Integração com Meta Ads

É necessária a ajuda do desenvolvedor

Você precisará da ajuda da sua equipe de desenvolvimento para configurar a integração. Por favor, compartilhe este guia com eles.

A integração com Meta Ads permite que você sincronize públicos do Pushwoosh com suas contas de anúncios do Meta. Use-a para segmentar ou excluir usuários em campanhas de anúncios e adicionar anúncios pagos como outro canal na jornada do seu cliente.

Casos de uso

Use esta integração para:

• segmentar usuários de alto valor em múltiplos canais para aumentar compras ou engajamento
• fazer retargeting de usuários que são menos responsivos em outros canais
• construir públicos de supressão para que clientes fiéis não recebam anúncios desnecessários

Pré-requisitos

Antes de conectar o Meta Ads, certifique-se de que:

• Você tem a função de Admin na sua conta Pushwoosh. Consulte Gerenciar acesso e permissões de usuário para saber como as funções e permissões funcionam.
• Você tem um Gerenciador de Negócios do Facebook configurado para gerenciar os ativos da sua marca no Facebook, incluindo contas de anúncios, páginas e aplicativos.
• Você tem uma Conta de Anúncios do Facebook ativa vinculada ao seu Gerenciador de Negócios.
• O administrador do seu Gerenciador de Negócios do Facebook concedeu a você as permissões de Gerenciar Campanhas ou Gerenciar contas de anúncios para as contas de anúncios que você planeja usar com o Pushwoosh.
• Você aceitou os termos e condições da conta de anúncios para essas contas.
• Você aceitou os Termos dos Públicos Personalizados do Facebook para as contas de anúncios do Facebook que você planeja usar com o Pushwoosh.

Configure o Meta Ads no Pushwoosh

1. No Pushwoosh, vá para Configurações > Integrações de terceiros.

2. No card do Meta Ads, clique em Página de login.

3. Faça login na sua conta Meta e clique em Continuar.

4. Selecione as contas de anúncios que você deseja conectar.

5. Revise as permissões solicitadas para a conta de anúncios e o acesso de negócios.

6. Clique em Salvar. O Meta então mostra uma confirmação de que sua conta está conectada.

Revise o status da conexão

Após a configuração, você será redirecionado para a página Meta Ads no Pushwoosh.

A tabela de contas de anúncios lista cada conta conectada com:

• Nome da conta de anúncios
• Conta de negócios
• ID

Abra os três pontos no final de uma linha e escolha Remover conta de anúncios para excluir essa conta de anúncios da lista no Pushwoosh.

Gerencie as contas de anúncios conectadas

Na página Meta Ads, clique em Gerenciar contas para abrir a caixa de diálogo. Use o botão de alternância em cada linha para incluir ou excluir essa conta de anúncios da integração. Clique em Aplicar para salvar as alterações ou em Cancelar para fechar sem salvar.

Para ajustar a visualização da lista:

• Ative ou desative Mostrar apenas conectados para limitar quais linhas aparecem.
• Digite em Pesquisar por nome ou id… para encontrar contas na lista.

Mapeie as tags do projeto para os campos do Meta

O mapeamento de propriedades do usuário permite que você diga ao Pushwoosh quais atributos de usuário do Meta devem atualizar quais campos de Nome da tag em seu projeto. Dessa forma, quando os dados vêm do Meta, eles são salvos onde você espera.

Nota

Para a sincronização de público, o Pushwoosh sempre envia um identificador por usuário de E-mail, Número de telefone ou MADID, dependendo do que existe no perfil. Configure o mapeamento quando quiser que o Meta receba atributos de usuário adicionais além dos identificadores acima.

1. Na página Meta Ads, clique em Mapear dados do usuário.

2. Para cada Campo do Facebook na coluna da esquerda, escolha um Nome da tag em seu projeto no controle à direita. Mapeie apenas as linhas que você precisa.

Campos mapeados automaticamente

O Pushwoosh mapeia esses campos automaticamente. Você não os define em Mapear tags do projeto para campos do Meta:

