Data Clean Room—Trabalhando com fontes

Os dados dentro das fontes devem atender a estes requisitos:

• Data e hora:
  • Formato: aaaa-MMM-dd hh:mm:ss (por exemplo, 2023-APR-18 15:30:35)
  • Fuso horário: UTC
• Números: máximo 2 dígitos após a vírgula decimal
• Comprimento da string: máximo de 256
• Limitações de caracteres
  • Para nomes de campo (cabeçalhos de coluna): sem espaços ou caracteres especiais
  • Todos os outros dados: sem limitações (todos os caracteres são válidos)

Além dos dados compartilhados para processamento, as tabelas de origem no BigQuery ou Snowflake devem incluir 2 colunas adicionais – uma para data e outra para versão:

• Data:
  • Cabeçalho da coluna: dt
  • Tipo de coluna: data
  • Formato dos dados: aaaa-mm-dd (por exemplo, 2023-04-18)
  • Adicional: as tabelas do BigQuery devem ser particionadas por esta coluna
• Versão:
  • Cabeçalho da coluna: v
  • Tipo de coluna: string
  • Formato dos dados: número (por exemplo, 1, 2, 3, 10)
  • Importante! Uma nova versão de um relatório é acionada cada vez que o DCR detecta um novo valor nesta coluna. Para garantir a integridade do seu relatório, certifique-se de preencher a tabela de origem com um conjunto completo de dados sempre que o valor da coluna for alterado.

Os arquivos de origem armazenados no Amazon S3 ou GCS devem atender a estes requisitos de nome e formato de arquivo:

• O nome do arquivo deve estar em conformidade com os requisitos de nomenclatura DCR
• Formato CSV ou GZIP
  • O arquivo subjacente à compressão GZIP deve ser um arquivo CSV.
• Número de arquivos de fonte de dados por pasta de dados:
  • CSV: máximo 1
  • GZIP: no máximo 1 arquivo em uma única parte. Arquivos GZIP de várias partes são compatíveis quando nomeados da seguinte maneira: filename_part01.gzip, filename_part02.gzip, etc.

1. Vá para a aba Fontes do Data Clean Room.
2. Clique no botão + Nova fonte.
   A página Nova fonte abre.
3. Insira o nome da fonte no canto superior esquerdo.
   • Esse pode ser qualquer nome exclusivo que ajudará você a identificar a fonte na plataforma DCR. Ele não precisa corresponder ao nome do arquivo.
   • Importante! Certifique-se de que o nome da fonte é diferente de todas as outras fontes em sua conta ou você não poderá salvá-la.
   • Requisitos do nome da fonte:
     • Comprimento: 2-80 caracteres
     • Caracteres válidos:
       • letras (A-Z, a-z)
       • números (0-9), não podem ser o primeiro caractere de um nome; 
     • Caracteres inválidos:
       • espaços
       • todos os outros símbolos ou caracteres especiais

Para especificar a localização da fonte:

1. Selecione a conexão na qual a fonte será (ou foi) criada.
   • Se não houver conexões definidas em sua conta, a caixa de diálogo Nova conexão será aberta, solicitando que você crie uma. Siga estas instruções para criá-la.
   • Se você tiver conexões existentes, mas quiser usar uma nova, clique no botão  para abrir a caixa de diálogo Nova conexão. Siga estas instruções para criá-la.
2. Continue com as instruções relevantes abaixo com base na localização dos dados de sua fonte.

Locais de origem no BigQuery

Para concluir a especificação do local de origem para origens do BigQuery:

1. Selecione o conjunto de dados no qual a tabela de origem está localizada.
2. Selecione a tabela na qual os dados de origem estão localizados.

As listas nas quais você faz essas seleções contêm os conjuntos de dados e tabelas disponíveis, respectivamente, no projeto do BigQuery que você especificou ao criar a conexão.

Locais de origem no Snowflake

Para concluir a especificação do local de origem para fontes do Snowflake:

1. Selecione o compartilhamento que contém os dados de origem.
2. Selecione o esquema no qual a tabela de origem está localizada.
3. Selecione a tabela na qual os dados de origem estão localizados.

As listas das quais você faz essas seleções contêm os compartilhamentos, esquemas e tabelas, respectivamente, na conta do Snowflake que você especificou ao criar a conexão.

Locais de origem em buckets de armazenamento em nuvem

Os locais de origem no Amazon S3 ou GCS consistem no bucket de armazenamento em nuvem especificado pela conexão e no caminho da pasta subjacente do qual o DCR lê o arquivo de origem sempre que ele é atualizado. 

