Esta página foi traduzida pela API Cloud Translation.

Guia de instalação do TCRM

Etapa 1: configurar o Google Cloud Platform (GCP)

AVISO: os projetos do GCP que pertencem ao Google podem ser aplicados pelo Aplicaçãor (ECP, na sigla em inglês). Nesse caso, a instalação falhará, solicitando uma chave de segurança. Para evitar isso, crie um novo projeto do GCP (o ECP leva cerca de 24 horas para encontrar seu projeto) ou use um projeto público que não seja aplicado enquanto tentamos encontrar uma solução permanente para esse problema.

1.1 Selecionar ou criar um projeto do GCP

Crie um novo projeto do Google Cloud Platform ou use um atual. Abra o arquivo e verifique se o nome do projeto aparece na parte superior da página.

Etapa 2: instalar o TCRM

2.1 Solicitar acesso à pasta de código do TCRM

Até que o TCRM tenha código aberto e esteja disponível externamente, a permissão de clonagem será necessária para cada uso. Envie este formulário de solicitação para ter acesso à clonagem da pasta de código TCRM.

2.2 Instalar o TCRM

Clique no ícone do Cloud Shell no canto superior direito da página para abrir a linha de comando do GCP.
Execute o seguinte comando no shell para clonar a pasta do código TCRM:
```
  git clone https://github.com/google/TaglessCRM.git
```

Em seguida, execute este comando:

  cd TaglessCRM && sh setup.sh --project_id=$GOOGLE_CLOUD_PROJECT

OBSERVAÇÃO: esse comando seguirá estas três etapas:

Criar um ambiente virtual do Python e instalar todos os pacotes necessários em Python.
Ativar as APIs do Cloud necessárias no projeto do GCP.
Criar um ambiente do Cloud Composer e implantar os DAGs do TCRM nele

OBSERVAÇÃO: a execução da instalação leva cerca de duas horas. Aguarde até que a execução do script seja concluída.

Etapa 3: configurar o Airflow e configurar variáveis

3.1 Configurar uma conexão do BigQuery

Para ler dados do BigQuery, vincule sua conta de serviço à conexão do BigQuery.

Clique em Identidade → Contas de serviço. Em seguida, clique nos três pontos ao lado da conta de serviço que começa com tcrm-sa e selecione "Criar chave → JSON → Criar".

Abra a chave salva em um editor de texto e copie o JSON.

Volte para o Airflow (Composer → Airflow) e selecione Admin → Conexões.

Clique no ícone de lápis ao lado da conexão bigquery_default.

OBSERVAÇÃO: o nome de conexão padrão é bigquery_default. Se você estiver usando um nome de conexão do BigQuery diferente, defina as variáveis monitoring_bq_conn_id e bq_conn_id do Airflow (variáveis, não conexões) com o novo nome de conexão.

DICA: consulte esta página para mais detalhes sobre como gerenciar conexões do Airflow.

Cole o JSON da conta de serviço no campo "JSON" do arquivo de chaves e clique em "Salvar".

3.2 Configurar variáveis usando a IU do Airflow

Abra o menu no canto superior esquerdo da tela. Em seguida, clique em Composer para abrir a página de ambientes do Composer.
Na tela do Composer, localize a linha tcrm-env no lado esquerdo da lista. Nessa linha, clique no link Airflow para abrir o console do Airflow.
No Console do Airflow, na barra de menus superior, clique na opção Admin e escolha Variables no menu suspenso.
Na tela "Variables", clique em Create.
Para adicionar uma variável, insira o nome da chave e o valor e clique em save. Consulte as próximas duas etapas para ver quais variáveis são necessárias para cada DAG.

3.3 Configurar variáveis gerais do DAG

A tabela a seguir contém as variáveis gerais necessárias para todos os DAGs. Essas variáveis têm valores padrão já configurados automaticamente para que você não precise mudar nada se os valores padrão atenderem às suas necessidades. No entanto, é possível alterar essas variáveis a qualquer momento definindo uma variável do Airflow com o mesmo Variable Name para outro valor.

Para permitir que DAGs diferentes tenham configurações distintas, os nomes de alguns deles vão conter o nome do DAG como prefixo. Lembre-se de substituir a parte <DAG Name> e usar o nome do DAG correto.

Por exemplo: para definir a variável de programação para o DAG tcrm_gcs_to_ga, use o nome da variável da tabela <DAG Name>_schedule abaixo e crie uma variável chamada tcrm_gcs_to_ga_schedule. Para programar o DAG tcrm_gcs_to_ads_oc, crie uma variável chamada tcrm_gcs_to_ads_oc_schedule.

O nome do DAG pode ser encontrado na IU do Airflow na guia "DAGs":

3.3.1 Tabela de variáveis gerais

