Data Clean Room—armazenamento em nuvem e configuração de arquivo de dados

Visão geral: configure buckets de serviços em cloud, caminhos de pastas e arquivos para uso no AppsFlyer Data Clean Room. Os buckets podem ser localizados no AWS S3, GCS, ou em ambos.

Visão geral

O Data Clean Room (DCR) da AppsFlyer permite que os anunciantes aproveitem o valor de seus dados primários do usuário, combinando-os e enriquecendo-os com os dados de atribuição da AppsFlyer a nível do usuário. Os relatórios agregados obtidos desse recurso protegem a privacidade do usuário ao mesmo tempo em que oferecem aos anunciantes insights valiosos que somente esses dados combinados podem fornecer.

Para usar o DCR, é preciso configurar o armazenamento do serviço em cloud e certificar-se de que os arquivos de dados que você fará upload estejam devidamente formatados e sejam transmitidos para o DCR.

Armazenamento de serviços em cloud

O armazenamento de serviços em cloud é usado pelo Data Clean Room (DCR) da AppsFlyer para 2 objetivos principais—

  • Entrada: localização a partir da qual a AppsFlyer lê arquivos de dados primários produzidos por seu sistema de BI
  • Saída: destino para o qual a AppsFlyer envia relatórios após o processamento no DCR

Você pode usar um ou mais buckets para estes fins (em AWS, GCS, ou ambos). No entanto, na maioria dos casos, a estrutura mais fácil inclui:

  • Um único bucket em um único serviço em cloud
  • Uma pasta identificada por sua chave DCR diretamente abaixo do bucket
  • 2 caminhos de pasta separados sob a pasta de nível superior: um para entrada e outro para saída

Esse artigo fornece as instruções necessárias para que você crie essa estrutura.

Requisitos de nomenclatura do DCR

Os seguintes requisitos de nomenclatura aplicam-se a todas as entidades de dados no DCR (buckets, pastas e arquivos):

  • Comprimento máximo: 200 caracteres
  • Caracteres válidos:
    • letras (A-Z, a-z)
    • números (0-9), não pode ser o primeiro caractere de um nome
    • hifens (-), não pode ser o primeiro caractere de um nome
  • Caracteres inválidos:
    • espaços
    • todos os outros símbolos ou caracteres especiais
  • Caracteres utilizados apenas para fins especiais:

 Observação

AWS e GCS anexam automaticamente uma barra (/) ao final de cada nome de pasta. Não inclua esse caractere ao nomear seus buckets ou pastas.

Criando um bucket

Os buckets são criados usando a interface do serviço em cloud de sua escolha, conforme descrito abaixo.

Os seguintes requisitos são relevantes para os buckets em ambos os serviços em cloud:

  • Nome do repositório:
    • O nome do bucket deve começar com af-dcr-
    • Exemplo: af-dcr-exemplo-bucket
  • Adicional:
    • O serviço de DCR da AppsFlyer deve receber permissões de bucket. Veja instruções para conceder essas permissões nas abas para cada serviço em nuvem abaixo.
    • O bucket deve ser de uso exclusivo do Data Clean Room da AppsFlyer. Em outras palavras, nenhum outro serviço pode escrever dados no bucket.

Bucket AWS

Observação: o seguinte procedimento deve ser realizado por seu administrador AWS.