Depois de especificar a conexão, a AppsFlyer pode gerar automaticamente o caminho da pasta subjacente necessária como parte do processo de criação da fonte.

• Permitir que a AppsFlyer gere as pastas facilita o processo. No entanto, você pode optar por criá-las manualmente, de acordo com as instruções detalhadas aqui.

Se a AppsFlyer gera as pastas, a única informação adicional necessária é o nome que você deseja dar à pasta fonte. (Esta é a pasta de nível superior na qual você atualiza a fonte cada vez que deseja utilizá-la para executar uma nova versão do relatório) Você também pode indicar se deseja que a pasta fonte seja criada abaixo de uma pasta principal – frequentemente chamada de entrada.

Para concluir a especificação de um local de origem em um bucket de armazenamento em nuvem, insira o nome da pasta de origem.

• Por padrão, o nome da pasta fonte exibida:
  • É baseado no nome que você forneceu à fonte. Você pode mudar o nome da pasta para atender às suas necessidades, desde que esteja de acordo com os requisitos de nomenclatura do DCR .
  • Indica que será gerado dentro de uma pasta principal denominada entrada. Esta pasta serve como pasta principal para todas as fontes que você carrega para o DCR.
    • A pasta entrada não é necessária, e você pode removê-la ou dar-lhe um nome diferente, desde que esteja de acordo com os requisitos de nomenclatura do DCR.
    • Embora esta pasta não seja necessária, ter uma pasta entrada (ou uma pasta equivalente com um nome diferente) é considerado uma boa prática. É ainda mais recomendado quando você estiver usando o mesmo bucket de armazenamento em nuvem para carregar arquivos de dados (entrada) e receber relatórios (saída).

Para todas as fontes que você compartilha com o DCR para processamento, a AppsFlyer precisa saber como cada campo de dados deve ser usado para criar relatórios. A definição da estrutura de origem consiste em:

• Carregar os campos de origem
• Categorizar cada campo (coluna) como um dos seguintes tipos:
  • Identificador: campo que identifica um usuário de aplicativo exclusivo (exemplos podem incluir CUID, AppsFlyer ID, etc.)
    • O objetivo principal dos identificadores no contexto do DCR é unir as fontes de dados para que os dados do usuário correspondentes possam ser combinados.
  • Dimensão: um atributo pelo qual você categoriza os usuários do aplicativo (exemplos podem incluir localização, data de instalação, campanha, etc.)
  • Métrica: dados numéricos que você coletou com relação a um usuário de aplicativo (exemplos podem incluir receita, número de aberturas do aplicativo, LTV, etc.)
    • Um campo de dados identificado como métrica deve conter apenas valores numéricos.

Carregar campos de origem

Carregue os campos de origem usando as instruções relevantes abaixo:

Fontes de data warehouses

Para carregar campos de uma origem localizada em um data warehouse (BigQuery ou Snowflake), clique no botão  .

Fontes de bucket de armazenamento em nuvem

Para carregar campos de uma origem localizada em um bucket de armazenamento em nuvem (Amazon S3 ou GCS), você deve carregar um arquivo de origem de protótipo.

Para fins de definição da estrutura da fonte: 

• Você pode carregar uma versão protótipo da fonte a partir de um arquivo local.
  • Se você selecionar esta opção, a AppsFlyer sempre cria automaticamente o caminho da pasta de fonte.

                                                                - or -

• Você pode carregar uma versão protótipo do arquivo de origem diretamente de sua conexão.
  • Se você selecionar esta opção, há uma opção adicional a ser feita:
    • Permita que a AppsFlyer crie automaticamente a estrutura da pasta fonte; ou
    • Crie manualmente a estrutura da pasta fonte

Para carregar seu protótipo de arquivo fonte, siga as instruções na aba correspondente abaixo:

Categorizar campos

Depois de carregar os campos, a AppsFlyer analisa o arquivo e uma lista de todos os campos de dados (colunas) é exibida na lista Campos disponíveis.

Para categorizar os campos:

1. Selecione um ou mais campos na lista Campos disponíveis à esquerda e use os botões no meio da tela para classificá-los como identificadores, dimensões ou métricas.
   • Quando um campo é categorizado, ele é exibido na lista de categorias relevante no lado direito da tela.
   • Você pode usar a barra de busca para pesquisar os campos das listas.
   • Para remover um campo de uma categoria para a qual ele foi designado, selecione-o na lista de categorias relevantes e use o botão Remover para retorná-lo à lista Campos disponíveis.
