Atualmente, este recurso está na versão beta.

 

Este artigo explica como se conectar à API de Conversões do Spotify

 

Índice

Sobre a API de Conversões do Spotify

Resumo de integração

Métodos de integração

       Integração com o gerenciador de tags do Google

       Integração direta

Conecte-se à API de Conversões no Gerenciador de Anúncios

Como criar uma integração com o gerenciador de tags do Google

Como criar uma integração direta de servidor para servidor

Como usar a API

Resolução de problemas da API de Conversões

 

 

Sobre a API de Conversões do Spotify

O que é a API de Conversões do Spotify?

A API de Conversões do Spotify é uma ferramenta de atribuição sem tags que permite transmitir eventos de conversão online e offline diretamente para o Spotify. A API de Conversões foi projetada para oferecer atribuição abrangente e de alta fidelidade para ajudar você a entender o desempenho das suas campanhas no Spotify. 

 

Uma vez criada, a conexão da API de Conversões deve ser selecionada como a fonte de dados de mensuração de conversões durante o processo de agendamento de campanhas no Gerenciador de Anúncios.

 

Ao usar a API de Conversões do Spotify com o Gerenciador de Anúncios, você pode:

  • Instalar a API de Conversões uma única vez para mensurar o desempenho de todas as suas campanhas no Spotify. 

  • Ver as principais ações entre dispositivos que os ouvintes fazem no seu site, aplicativo ou offline

  • Entender melhor o ROI no Gerenciador de Anúncios.

 

O que a API de Conversões pode mensurar?

A API de Conversões suporta os seguintes eventos no seu site, aplicativo ou offline:

  • Adicionar ao carrinho

  • Alias

  • Lead

  • Visualizações de página

  • Compra

  • Inscrição

  • Início de finalização da compra

  • Visualização de produto

  • Evento personalizado (até cinco)

 

Resumo de integração

A API de Conversões do Spotify (CAPI) permite que os anunciantes enviem eventos da web, de aplicativos e offline por meio de uma integração de servidor para servidor. Assim como o Spotify Pixel, essa integração permite que você acompanhe e mensure a atribuição de suas campanhas do Spotify, transmitindo esses eventos para o Spotify.

 

 

Métodos de integração

Integração com o gerenciador de tags do Google

Os anunciantes que usam o gerenciador de tags do Google (GTM) podem usar nosso modelo GTM para uma opção de integração mais rápida e leve que não exige programação. 

Antes de configurar uma integração com o GTM, verifique se você tem acesso à conta de cobrança e permissões de criador de projetos na sua empresa do GCP para fazer o provisionamento automático. Se você planeja fazer o provisionamento manual em vez do automático, precisará da ajuda de um usuário com as permissões apropriadas do GCP para configurar a infraestrutura do Cloud Run a partir da documentação do Google.

Integração direta

Para maximizar o controle sobre seu processo de integração, recomendamos criar uma integração direta com a API de Conversões. Isso exigirá o envolvimento do desenvolvedor.

 

Conecte-se à API de Conversões no Gerenciador de Anúncios

  1. Faça login no Gerenciador de Anúncios e vá até Eventos a partir do ícone de navegação global no canto superior esquerdo

  2. Uma vez nesta página, vá até "Conectar fonte de dados" e selecione "API de Conversões"
     

  3. Em seguida, nomeie sua API de Conversões

  4. Se você também planeja usar o Spotify Pixel, é recomendável criar um conjunto de dados para permitir a mensuração de conversão sem duplicatas usando os dados do Spotify Pixel e da API de Conversões.

  5. Usando a barra de busca, escolha as contas de anúncios para conectar à sua API de Conversões. As contas de anúncios devem estar associadas à sua conta comercial.
     

  6. Em "Exibir instruções da API de Conversões", leia a seção "Acessar API de Conversões" e navegue até a seção "Token"

  7. Clique em "Gerar token"

  8. Gere seu token de autenticação (você pode gerar até 3 tokens)
     

  9. Copie seu token e ID de conexão

    1. Você só pode enviar eventos para o ID de conexão que pertence à organização que gerou o token. 

Como criar uma integração com o gerenciador de tags do Google

Para criar uma integração com o gerenciador de tags do Google, você precisará de um token de autenticação e um ID de conexão gerados na página "Eventos" no Spotify Ads Manager. Você deve ser um administrador comercial no Gerenciador de Anúncios para acessar o painel e seguir as etapas abaixo.

Antes de configurar uma integração com o GTM, verifique se você tem acesso à conta de cobrança e permissões de criador de projetos na sua empresa do GCP para fazer o provisionamento automático. Se você planeja fazer o provisionamento manual em vez do automático, precisará da ajuda de um usuário com as permissões apropriadas do GCP para configurar a infraestrutura do Cloud Run a partir da documentação do Google.

  1. Siga as instruções na seção acima para se conectar à API de Conversões no Gerenciador de Anúncios

  2. Acesse o gerenciador de tags do Google e crie um novo contêiner de servidor

  3. Clique em "Tags" na barra lateral esquerda e selecione "Novo"

  4. Clique em "Configuração de tag" e selecione "Descubra mais tipos de tag na Galeria de modelos da comunidade" na janela "Escolher tipo de tag"

  5. Procure por "Spotify" e selecione "Spotify CAPI 3P Integration Tag" > Adicionar ao espaço de trabalho

  6. Cole seu token de autenticação e ID de conexão do Gerenciador de eventos

  7. Configure eventos, fonte de ação e selecione disparadores

  8. Clique em "Salvar" para adicionar a tag

 