Nome da variável	Valor padrão	Informações da variável
`<DAG_Name>_retries`	`0`	Número inteiro. Número de vezes que o Airflow tentará executar novamente o DAG em caso de falha. Recomendamos manter esse valor como 0, já que o TCRM tem o próprio mecanismo de repetição. No entanto, defini-lo como outro número inteiro não causará erros, mas ele não tentará reenviar eventos com falha.
`<DAG_Name>_retry_delay`	`3`	Número inteiro. Número de minutos entre cada nova execução do DAG.
`<DAG_Name>_schedule`	`@once`	Uma programação de DAG. Consulte a seção 3.3.2 Programar um DAG para mais informações.
`<DAG_Name>_is_retry`	`1`	`1` para ativar e `0` para desativar. Se o DAG deve ou não tentar reenviar eventos com falha para a mesma origem de saída. Esta é uma nova tentativa interna de envio de eventos com falha de execuções semelhantes anteriores. Isso é diferente da nova tentativa do Airflow de todo o DAG. Consulte a seção Mecanismo de repetição deste Guia de uso para mais informações.
`<DAG_Name>_is_run`	`1`	`1` para ativar e `0` para desativar. Se o DAG precisa ou não incluir uma execução principal. Essa opção poderá ser desativada se o usuário quiser pular a execução principal e executar apenas a operação de repetição. Consulte a seção Executar deste guia de uso para mais informações.
`<DAG_Name>_enable_run_report`	`0`	`1` para ativar e `0` para desativar. Indica se o DAG retornará ou não um relatório de execução. Nem todos os DAGs têm relatórios. Consulte a seção Relatórios deste guia de uso para mais informações.
`<DAG_Name>_enable_monitoring`	`1`	`1` para ativar e `0` para desativar. Consulte a seção Monitoramento deste guia para mais informações.
`monitoring_dataset`	`tcrm_monitoring_dataset`	O ID do conjunto de dados da tabela de monitoramento.
`monitoring_table`	`tcrm_monitoring_table`	O nome da tabela de monitoramento.
`monitoring_bq_conn_id`	`bigquery_default`	ID da conexão do BigQuery para a tabela de monitoramento. Pode ser o mesmo ou diferente do ID de conexão do BQ de entrada.

3.3.2 Programar um DAG

Para configurar o programador de DAGs, crie uma variável de programação para cada DAG que você quer programar. O nome da variável precisa começar com o nome do DAG, seguido de _schedule.

O valor da variável precisa ser o intervalo para o qual você quer programar o DAG. Exemplo:

Insira @uma vez para executar o DAG apenas uma vez ou insira @daily ou @weekly para configurar o DAG. Consulte este guia para saber mais sobre todas as opções de programação disponíveis.

Essas variáveis são opcionais. Se as variáveis de programação não estiverem definidas, a programação padrão para todos os DAGs será @once.

3.4 Configurar variáveis específicas do DAG

A seção a seguir indica quais variáveis são necessárias para executar cada DAG. Você só precisará configurar variáveis para os DAGs que planeja usar.

3.4.1 `tcrm_bq_to_ga` DAG

Para executar o DAG tcrm_bq_to_ga, defina as seguintes variáveis:

bq_dataset_id: o nome do conjunto de dados do BigQuery que contém os dados. Exemplo: my_dataset
bq_table_id: o nome da tabela do BigQuery que contém os dados. Exemplo: my_table
ga_tracking_id: ID de acompanhamento do Google Analytics. Exemplo: UA-123456789-1

3.4.2 `tcrm_gcs_to_ga` DAG

Para executar o DAG tcrm_gcs_to_ga, defina as seguintes variáveis:

gcs_bucket_name: nome do bucket do Cloud Storage. Exemplo: my_bucket
gcs_bucket_prefix: o caminho para a pasta de dados dentro do bucket. Exemplo: folder/sub_folder
gcs_content_type(opcional): tipo de conteúdo do Cloud Storage. JSON ou CSV;
ga_tracking_id: ID de acompanhamento do Google Analytics. Exemplo: UA-123456789-1

3.4.3 `tcrm_bq_to_ads_oc` DAG

Para executar o DAG tcrm_bq_to_ads_oc, defina as seguintes variáveis:

bq_dataset_id: o nome do conjunto de dados do BigQuery que contém os dados. Exemplo: my_dataset
bq_table_id: o nome da tabela do BigQuery que contém os dados. Exemplo: my_table
ads_credentials: as informações de autenticação da API Google AdWords. Consulte 3.5.1 Criar string YAML do ads_credentials para autenticação do Google Ads para mais informações.

3.4.4 `tcrm_gcs_to_ads_oc` DAG

Para executar o DAG tcrm_gcs_to_ads_oc, defina as seguintes variáveis:

gcs_bucket_name: nome do bucket do Cloud Storage. Exemplo: my_bucket
gcs_bucket_prefix: o caminho para a pasta de dados dentro do bucket. Exemplo: folder/sub_folder
gcs_content_type(opcional): tipo de conteúdo do Cloud Storage. JSON ou CSV;
ads_credentials: as informações de autenticação da API Google AdWords. Consulte 3.5.1 Criar string YAML do ads_credentials para autenticação do Google Ads para mais informações.