2. Repita este processo até que você tenha categorizado cada campo que deseja incluir nos relatórios do DCR.
   • Não é preciso categorizar cada campo na lista Campos disponíveis. Entretanto, um campo deve ser categorizado para que seja utilizado posteriormente em um relatório.
3. Se você editar a fonte antes de salvá-la e quiser usar campos dos dados de fonte editados, clique no link Recarregar campos na parte inferior da lista Campos disponíveis.
   • Observe que recarregar a fonte irá substituir os nomes dos campos na lista Campos disponíveis. Quaisquer campos categorizados anteriormente permanecerão nas listas Identificadores, Dimensões, ou Métricas.
   • Se um campo categorizado anteriormente não for encontrado nos dados de origem recarregados, ele ainda será exibido na lista de categorias relevantes, mas será marcado com um ícone de erro.

1. [Opcional] Clique para verificar a existência de erros no formato ou validade dos campos fonte.
2. Clique em Salvar para salvar a fonte.

   A fonte é criada e uma mensagem de confirmação é exibida.

   • Se você carregou a fonte de um arquivo local, salvar a fonte aciona a criação automática da estrutura da pasta, e a mensagem de confirmação exibida inclui um link para a pasta fonte.

   A nova fonte é exibida na lista de todas as fontes existentes na aba Fontes do Data Clean Room.

A estrutura das subpastas aninhadas é a seguinte:

• Dentro de cada pasta de fonte de dados --> 1 subpasta para cada data ("pasta de data")
  • Formato: dt=aaaa-mm-dd/
  • Exemplo: dt=2022-12-15/
• Dentro de cada pasta de datas --> 1 subpasta para cada versão naquela data ("pasta de versões")
  • Formato: v=n/
  • Exemplo: v=1/
  • Observação: a pasta da versão é necessária mesmo que você só faça o upload do arquivo uma vez por dia.
• Dentro de cada pasta de versão --> 1 subpasta para indicar a localização dos dados ("pasta de dados")
  • Formato: data/
  • A pasta de dados é o local para o qual o arquivo da fonte é carregado.

Na maioria dos casos, você usaria chamadas de API ou outros meios programáticos disponíveis para criar automaticamente as pastas de data/versão/dados cada vez que o arquivo da fonte de dados fosse carregado. Para informações adicionais, consulte a referência de API para seu serviço de nuvem: AWS, GCS.

Após concluir o upload de um arquivo de fonte de dados para a pasta de dados, você deve fazer o upload de um arquivo vazio chamado _SUCCESS para a pasta de versão. Isso alerta a AppsFlyer de que um novo arquivo está disponível para ser processado. Na maioria dos casos, você usaria uma API script para gerar e fazer o upload automático desse arquivo.

Importante! O upload do arquivo _SUCCESS é feito para a pasta versão, fora da pasta de dados.

O nome do arquivo _SUCCESS:

• Deve estar em EM MAIÚSCULAS
• Deve ser precedido por um underline (_)
• Não deve ter uma extensão de arquivo

Para arquivos GZIP de multi-partes:

• Deve ser feito upload de apenas um arquivo _SUCCESS para todas as partes do arquivo.
• O upload do arquivo _SUCCESS deve ser feito somente depois que todos os uploads de partes do arquivo estiverem completos.

Após o upload dos arquivos da fonte em 2 dias (e após criar programaticamente pastas de data/versão/dados e arquivos _SUCCESS), sua estrutura de bucket/pasta deve ficar assim:

Para editar o nome da fonte:

1. Vá para a aba Fontes do Data Clean Room.
2. Na lista de fontes, passe o mouse sobre a fila da fonte que você deseja editar.
3. Clique no botão de edição que aparece no lado direito da fila.
4. Na página Editar fonte, edite o nome da fonte.
5. Clique no botão Salvar para salvar a fonte com o novo nome ou Cancelar para desfazer suas alterações.

Para editar a estrutura da fonte:

1. Vá para a aba Fontes do Data Clean Room.
2. Na lista de fontes, passe o mouse sobre a fila da fonte que você deseja editar.
3. Clique no botão de edição que aparece no lado direito da fila.
4. Na página Editar fonte, os campos que anteriormente eram categorizados como identificadores, dimensões ou métricas serão exibidos nas listas de categorias relevantes no lado direito da tela.
5. Você pode mover um campo previamente categorizado para uma categoria diferente sem recarregar os campos do arquivo fonte. Para fazer isso:
   1. Primeiro, selecione-o na lista de categorias relevantes e use o botão Remover para devolvê-lo à lista Campos disponíveis.
   2. Depois, selecione-o na lista Campos disponíveis e use os botões no meio da tela para classificá-lo como identificador, dimensão ou métrica.