• E-mail
• Número de telefone
• MADID

3. Clique em Salvar para aplicar o mapeamento ou em Cancelar para fechar sem salvar.

Habilite a coleta de MADID no SDK

O Meta Ads corresponde usuários usando identificadores de dispositivo (MADID) coletados através do SDK móvel. O SDK do Pushwoosh não coleta identificadores de publicidade (GAID no Android, IDFA no iOS) automaticamente. Ambas as plataformas exigem consentimento explícito do usuário antes que o identificador possa ser lido. Em seu aplicativo, solicite o consentimento do usuário, leia o identificador quando permitido e passe o valor para o SDK.

Android

1. Adicione a dependência

implementation 'com.google.android.gms:play-services-ads-identifier:...'

2. Declare a permissão AD_ID (necessária para targetSdk ≥ 33)

Adicione isto ao seu AndroidManifest.xml:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Cuidado

Sem essa permissão no Android 13+, AdvertisingIdClient.getAdvertisingIdInfo() retorna silenciosamente um UUID zerado (00000000-0000-0000-0000-000000000000). O SDK do Pushwoosh normaliza isso para null, então nenhum MADID é enviado para o servidor e a correspondência de público do Meta não funcionará.

3. Recupere o GAID e passe-o para o SDK

getAdvertisingIdInfo deve ser chamado em uma thread de segundo plano:

String gaid = AdvertisingIdClient.getAdvertisingIdInfo(context).getId();

Pushwoosh.getInstance().setAdvertisingId(gaid);

Para limpar o valor armazenado no backend, passe null ou uma string vazia:

Pushwoosh.getInstance().setAdvertisingId(null);

Notas de comportamento:

• Se o valor não mudou desde a última chamada bem-sucedida, nenhuma solicitação de rede é feita.
• Se a solicitação de rede falhar, tente novamente no próximo lançamento do aplicativo.
• A chamada é ignorada quando Pushwoosh.stopCommunication() está ativo.
• O UUID zerado (00000000-0000-0000-0000-000000000000) é tratado da mesma forma que null — o MADID armazenado é limpo no backend.

iOS

1. Adicione a descrição de uso ao Info.plist

A Apple exige esta chave antes de mostrar a caixa de diálogo de permissão ATT:

<key>NSUserTrackingUsageDescription</key>
<string>Usamos seu identificador de publicidade para mostrar anúncios relevantes.</string>

2. Declare o domínio de rastreamento no seu manifesto de privacidade

Se o seu aplicativo usa IDFA para rastreamento, a Apple exige que você liste os domínios que recebem dados de rastreamento no seu manifesto de privacidade (PrivacyInfo.xcprivacy). Consulte TN3182 para os requisitos completos.

Defina NSPrivacyTracking como true e adicione o domínio de rastreamento do Pushwoosh a NSPrivacyTrackingDomains:

<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.svc-nue.pushwoosh.com</string>
</array>

Nota

Se o usuário não concedeu a permissão ATT, o iOS bloqueia as solicitações de rede para todos os domínios listados em NSPrivacyTrackingDomains. O MADID não será enviado, independentemente do que seu código faça.

3. Solicite autorização de rastreamento e passe o IDFA para o SDK

ATTrackingManager requer iOS 14 ou posterior. Se o seu alvo de implantação for inferior ao iOS 14, envolva a chamada em uma verificação de disponibilidade.

O SDK do Pushwoosh não chama ATTrackingManager. Solicite autorização de rastreamento em seu aplicativo e, em seguida, passe o resultado para o SDK:

import AppTrackingTransparency
import AdSupport

if #available(iOS 14, *) {
    ATTrackingManager.requestTrackingAuthorization { status in
        let idfa = status == .authorized
            ? ASIdentifierManager.shared().advertisingIdentifier.uuidString
            : nil
        Pushwoosh.configure.setAdvertisingId(idfa)
    }
}

Para limpar o valor armazenado no backend, passe nil ou uma string vazia:

Pushwoosh.configure.setAdvertisingId(nil)

Notas de comportamento:

• Se o valor não mudou desde a última chamada bem-sucedida, nenhuma solicitação de rede é feita.
• Se a solicitação de rede falhar, chame setAdvertisingId novamente no próximo lançamento do aplicativo.
• A chamada é ignorada quando Pushwoosh_ALLOW_SERVER_COMMUNICATION está desativado.
• O UUID zerado (00000000-0000-0000-0000-000000000000) é tratado da mesma forma que nil ou uma string vazia — o MADID armazenado é limpo no backend.

Chame requestTrackingAuthorization do fluxo principal da interface do usuário do seu aplicativo. A Apple recomenda fazer isso depois de mostrar sua própria tela explicativa, não imediatamente no lançamento.

Como funciona

Depois de chamar setAdvertisingId, o SDK envia o valor para o endpoint de rastreamento do Pushwoosh como o campo madid junto com o código do aplicativo e o ID de hardware do dispositivo. O Pushwoosh usa este identificador para corresponder seus registros de dispositivo com os públicos do Meta Ads para sincronização.

Sincronize públicos em jornadas

O ponto de Sincronização de público no Journey Builder vincula sua jornada a um Público Personalizado do Meta. Toda vez que um usuário chega a esse ponto, o Pushwoosh solicita ao Meta que o adicione ou remova do público.

Por exemplo, você pode usar isso para parar de mostrar um anúncio de webinar para usuários que já se registraram, para não desperdiçar gastos com anúncios em pessoas que não precisam mais vê-lo.

Para configurar a sincronização de público:

1. Abra o Journey Builder.

2. Adicione uma Entrada baseada em público. Em Fonte do público, escolha um segmento ou lista do Pushwoosh que defina quem entra nesta jornada. Por exemplo, um segmento Usuários com a tag webinar_registered definida como true. Apenas esses usuários passarão pela jornada e chegarão à Sincronização de público.

3. Adicione o ponto de Sincronização de público.

4. Em Como sincronizar informações de usuários com o público do Meta, escolha uma opção:

   • Adicionar usuários ao público. Adiciona cada usuário que chega a esta etapa ao público do Meta que você selecionar. Por exemplo, use isso para começar a mostrar um anúncio para usuários que se inscreveram, mas ainda não participaram.
   • Remover usuários do público. Remove cada usuário que chega a esta etapa daquele público do Meta. Neste exemplo, selecione esta opção para parar de mostrar o anúncio do webinar para usuários que já se registraram.

5. Em Conta do Meta Ads, selecione a conta de anúncios conectada.

6. Em Público, selecione o público do Meta, por exemplo, Webinar.

7. Clique em Aplicar para salvar o ponto ou em Cancelar para fechar sem salvar.

8. Termine de configurar a jornada e, em seguida, inicie-a.

Quando esses usuários chegam à Sincronização de público, eles são removidos do público Webinar no Meta, para que não vejam mais o anúncio do webinar lá.

Comportamento e tratamento de erros

O processamento da jornada depende da disponibilidade da conta e do público do Meta:

• O Meta atualiza o público apenas quando consegue corresponder o usuário com os dados que o Pushwoosh fornece. Se o Meta não conseguir corresponder o usuário, o público não muda para esse usuário, e ele continua na jornada.
• Se um perfil chegar ao ponto de Sincronização de público enquanto a conta de anúncios conectada estiver desconectada, a jornada para para esse perfil e o Pushwoosh envia notificações do sistema e por e-mail.
• Se um público selecionado não for encontrado no Meta e a API retornar um erro, a jornada para para esse perfil e o Pushwoosh envia notificações do sistema e por e-mail.

Estatísticas de sincronização de público

Após o lançamento, abra as estatísticas da etapa de Sincronização de público para ver o volume de entrada, adições e remoções, e perfis ignorados. Para detalhes das métricas, consulte Sincronização de público em Estatísticas da Jornada do Cliente.