3.5 Autenticação nas plataformas do Google

3.5.1 Criar uma string YAML ads_credentials para autenticação do Google Ads

Para se autenticar no Google Ads, você precisará criar uma string formatada em YAML e salvá-la como um parâmetro do Airflow. Esse parâmetro será usado pelo TCRM para autenticação entre o TCRM e o Google Ads. O formato da string é o seguinte:

developer_token: abcd
client_id: test.apps.googleusercontent.com
client_secret: secret
refresh_token: 1//token
login_customer_id: 1234567890
use_proto_plus: True

O login_customer_id fica no canto superior direito acima do seu e-mail depois que você faz login no Google Ads. O ID do cliente precisa ser um ID da conta da MCC que inclua as contas do Google Ads que você quer automatizar.

O developer_token está localizado na Central de API depois que você faz login na sua conta da MCC do Google Ads.

É possível criar client_id e client_secret na página "APIs e serviços" no Console do GCP.

refresh_token pode ser gerado da seguinte maneira:

Faz o download do script Python.
Execute o script Python com os parâmetros necessários em um terminal. python generate_refresh_token.py --client_id INSERT_CLIENT_ID --client_secret INSERT_CLIENT_SECRET
Clique no link.

Escolha a conta de e-mail que tem permissão para modificar seus dados do Google Ads e clique em "Permitir".

Copie o código e cole-o no terminal após o código. O token de atualização será mostrado abaixo.

Etapa 4: preparar os dados para o envio

4.1 Preparar dados para o Google Analytics (GA)

OBSERVAÇÃO: consulte a API Measurement Protocol para ver os requisitos detalhados.

Para enviar seus dados ao GA, escolha entre estas três opções:

No BigQuery, use o DAG tcrm_bq_to_ga no formato de tabela SQL.
Do Google Cloud Storage usando o DAG tcrm_gcp_to_ga no formato JSON.

{"cid": "12345.67890", "t":"event", "ec": "video", "ea": "play", "el": "holiday", "ev": "300" }
{"cid": "12345.67891", "t":"event", "ec": "video", "ea": "play", "el": "holiday", "ev": "301" }
{"cid": "12345.67892", "t":"event", "ec": "video", "ea": "play", "el": "holiday", "ev": "302" }
{"cid": "12345.67893", "t":"event", "ec": "video", "ea": "play", "el": "holiday", "ev": "303" }

Do Google Cloud Storage usando o DAG tcrm_gcp_to_ga no formato CSV.

cid,t,ec,ea,el,ev
12345.67890,event,video,play,holiday,300
12345.67891,event,video,play,holiday,301
12345.67892,event,video,play,holiday,302
12345.67893,event,video,play,holiday,303

AVISO: para garantir que o GA aceite os dados enviados do TCRM, você precisa configurar a filtragem de bots do GA. Para fazer isso, acesse Admin -> View Settings -> Bot Filtering na IU do Google Analytics e desmarque a opção "Excluir todos os hits de bots e indexadores conhecidos".

4.2 Preparar dados para a conversão off-line do Google Ads

Para enviar seus dados ao Google Ads, escolha entre estas três opções:

No BigQuery, use o DAG tcrm_bq_to_ads_oc no formato de tabela SQL.
Do Google Cloud Storage usando o DAG tcrm_gcs_to_ads_oc no formato JSON.

{"conversionName": "my_conversion_1", "conversionTime":"20191030 122301 Asia/Calcutta", "conversionValue": "0.47", "googleClickId": "gclid1"}
{"conversionName": "my_conversion_1", "conversionTime":"20191030 122401 Asia/Calcutta", "conversionValue": "0.37", "googleClickId": "gclid2"}
{"conversionName": "my_conversion_2", "conversionTime":"20191030 122501 Asia/Calcutta", "conversionValue": "0.41", "googleClickId": "gclid3"}
{"conversionName": "my_conversion_2", "conversionTime":"20191030 122601 Asia/Calcutta", "conversionValue": "0.17", "googleClickId": "gclid4"}

Do Google Cloud Storage usando o DAG tcrm_gcp_to_ads_oc no formato CSV.

conversionName,conversionTime,conversionValue,googleClickId
my_conversion_1,20191030 122301 Asia/Calcutta,0.47,gclid1
my_conversion_1,20191030 122401 Asia/Calcutta,0.37,gclid2
my_conversion_2,20191030 122501 Asia/Calcutta,0.41,gclid3
my_conversion_2,20191030 122601 Asia/Calcutta,0.17,gclid4

Etapa 5: executar o TCRM

No Console do Airflow, clique na opção DAGs na barra de menus superior. Encontre o DAG que você quer executar na lista à esquerda. Em seguida, execute-o clicando no botão Play no lado direito da lista.