6. Para trabalhar com campos no arquivo fonte que ainda não tenham sido categorizados, eles devem ser recarregados a partir do local de origem ou de um arquivo local. Faça esta seleção clicando no botão relevante Recarregar campos na parte inferior da lista Campos disponíveis.
7. A AppsFlyer analisa o arquivo, e uma lista de todos os campos de dados (colunas) anteriormente não categorizados é exibida na lista Campos disponíveis.
   • Os campos que anteriormente eram categorizados como identificadores, dimensões ou métricas ainda serão exibidos nas listas de categorias relevantes no lado direito da tela.
   • Se um campo previamente categorizado não for encontrado no arquivo fonte recarregado, ele ainda será exibido na lista de categorias relevante, mas será marcado com um ícone de erro.
8. Selecione um ou mais campos na lista Campos disponíveis à esquerda e use os botões no meio da tela para classificá-los como identificadores, dimensões ou métricas.
9. Quando todas as alterações necessárias forem feitas, clique no botão Salvar para salvar a fonte com a estrutura atualizada ou Cancelar para desfazer suas alterações.

1. Vá para a aba Fontes do Data Clean Room.
2. Na lista de fontes, passe o mouse sobre a fila da fonte que você deseja excluir.
3. Clique no botão de exclusão  exibido no lado direito da linha.
4. No diálogo, confirme que você deseja excluir a fonte.
   • Não é possível eliminar uma fonte que está sendo usada por um relatório. Se este for o caso, uma mensagem listará os relatórios nos quais a fonte está sendo utilizada. Para apagar a fonte, você pode:
     • Excluir os relatórios em que está sendo usada; ou
     • Remover os campos de origem das definições dos relatórios em que são utilizados.

Em geral, é mais fácil permitir que a AppsFlyer gere automaticamente a estrutura de pastas necessária como parte do processo de criação da fonte. No entanto, se você deseja criar essas pastas manualmente, pode fazer isso da seguinte maneira.

Crie uma pasta de chave DCR

Para garantir segurança máxima, a pasta diretamente abaixo do bucket (a "pasta de chave DCR") deve ser nomeada com a chave DCR alfanumérica de 8 caracteres atribuída à sua conta (por exemplo, 01bcc5fb). Observe que isso é diferente de qualquer outra senha ou chave associada à sua conta da AppsFlyer.

A pasta de chaves DCR geralmente é criada manualmente usando a interface de seu serviço em cloud selecionado.

Para obter a chave DCR da sua conta, clique no botão da chave DCR na parte superior da página principal do DCR.

Após criar a pasta de chaves DCR, sua estrutura de bucket/pasta deve ficar assim:

Pasta de entrada de nível superior

Embora não seja necessário, a prática recomendada é criar uma pasta de entrada de nível superior diretamente abaixo da pasta de chaves DCR. Esta pasta será dedicada aos arquivos que você fizer upload para o DCR.

A pasta de entrada de nível superior geralmente é criada manualmente usando a interface de seu serviço em cloud selecionado.

• Esta prática é ainda mais importante caso você use o mesmo bucket tanto para fazer o upload de arquivos de dados (entrada) quanto para receber relatórios (saída).
• Você pode nomear essa pasta como quiser, desde que ela esteja de acordo com as exigências de nomenclatura do DCR. Para facilitar a identificação, ela costuma ser denominada como input/.

Depois de criar a pasta de entrada de nível superior, sua estrutura de bucket/pasta deve ficar assim:

Pasta de segundo nível para cada fonte de dados

Você pode fazer o upload regular de diferentes arquivos de fontes de dados para processamento no DCR. A cada uma dessas fontes de dados deve ser atribuída uma pasta separada ("pastas de fontes de dados").

Assim, por exemplo, se você planeja fazer o upload de 2 arquivos no DCR para processamento, todos os dias: BI-data.csv e CRM-data.gzip, você atribuiria uma pasta para cada uma dessas fontes de dados. Você pode escolher chamar essas pastas BI-data/ e CRM-data/.

As pastas das fontes de dados geralmente são criadas manualmente usando a interface de seu serviço em cloud selecionado.

Após criar 2 pastas de fonte de dados, sua estrutura de bucket/pasta deve ficar assim:

Em cada pasta de fonte de dados, subpastas aninhadas por data e versão devem ser criadas sempre que a fonte for atualizada.