Para criar um bucket e conceder permissões da AppsFlyer: 

  1. Faça login no console da AWS.
  2. Vá para o serviço S3.
  3. Para criar o bucket:
    1. Clique em Criar bucket.
    2. Complete o nome do bucket, começando com af-dcr-, seguido de seu texto (como descrito acima).
    3. Clique em Criar bucket.
  4. Para conceder permissões ao bucket da AppsFlyer:
    1. Selecione o bucket que você criou. 
    2. Acesse a aba Permissões
    3. Na seção Política do bucket, clique em Editar.
      A janela Editar política do bucket é aberta.
    4. Cole o seguinte code snippet na janela.
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Sid": "AF-DCR",
            "Effect": "Allow",
            "Principal": {
              "AWS": "arn:aws:iam::195229424603:user/product=dcr-reporter__envtype=prod__ns=default"
            },
            "Action": [
              "s3:GetObject",
              "s3:ListBucket",
              "s3:DeleteObject",
              "s3:PutObject"
            ],
            "Resource": [
              "arn:aws:s3:::af-dcr-mybucket",
              "arn:aws:s3:::af-dcr-mybucket/*"
            ]
          }
        ]
      }
      
  5. No code snippet, substitua af-dcr-mybucket (nas 2 linhas em que ele aparece) pelo nome do bucket que você criou.
    Atenção! Ao substituir o nome do bucket no snippet, certifique-se de não escrever /* sobre a segunda linha em que o nome do bucket aparece.

  6. Clique em Salvar alterações.

Bucket GCS

Observação: o procedimento a seguir deve ser realizado pelo administrador do Google Cloud.

Para criar um bucket e conceder permissões da AppsFlyer: 

  1. Faça login em seu console do GCS.
  2. Vá para a página do Cloud Storage Browser.
  3. Para criar o bucket:
    1. Clique em Criar bucket.
    2. Insira as informações do bucket na página Criar um bucket . Inclua o nome do bucket, começando com af-dcr- e seguido pelo seu texto (como descrito acima).
    3. Clique em Continuar.
    4. Clique em Criar.
  4. Para conceder permissões ao bucket da AppsFlyer:
    1. Selecione o bucket que você criou. 
    2. Acesse a aba Permissões
    3. Na seção de permissões, clique em + Adicionar.
      A janela Adicionar membros abre.
    4. Na caixa Novos membros, cole o snippet a seguir.
      appsflyer-dcr@dcr-report.iam.gserviceaccount.com
    5. Na lista Função, selecione Armazenamento em nuvem > Administração do armazenamento.

      dcr_gcs_permissions.png

    6. Clique em Salvar.

Criando uma pasta de chaves DCR

Para garantir a máxima segurança, a pasta diretamente abaixo do bucket (a "DCR key" ) deve ser nomeada com a chave DCR alfanumérica de 8 caracteres atribuída à sua conta (por exemplo, 01bcc5fb). Observação: essa chave é 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 de sua conta, clique no botão DCR na parte superior da tela principal do DCR.

dcr_key_button.png

 Exemplo

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

af-dcr-example-bucket/01bcc5fb/

Como criar de um caminho de pasta de entrada

As exigências necessárias para criar cada elemento do caminho da pasta de entrada estão descritos abaixo.

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/.

 Exemplo

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

af-dcr-example-bucket/01bcc5fb/input/

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.

 Exemplo

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

af-dcr-example-bucket/01bcc5fb/input/BI-data/
                                     CRM-data/

Subpastas para cada data e versão

Finalmente chegamos à parte da estrutura de pastas onde a ação realmente acontece: as pastas nas quais a AppsFlyer continuamente procura por novos arquivos de dados para ler no DCR.

Cada vez que você deseja que a AppsFlyer processe um arquivo de fontes de dados e crie um relatório com base nele, você deve fazer o upload de uma nova versão do arquivo para a pasta de fontes de dados, dentro de uma série de subpastas aninhadas que indicam a data e o número da versão (além de uma subpasta extra para que a AppsFlyer saiba onde os dados estão):

  • Dentro de cada pasta de origem de dados --> 1 subpasta para cada data ("pasta de data")
    • Formato: dt=aaaa-mm-dd/
    • Exemplo: dt=2022-03-10/
  • 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/

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 as referências de API para seu serviço em cloud: AWS, GCS.

Como a estrutura completa das pastas é criada programaticamente no momento do upload dos arquivos, um exemplo realista inclui tanto as pastas quanto os arquivos. Veja esta ilustração em Arquivos, abaixo.

Arquivos

Arquivos de fontes de dados

Os arquivos de fontes de dados enviados devem atender às seguintes exigências de nome, formato de arquivo e localização:

  • Deve cumprir com os requisitos de nomenclatura do DCR
  • Formato CSV ou GZIP. O arquivo subjacente à compressão GZIP deve ser um arquivo CSV.
  • Número de arquivos de origem de dados por pasta de dados:
    • CSV: máximo 1
    • GZIP: 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.

Os dados dentro dos arquivos de fonte devem atender a estes requisitos:

  • Data e hora:
    • Formato: aaaa-MM-dd hh:mm:ss
    • Fuso horário: UTC
  • Números: máximo 2 dígitos após a vírgula decimal
  • Comprimento da sequência de caracteres: máximo de 256
  • Limitações de caracteres: nenhum (todos os caracteres são válidos)

 

Arquivos _SUCCESS

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:

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

Para arquivos 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.

 Exemplo

Após o upload dos arquivos de dados de origem 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:

af-dcr-example-bucket/01bcc5fb/input/BI-data/
dt=2022-03-10/
v=1/
_SUCCESS
data/
BI-data.csv
dt=2022-03-11/
v=1/
_SUCCESS
data/
BI-data.csv CRM-data/
dt=2022-03-10/
v=1/
_SUCCESS
data/
CRM-data_part01.gzip
CRM-data_part02.gzip
v=2/
_SUCCESS
data/
CRM-data_part01.gzip
CRM-data_part02.gzip
dt=2022-03-11/
v=1/
_SUCCESS
data/
CRM-data_part01.gzip
CRM-data_part02.gzip
v=2/
_SUCCESS
data/
CRM-data_part01.gzip
CRM-data_part02.gzip

Criando um caminho de pastas de saída

As exigências necessárias para criar cada elemento do caminho da pasta de saída estão descritos abaixo.

Pasta de saída de nível superior

Embora não seja obrigatória, a prática recomendada é criar uma pasta de saída de nível superior diretamente abaixo da pasta de chaves DCR. Esta pasta será dedicada aos repositórios enviados pelo DCR.

A pasta 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 output/.

 Exemplo

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

af-dcr-example-bucket/01bcc5fb/output/

Pasta de segundo nível para cada relatório

Você pode receber regularmente qualquer número de relatórios personalizados do DCR. Você deve atribuir uma pasta separada ("pastas de relatórios") a cada um desses relatórios.

Por exemplo, se você estiver recebendo 2 relatórios do DCR: relatório de conversão e relatório de retargeting, você atribuiria uma pasta para cada uma dessas fontes de dados. Você pode chamar essas pastas de conversões/ e retargeting/.

As pastas de relatórios geralmente são criadas manualmente usando a interface de seu serviço em cloud selecionado.

 Exemplo

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

af-dcr-example-bucket/01bcc5fb/output/conversions/
                                      retargeting/

Subpastas para cada data e versão (que não foram criadas pelo cliente)

Ao contrário do caminho da pasta de entrada, você não cria pastas de data/versão no caminho da pasta de saída. A AppsFlyer criará automaticamente essa estrutura de pastas cada vez que um relatório for entregue.

Formato do arquivo de relatório

Os relatórios do DCR são enviados em formato CSV.

Este artigo foi útil?