> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/pt-br/reporting/reporting-faq.md). # Perguntas frequentes ### A Reporting API é segura? Todos os dados armazenados no BigQuery são criptografados em repouso e em trânsito. Isso significa que, quando os dados são armazenados nos servidores do Google e quando são transmitidos entre esses servidores e o cliente, eles ficam protegidos por criptografia forte. Além disso, o BigQuery possui controles de acesso integrados que permitem restringir o acesso aos seus dados com base em funções e permissões de usuário. Isso significa que especificamos exatamente quem tem acesso aos seus dados e quais ações eles podem realizar neles. O BigQuery também suporta autenticação e autorização por meio de mecanismos padrão, como OAuth 2.0 e chaves de API. A infraestrutura do Google é projetada para proteger contra ameaças comuns, como ataques de negação de serviço, violações de dados e acesso não autorizado. Isso é feito usando várias medidas de segurança, como firewalls, sistemas de detecção de intrusão e auditorias de segurança regulares, e a API do BigQuery é projetada com a segurança em mente e emprega uma série de medidas para garantir que seus dados estejam protegidos em todos os momentos. ### Com que frequência os dados são atualizados? Diariamente. A atualização começa à meia-noite UTC+0 com um tempo máximo de atualização de 12 horas. A atualização cobre todos os dados recebidos até a meia-noite (UTC+0) do dia anterior. ### Qual é a abrangência histórica dos dados? Todos os dados históricos aprovados para uma determinada organização estarão disponíveis. ### Se eu for um usuário do Direct Access, como me conecto? Estando já no GCP, será simples. Basta fazer login e tentar consultar as tabelas relevantes por meio da UI ou API.
Insights IAM UI
#### Recebo um erro "User does not have bigquery.jobs.create permission in project" – o que estou fazendo de errado? Para as contas que você nos forneceu, Epsilon Retail Media concedeu privilégios de visualizador do BigQuery aos conjuntos de dados relevantes. Isso permitirá que você leia as tabelas dentro deles. No seu projeto, algumas coisas precisam acontecer para realmente consultar essas tabelas remotas. Vamos assumir o seguinte: * Seu projeto = "client-project-123456" * Seu usuário = * Epsilon Retail Media dataset: "insight-platform-external-iam.client\_insight\_reporting" Você precisa: 1. Conceder a a permissão bigquery.jobs.create dentro do projeto client-project-123456 (não no projeto Epsilon Retail Media ). Você pode fazer isso atribuindo a função BigQuery Job User. 2. Ao executar uma consulta, você deve executá-la dentro do seu projeto (pois você só tem permissões para ler o conjunto de dados dentro do projeto Epsilon Retail Media não executar consultas dentro dele). Veja como isso pode acontecer usando um exemplo simples de comando do cloud shell (executando como ): ```bash bq query --use_legacy_sql=false --project_id client-project-123456 'SELECT * FROM insight-platform-external-iam.client_insight_reporting.campaign limit 10;' ``` Observe que o projeto do cliente está definido como o seu projeto, não como insight-platform-external-iam. Uma abordagem semelhante deve ser adotada com quaisquer outras ferramentas usadas. Consulte a documentação das ferramentas fornecidas para obter mais informações, bem como a documentação online do GCP para obter dicas! #### Os Epsilon Retail Media dados não estão no meu local, como posso trazer os dados para o meu local? Há muitas possibilidades, mas é fácil criar conjuntos de dados no mesmo local que o nosso e, em seguida, fazer transformações, consultas etc., em tabelas nesses conjuntos de dados e copiar isso para seu próprio local preferido.
Location Guide
Existem muitas maneiras de copiar entre locais usando a UI, a ferramenta de linha de comando BQ e a própria API. Para obter mais informações, consulte estas páginas de documentação do Google Cloud: * [Manage datasets | BigQuery](https://cloud.google.com/bigquery/docs/managing-datasets) * [referência da ferramenta de linha de comando bq](https://cloud.google.com/bigquery/docs/bq-command-line-tool) * [Copiar uma tabela de origem única](https://cloud.google.com/bigquery/docs/copying-datasets) ### Se eu for um usuário de API fora do GCP, como me conecto? Epsilon Retail Media fornecerá a você as credenciais relevantes em um JSON que você pode incorporar ao seu mecanismo de autenticação. ### Posso depurar consultas usando apenas a Reporting API (não a UI do BigQuery)? Sim, a API do BigQuery retornará um código indicando se houve um problema e as mensagens de erro também estarão disponíveis. ### Posso estimar o custo de uma consulta? Sim, a API possui um mecanismo para obter uma estimativa em bytes do que a consulta examinará se for executada. Você pode usar essa estimativa multiplicada pela frequência com que chama a consulta para entender o quão perto chegará da cota. Mais informações podem ser encontradas na documentação do GCP. [Dry run query | BigQuery | Google Cloud](https://cloud.google.com/bigquery/docs/samples/bigquery-query-dry-run) ### E se eu exceder o limite de cota? Consulte seu contrato com a Epsilon Retail Media para entender qual é a sua cota. Se não estiver especificamente definida, o padrão será 10 TB de varredura de dados de consulta por mês. Seu contrato também pode envolver um número máximo de chamadas de API por dia. Se isso não estiver especificamente definido, o padrão será 100 chamadas de API por dia. Caso você exceda sua cota (seja de varredura de dados ou número de chamadas), entraremos em contato para entender seus casos de uso. Custos por excesso podem ser aplicados dependendo do seu contrato. Em caso de uso indevido grave fora dos termos do seu contrato (ou limites padrão), reservamo-nos o direito de suspender o acesso. ### Qual é um exemplo de uso da Reporting API? Abaixo estão alguns exemplos usando métodos comuns. #### Google SDK para Python Este exemplo irá: 1. Conectar ao BigQuery 2. Executar a consulta 3. Gravar o resultado em um csv ```python import google.cloud.bigquery as bq import pandas as pd bq_client = bq.Client.from_service_account_json(".json") job_config = bq.QueryJobConfig(allow_large_results=True) query_job = bq_client.query( 'SELECT count(1) FROM insight-platform-external-iam._insight_reporting.campaign LIMIT 1000', job_config=job_config) df = query_job.to_dataframe(create_bqstorage_client=False) df.to_csv(r"C:\Users\\.csv", index=False) print("Run Complete") ``` Outros métodos estão disponíveis para estimar bytes examinados etc. antes de executar a consulta. Consulte a documentação do BigQuery [BigQuery API | Google Cloud](https://cloud.google.com/bigquery/docs/reference/rest) Se não estiver no GCP, pode referenciar um arquivo de credencial JSON por meio de uma variável de ambiente. #### API genérica para Python ```python import csv import requests from google.oauth2 import service_account PROJECT_ID = "insight-platform-external-iam" DATASET = "" END_POINT = f"https://bigquery.googleapis.com/bigquery/v2/projects/{PROJECT_ID}/queries" QUERY = f""" SELECT supplier_id, campaign_id, sum(ad_spend) as ad_spend, sum(clicks) as clicks FROM `{PROJECT_ID}.{DATASET}.realised_ad_agg` WHERE ingressed_at BETWEEN '2022-09-01' and '2022-12-31' group by 1,2 """ def get_token(): # With service account credentials = service_account.Credentials.from_service_account_file('./secrets/service-account.json') scoped_credentials = credentials.with_scopes(['https://www.googleapis.com/auth/cloud-platform']) # Do token request def req( method, url, headers, body, **kwargs): resp = requests.post(url, headers=headers, data=body) return type('obj', (object,), {'data' : resp.text, 'status': 200}) scoped_credentials.refresh(req) return scoped_credentials.token def run_job(token): resp = requests.post( END_POINT, json={ "query": QUERY, "useLegacySql": False }, headers={ "Content-Type": "application/json", "Authorization": f"Bearer {token}" } ) return resp.json()['jobReference']['jobId'] def get_query_results(job_id, token): status_endpoint = f'{END_POINT}/{job_id}?location=australia-southeast1' completed = False while not completed: response = requests.get(status_endpoint, headers={ "Content-Type": "application/json", "Authorization": f"Bearer {token}" }) completed = response.json()['jobComplete'] data = response.json() rows = data['rows'] columns = [c['name'] for c in data['schema']['fields']] return rows, columns def extract(): token = get_token() job_id = run_job(token) rows, columns = get_query_results(job_id, token) with open('results.csv', 'w', newline='') as f: writer = csv.writer(f) writer.writerow(columns) for row in rows: writer.writerow([i['v'] for i in row['f']]) extract() ``` ### E se eu estiver na AWS etc. e não no Google Cloud, ainda posso autenticar e usar a API? Sim, funcionará. Forneceremos credenciais de conta de serviço e você poderá referenciá-las em sua aplicação. Aqui está um exemplo. ```python # TODO(developer): Set key_path to the path to the service account key # file. # key_path = "path/to/service_account.json" credentials = service_account.Credentials.from_service_account_file( key_path, scopes=["https://www.googleapis.com/auth/cloud-platform"], ) token = credentials.token # use the token to do the API calls # ... # headers: Bearer ${token} # ... ``` ### Como posso determinar qual é a localização de cada conjunto de dados compartilhado comigo? Esta chamada de API informará em qual localização cada conjunto de dados está. `GET https://bigquery.googleapis.com/bigquery/v2/projects/insight-platform-external-iam/datasets` ```json { "kind": "bigquery#datasetList", "etag": "RLU1Ww9C5FdhlcIuRHjW0A==", "datasets": [ { "kind": "bigquery#dataset", "id": "insight-platform-external-iam:acme_insight_reporting", "datasetReference": { "datasetId": "acme_insight_reporting", "projectId": "insight-platform-external-iam" }, "location": "australia-southeast1" }, { "kind": "bigquery#dataset", "id": "insight-platform-external-iam:acme_acme_analytics", "datasetReference": { "datasetId": "acme_acme_analytics", "projectId": "insight-platform-external-iam" }, "location": "us-central1" } ] } ``` ### Alguma dica de melhores práticas? De modo geral, se você pretende ser um usuário assíduo dos dados, particularmente se tiver acesso aos dados não agregados (solicitações/anúncios realizados/pedidos/atribuição aprimorada etc.), é melhor copiar (armazenar) as tabelas em seu próprio data warehouse e, ENTÃO, implementar as consultas para a lógica de negócios necessária nessas cópias. Usuários eventuais podem optar por consultar as tabelas diretamente para resultados específicos. É importante permanecer abaixo da cota permitida para garantir um funcionamento contínuo. Observe também que cada consulta pode baixar no máximo 1 GB; caso contrário, uma mensagem de erro será recebida. Caso seja necessário um download muito grande, execute várias consultas menores (por exemplo, um subconjunto de dados por dia ou fornecedor etc.). ### E se eu precisar de ajuda para elaborar instruções SQL adequadas? Abra um chamado especificando a consulta que tentou fazer e podemos ajudar a analisá-la - retornaremos com quaisquer comentários que possamos ter. ### Alguma dica para usar o pacote Pandas? O Pandas é uma das ferramentas de análise mais populares. Para fazê-lo funcionar, as dependências pandas-gbq e pydata-google-auth precisam estar instaladas. O trecho abaixo é um exemplo prático de como ler dados de uma tabela do BigQuery. ```python import pandas as pd from google.oauth2 import service_account credentials = service_account.Credentials.from_service_account_file('path/to/the/credential/file') query = 'select * from project.dataset.table' dat = pd.read_gbq( query, project_id='project_id', credentials=credentials ) ``` Mais informações sobre a função do Pandas podem ser encontradas [aqui](https://pandas.pydata.org/docs/reference/api/pandas.read_gbq.html). ### Alguma dica para usar o pacote PySpark? Assumindo que você tenha um ambiente PySpark funcional, você precisa fornecer o arquivo jar correto para o conector do BigQuery adequado à sua versão do PySpark. Por exemplo, o PySpark 3.2.\* requer o spark-3.2-bigquery-0.30.0.jar. A lista dos arquivos jar, bem como trechos de código práticos e parâmetros, podem ser encontrados [aqui](https://github.com/GoogleCloudDataproc/spark-bigquery-connector). O trecho de código abaixo fornece um exemplo de como executar uma consulta. ```python from pyspark.sql import SparkSession spark = SparkSession.builder.appName('BigNumeric').config('spark.jars', 'spark-3.2-bigquery-0.30.0.jar').getOrCreate() spark.conf.set('credentialsFile', 'path/to/the/credential/file') spark.conf.set('viewsEnabled', 'true') spark.conf.set('materializationProject', 'yourMaterializationProject') spark.conf.set('materializationDataset', 'yourMaterializationDataset') query = 'select * from project.dataset.table' df = spark.read.format('bigquery').option('query', query).load() df.show() ``` IMPORTANTE: O parâmetro viewsEnabled deve ser true. Os dados nas exibições são materializados em tabelas temporárias antes de serem lidos pelo PySpark, onde a permissão bigquery.tables.create é necessária. Portanto, você precisa fornecer o materializationProject e o materializionDataset onde o usuário tenha acesso de escrita. ### Estou recebendo um erro exigindo um filtro na consulta? Para uma tabela particionada, um filtro é obrigatório; sem ele, uma mensagem de erro como a abaixo será exibida: > Cannot query over table ‘dataset\_id.table\_id' without a filter over column(s) ‘partitioned\_column' that can be used for partition elimination Para resolver o erro, basta adicionar um filtro razoável cobrindo o intervalo de destino, por exemplo, ```sql -- this query returns all records available since yesterday select * from dataset_id.table_id where ingressed_at >= date_sub(current_date, interval 1 day) ``` Para descobrir por qual coluna a tabela está particionada (como ingressed\_at no exemplo acima), consulte a descrição da tabela fornecida. ### Como posso solicitar acesso? #### Processo Um chamado deve ser aberto e os critérios de elegibilidade devem ser acordados por escrito. Trabalharemos com o Candidato potencial para identificar o nível de acesso e as configurações de segurança necessários e determinar quais cotas e custos podem se aplicar. #### Critérios de Elegibilidade Um Candidato deve cumprir os seguintes Critérios para ser considerado elegível para acesso à Reporting API: - **Geral** 1. O Candidato só pode solicitar acesso a dados de Epsilon Retail Media namespaces e equipes dos quais ele já seja membro ou tenha acesso geral. O Candidato deve especificar para qual dos seguintes cenários está se candidatando (e fornecer prova do acesso existente): 1. Nível de ambiente (uma implementação inteira da Epsilon Retail Media plataforma é dedicada ao Candidato). 2. Nível de Namespace (o Candidato tem permissão para ver todas as equipes, tanto do varejista quanto do fornecedor, em um Namespace individual ou lista de Namespaces). 3. Nível de grupo ou ID de Equipe do Varejista específico. 4. Nível de grupo ou ID de Equipe do Fornecedor específico. 1. além disso, um Integrador pode acessar um nível de grupo ou ID de Equipe do Fornecedor específico MAIS os Catálogos de Produtos do Varejista completos, onde acordado por um Varejista caso a caso. 2. Dados de Fato Transacionais só podem ser fornecidos a Candidatos que sejam elegíveis para os Critérios Gerais 1a ou 1b. 3. Os Candidatos que não se qualificarem para dados de Fato transacionais receberão acesso apenas a dados de Fato pré-agregados. Os dados serão agregados em resumos diários (com UTC+0 como o fuso horário da agregação). 4. Os Candidatos elegíveis apenas para os Critérios Gerais 1d não podem receber dados de Solicitação de Anúncio (em oposição aos dados de Anúncios Realizados, que serão fornecidos). Os dados do Produto serão fornecidos para os Produtos específicos que estão sendo anunciados nos Anúncios Realizados pelo Fornecedor, EXCETO para Integradores que podem receber Catálogos de Produtos do Varejista, onde acordado por um Varejista caso a caso. 5. Os dados dimensionais têm garantia de incluir apenas as versões atuais dos registros em questão. Espera-se que o rastreamento de alterações históricas seja implementado pelo Candidato conforme necessário. 6. Os dados são atualizados diariamente e serão atualizados o mais tardar às 12:00 UTC+0 para dados até o dia anterior concluído em UTC+0, inclusive. 7. Entende-se que o acesso é de natureza somente leitura. A API não deve ser usada para criar objetos em nosso data warehouse para qualquer finalidade. 8. Qualquer combinação com outras fontes de dados deve ser feita no próprio ambiente do Candidato. 9. O Candidato deve ter um SDK (ou equivalente) disponível para acessar a Google BigQuery API. 10. O Candidato tem bom conhecimento de SQL. 11. O Candidato estará familiarizado com os conceitos da Epsilon Retail Media e, caso não esteja, fará arranjos para que o treinamento padrão do produto seja fornecido por meio do seu Gerente de Suporte ao Cliente ou Gerente de Contas Técnico. 12. Com base nos documentos fornecidos, espera-se que o Candidato desenvolva suas próprias soluções. Se for encontrado um problema em que o SQL não esteja se comportando como esperado de acordo com a documentação, um chamado deve ser aberto por meio dos canais de suporte regulares. As seguintes informações devem ser fornecidas. 1. A conta por meio da qual a conexão está sendo feita. 2. O SQL exato que está sendo chamado. 3. Uma descrição detalhada de quais mensagens de erro ocorrem. 13. Se o Candidato for um Varejista, é necessário que Impressões/Cliques/Pedidos sejam fornecidos para a Epsilon Retail Media plataforma de modo que uma visão completa do ciclo de vida do Anúncio possa ser estabelecida. 14. De tempos em tempos, Epsilon Retail Media reservam-se o direito de alterar o schema. Essas alterações geralmente envolvem a adição de novas colunas às tabelas e visualizações existentes e seriam compatíveis com versões anteriores. Os Candidatos devem estruturar seu SQL para nomear colunas em vez de usar caracteres curinga etc. Caso uma alteração envolva a descontinuação de uma coluna ou tabela, Epsilon Retail Media fornecerá pelo menos 12 semanas de aviso prévio sobre a alteração antes que ela seja implementada. As notificações ocorrerão por meio de comunicações padrão de lançamento feitas aos usuários da plataforma. Não é obrigatório que um Candidato seja um usuário existente do Google Cloud Platform (GCP); no entanto, existem Critérios adicionais dependendo se o Candidato é ou não um usuário do GCP. **Candidato Não-GCP** Salvo acordo em contrário, Epsilon Retail Media fornecerá credenciais para uma única conta de serviço em nosso ambiente para o Candidato. Salvo acordo em contrário, as seguintes condições padrão se aplicam: 1. Um máximo de 100 chamadas de API por dia. 2. Não mais do que 10 TB de varreduras de dados por mês (observe que a API tem uma maneira de estimar o tamanho da varredura da consulta antes da execução, consulte a documentação do Google [Dry run query | BigQuery | Google Cloud](https://cloud.google.com/bigquery/docs/samples/bigquery-query-dry-run)). 3. Se os Critérios 1 e/ou 2 do Candidato Não-GCP forem excedidos, Epsilon Retail Media reservam-se o direito de suspender o acesso a nosso critério exclusivo. 4. Nenhuma chamada de API individual pode baixar mais de 1 GB de dados por vez. #### Como faço para decodificar o arquivo da conta de serviço? As credenciais da conta de serviço serão fornecidas a você em um formato codificado em base64 para transmissão segura. Você precisará decodificar isso antes de usá-lo. Aqui estão exemplos de como decodificar o arquivo: Usando bash: ```bash # Replace encoded-credentials.txt with the file containing your base64 encoded credentials base64 -d encoded-credentials.txt > service-account.json ``` Usando Python: ```python import base64 # Replace encoded_credentials with your base64 encoded string with open('encoded-credentials.txt', 'r') as f: encoded_credentials = f.read() decoded_credentials = base64.b64decode(encoded_credentials) with open('service-account.json', 'wb') as f: f.write(decoded_credentials) ``` Após a decodificação, você terá um `service-account.json` arquivo que você pode usar com as bibliotecas de cliente do BigQuery conforme mostrado nos exemplos anteriores. **Candidato GCP** Salvo acordo em contrário, o Candidato fornecerá Epsilon Retail Media detalhes de no máximo 5 contas GCP para que possamos atribuir o acesso necessário. Observe que a conta deve ter a função de Usuário de Job do BigQuery (roles/bigquery.jobUser) atribuída. As seguintes restrições se aplicam: 1. Um máximo de 100 chamadas de API por dia. 2. Se o Critério 1 do Candidato GCP for excedido, Epsilon Retail Media reservam-se o direito de suspender o acesso a nosso critério exclusivo. 3. Nenhuma chamada de API individual pode baixar mais de 1 GB de dados. ### Glossário #### Ambiente O nome do ambiente físico em que a Epsilon Retail Media plataforma está implantada. Cada um hospeda um ou mais namespaces. #### Namespace Um agrupamento lógico de todas as entidades que fazem parte de uma implementação da Epsilon Retail Media solução. Isso inclui equipes e todos os objetos pertencentes às equipes. Tipicamente, um namespace pode consistir em um varejista (equipe) e múltiplos fornecedores (equipes), juntamente com usuários para cada equipe e outras configurações relacionadas (varejistas possuem catálogos, fornecedores configuram campanhas etc). As equipes (e o que elas possuem) pertencem exclusivamente a um único namespace (nenhuma equipe pode existir em múltiplos namespaces). #### Usuário Identificador exclusivo de um usuário no Epsilon Retail Media sistema. Um único e-mail pode ter múltiplos userIds. Cada userId é exclusivo por namespace. Cada usuário terá um nome, sobrenome, e-mail e id. Um usuário pode ser membro e acessar múltiplas equipes na Epsilon Retail Media plataforma. #### Equipe Uma equipe dentro do Epsilon Retail Media sistema. Pode ser um fornecedor (anunciante) ou varejista. Equipes de fornecedores geralmente criarão campanhas, varejistas revisam campanhas e realizam funções administrativas. Um usuário no Epsilon Retail Media sistema pode ser membro de muitas equipes ou de apenas uma. Uma equipe geralmente terá usuários, campanhas e carteiras associadas a ela. #### Fornecedor Uma equipe de fornecedor dentro do Epsilon Retail Media sistema. Um fornecedor pode ser tipicamente uma empresa-mãe de marca ou uma série de equipes por marca individual. Os fornecedores geralmente mantêm campanhas, administram saldos de carteiras etc. #### Varejista Uma equipe de varejista dentro do Epsilon Retail Media sistema. A maioria dos namespaces terá apenas uma equipe de varejista. Os varejistas geralmente mantêm catálogos de produtos, revisam campanhas etc. #### Campanha Uma única campanha exclusiva configurada com uma estratégia de posicionamento e direcionamento para uma seleção específica de produtos. Por exemplo, uma campanha no Epsilon Retail Media sistema pode estar promovendo o produto A e B direcionando os termos de pesquisa 'chocolate' e 'chocolates' com um lance máximo de $ 0,60. Uma única equipe geralmente tem muitas campanhas. #### Catálogo Um catálogo de produtos exclusivo de um varejista no Epsilon Retail Media sistema. É típico para um varejista sincronizar apenas um catálogo de produtos com Epsilon Retail Media em um único namespace. Um catálogo terá uma lista de todos os produtos no catálogo do varejista, seu nome, marca, categorias e outros atributos relevantes que são ingeridos no Epsilon Retail Media sistema. #### Produto Um único produto exclusivo no Epsilon Retail Media sistema. Um produto terá um código de produto exclusivo sincronizado no catálogo de produtos. Um produto pode ter atributos como categoria, taxonomia, marca etc. #### Carteira Uma carteira no Epsilon Retail Media sistema armazena os fundos de um anunciante com o propósito de fazer pagamentos (por exemplo, pagar por anúncios realizados). Cada carteira tem um único código de moeda e só pode gastar em catálogos desse mesmo código de moeda. Uma carteira pertence a uma equipe. Uma equipe pode ter qualquer número de carteiras. Uma carteira pode ser arquivada. Arquivar uma carteira apenas a mostrará/ocultará na plataforma; uma carteira arquivada ainda pode gastar créditos. #### Livreiro de lançamentos Um registro de eventos que resultaram em uma transação no Epsilon Retail Media sistema. Isso é mais comumente eventos de anúncios, como impressões ou cliques para produtos patrocinados ou anúncios de banner (resultando em um débito). Isso também pode ser recargas e ajustes de saldos por um fornecedor (créditos). Cada evento terá um 'motivo', como Produtos Patrocinados, Anúncios de Banner, Recarga. #### Solicitação Uma solicitação feita ao Epsilon Retail Media sistema para anúncios. Na solicitação, o varejista especifica um posicionamento, bem como o contexto, como o de um cliente sessionId ou filtros relevantes para a solicitação. Dependendo da solicitação, Epsilon Retail Media enviará de volta anúncios de um AdType relevante (por exemplo, Categoria ou Termo de pesquisa) para o varejista renderizar para o cliente. #### Anúncio (Realizado) Um anúncio é um único evento de anúncio enviado de volta a um varejista para veicular ao seu cliente. Ele se torna um anúncio realizado quando o varejista retorna a confirmação de que o anúncio recebeu pelo menos uma impressão (confirmação explícita de que o anúncio foi realmente usado, ou seja, realizado). No Epsilon Retail Media sistema, cada anúncio terá um id de anuncio realizado exclusivo, que é uma referência para esse único evento exclusivo. #### Categoria Uma categoria é uma página no site do varejista como parte da taxonomia do site, como 'Padaria' ou 'Laticínios'. Um varejista geralmente solicita anúncios em uma página de categoria e especifica esse atributo relevante em sua solicitação para a Epsilon Retail Media. If Epsilon Retail Media tiver campanhas ativas e válidas para a Categoria, os anúncios serão retornados. #### SearchTerm Um termo de pesquisa inserido por um cliente no site do varejista. Esse termo de pesquisa é então enviado para a Epsilon Retail Media para solicitar anúncios relevantes. Se a Epsilon Retail Media tiver campanhas ativas e válidas para o termo de pesquisa, os anúncios serão retornados. #### Order Um pedido exclusivo no sistema do varejista sincronizado com a Epsilon Retail Media. Um único pedido pode ter vários itens de pedido dentro dele (assim como o carrinho de um cliente pode conter vários itens). Assim que o pedido de um cliente é concluído, eles são enviados para a Epsilon Retail Media para alimentar a atribuição da Epsilon Retail Media. O retorno sobre o valor gasto em anúncios (ROAS) e outros KPIs importantes podem ser fornecidos aos varejistas e anunciantes. #### Atribuição A atribuição é um processo operado no sistema da Epsilon Retail Media que atribui anúncios exibidos a um cliente a um pedido enviado. A jornada típica do cliente seria ver um anúncio (impressão), clicar nele (clique), adicioná-lo ao carrinho e comprar esse item (conversão). O pedido é 'atribuído' ao anúncio exclusivo em que o cliente clicou. Para que um pedido seja atribuído no sistema da Epsilon Retail Media , é necessário interagir com o anúncio (seja visto ou clicado, sujeito à integração), e o cliente tenha comprado um item relevante para o anúncio. Epsilon Retail Media geralmente usam um 'sessionId' para atribuir pedidos a anúncios, onde o varejista especifica um 'sessionId' em todos os pontos de contato relevantes da jornada de um anúncio. É assim que a Epsilon Retail Media consegue identificar que um único anúncio, exibido a um único cliente, resultou em um pedido específico. #### Datas Todos os dados são convertidos para o fuso horário UTC+0 se forem agregados. #### Limite As implementações da plataforma da Epsilon Retail Media geralmente envolvem o varejista solicitando mais anúncios do que realmente seriam impressionados (realizados). Do ponto de vista analítico, isso pode dar uma impressão imprecisa de como certas métricas estão realmente se comportando. Por exemplo, se for feita uma solicitação de 20 anúncios (AdType=Product) e a plataforma servir 2 anúncios em resposta, isso representa uma 'taxa de preenchimento' de 10% na solicitação (2 de 20). No entanto, se for entendido que, na prática, apenas 4 anúncios provavelmente serão usados (realizados), seria preferível interpretar isso como 50% preenchido (2 de 4). Daí a noção de limitação dentro dos relatórios. A limitação é definida por varejista, com um limite disponível para anúncios de produtos e outro para anúncios de banner (já que as solicitações de anúncios de produtos normalmente solicitarão e usarão muito mais anúncios do que os banners). Voltando ao exemplo, se o limite de produtos = 4 para o varejista, as métricas de solicitação reportariam da seguinte forma:- NumAdRequests = 1 NumAdsRequested = 20 CappedNumAdsRequested = 4 NumAdsServed = 2 CappedNumAdsServed = 2 Observe que, no caso de 5 anúncios serem exibidos (ou seja, os anúncios exibidos excederem o próprio limite), as últimas 2 métricas reportariam como:- NumAdsServed = 5 CappedNumAdsServed = 4 (reduzido de volta ao limite) Os limites não são obrigatórios. Caso eles não sejam especificados, os resultados com e sem limite serão os mesmos. #### Atribuição aprimorada A plataforma da Epsilon Retail Media realiza atribuições conforme descrito na seção Atribuição (veja acima). O subsistema de relatórios também pode detectar e sinalizar outros cenários de atribuição, dependendo do varejista (atribuição aprimorada). Os cenários são: * Atribuição de visualização da impressão * Um Pedido foi atribuído a um Anúncio que foi visualizado para o mesmo Produto na mesma ID de sessão (ou seja, foi uma impressão e não um clique). * Atribuição de clique Halo * Um Pedido foi atribuído a um Anúncio que foi clicado para um Produto pertencente ao mesmo nível de Halo na mesma ID de sessão. O nível de halo mais comum é a Marca (ou seja, o Produto do Anúncio e o Produto do Pedido são diferentes, mas pertencem à mesma Marca). Outros tipos de halo são possíveis dependendo da implementação. Por exemplo, o halo pode ser mais específico e exigir que o Anúncio e o Pedido sejam de Produtos que tenham uma Categoria comum, além de uma Marca comum. A taxonomia do varejista definida por Produto no Catálogo é usada para definir esse nível extra de detalhe no Halo. Versão: 1ace13f --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.citrusad.com/retail-media-interface/integration/pt-br/reporting/reporting-faq.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.