Você também pode acessar o modelo de tag da API de Conversões do Gerenciador de Tags do Google diretamente aqui: https://tagmanager.google.com/gallery/#/owners/spotify/templates/conversion-api-tag-template

 

O repositório público para o modelo de tag do GTM também pode ser encontrado aqui: https://github.com/spotify/conversion-api-tag-template 

 

Como criar uma integração direta de servidor para servidor

Para criar uma integração direta de servidor para servidor e acessar a API de Conversões, você precisará de um token de autenticação e um ID de conexão gerados na página "Eventos" no Spotify Ads Manager. Você deve ser um administrador comercial no Gerenciador de Anúncios para acessar o painel e seguir as etapas abaixo.

 

Autenticação

O Spotify suporta um token de longa duração. Você poderá gerar até 3 tokens por vez. Depois que o terceiro token for criado, você precisará excluir um token anterior para gerar um novo. Seu token não expira e pode ser usado inúmeras vezes. 

 

ID de conexão

Para acessar a API, você precisará ter o ID de conexão. O ID de conexão é uma chave exclusiva atribuída à sua empresa que permite acessar a API quando usada com o token. O ID de conexão pode ser encontrado no Gerenciador de Anúncios em "Exibir instruções da API de Conversões".

 

Dados do usuário

A API de Conversões atualmente aceita 4 (quatro) tipos de identificadores: endereço de IP, ID do dispositivo, endereço de e-mail com criptografado com hash e número de telefone criptografado com hash. Pelo menos um tipo de identificador deve ser indicado. Como boas práticas, inclua o IP e o ID do dispositivo quando possível.

 

Como usar a API

 

Endpoint

URL do recurso: https://capi.spotify.com/capi-direct/events/

ConversionService
Resource URL: https://capi.spotify.com/capi-direct/events/

Método
de solicitação: POST
Descrição: esse método envia eventos de conversão, permitindo o monitoramento de interações do usuário, como compras, checkouts e outros tipos de engajamento por meio do endpoint da API direta especificada.

Acesse o Spotify for Developers para saber mais sobre como enviar solicitações à API.

 

Definições de evento

Nome do tipo de evento 

Descrição 

Visualizações de página 

opcional

O ato de ser direcionado ou visualizar uma página específica em um site. Por exemplo, chegar à página inicial do site ou navegar em uma página de produto específica. Observe que o evento de visualização de página é necessário para todos os anunciantes acompanharem se optarem por usar o Spotify Pixel. 

Lead 

opcional

O envio de informações sobre uma pessoa ou empresa que tenha manifestado alguma forma de interesse em um produto ou serviço. Por exemplo, digitar um endereço de e-mail para se inscrever em uma newsletter. Lembre-se de que lead pode significar coisas diferentes, dependendo do anunciante e do setor.

Adicionar ao carrinho

opcional

A ação de adicionar um item a um carrinho de compras virtual. Por exemplo, clicar no botão Adicionar ao carrinho em um site, mas não concluir a transação de compra.

Compra

opcional

A conclusão de uma transação de compra online, geralmente indicada pelo recebimento do pedido, da confirmação da compra ou de um recibo da transação. Por exemplo, chegar a uma página de agradecimento ou de confirmação do pedido.

Visualização do produto 

opcional

Mensura a ação de alguém ao visualizar uma página do site sobre um produto específico. 


Boas práticas: 

  • O código de evento de visualização do produto deve ser instalado em todas as páginas de produtos que o anunciante deseja mensurar.

  • Para informações mais detalhadas sobre nomes de produtos específicos, é recomendável usar o parâmetro product_name para incluir o nome da página ou do produto associado ao evento de visualização de produto. 

Inscrição

opcional

Mensura a ação de se inscrever ou se cadastrar em um evento, produto, serviço etc. 

Início de finalização da compra 

opcional

Mensura quando um usuário iniciou o processo de finalização de compra online.

Alias

opcional

Envia os detalhes do cliente do anunciante ao Spotify (e-mail, número de telefone).

Evento personalizado

opcional

Mensura ações de eventos personalizados em um site que não fazem parte dos tipos de evento padrão do Spotify. São eventos que você mesmo define.


Na versão beta, não é possível renomear os eventos personalizados. Eles aparecerão nos relatórios como Evento personalizado 1, Evento personalizado 2 e assim por diante. Por isso, é importante documentar quais eventos personalizados estão associados a ações específicas no seu site ao realizar a configuração inicial. 


Nota: no momento, o Gerenciador de Anúncios permite até cinco eventos personalizados. 



Resolução de problemas da API de Conversões

Você implementou a API de Conversões e já se passaram pelo menos 20 minutos, mas você ainda não está vendo atividade no gráfico de atividade do evento no Gerenciador de Anúncios. E agora? 

 

Dicas de resolução de problemas

  • Verifique se você digitou corretamente seu token e ID de conexão.

  • Confirme se a API de Conversões foi selecionada como a fonte de dados de mensuração de conversões para sua campanha.

  • Se estiver usando o gerenciador de tags do Google, lembre-se de configurar um contêiner de servidor, não um contêiner da web.

  • Se estiver usando a integração direta de servidor para servidor, verifique se a chamada da API está formatada corretamente.

 

Se você ainda não estiver vendo nenhuma atividade de evento, verifique com sua equipe de engenharia como a API de Conversões foi configurada e quais eventos estão sendo compartilhados.