Integração com Meta Ads

Necessária a assistência do desenvolvedor

Você precisará da ajuda de 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 em sua jornada do cliente.

Casos de uso

Use esta integração para:

• segmentar usuários de alto valor em múltiplos canais para aumentar compras ou engajamento
• redirecionar 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 Administrador em sua conta Pushwoosh. Veja 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 do Facebook de sua marca, 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 de Públicos Personalizados do Facebook para as contas de anúncios do Facebook que você planeja usar com o Pushwoosh.

Configurar o Meta Ads no Pushwoosh

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

2. No cartão do Meta Ads, clique em Página de login.

3. Faça login em sua conta do 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 empresarial.

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

Revisar 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 empresarial
• 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.

Gerenciar contas de anúncios conectadas

Na página Meta Ads, clique em Gerenciar contas para abrir o 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.

Mapear tags do projeto para campos do Meta

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

Habilitar a coleta de MADID no SDK

O Meta Ads faz a correspondência de usuários usando identificadores de dispositivo (MADID) coletados via 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 requisição de rede é feita.
• Se a requisição de rede falhar, tente novamente na próxima inicialização 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 o diálogo de permissão ATT:

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

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

Se seu aplicativo usa IDFA para rastreamento, a Apple exige que você liste os domínios que recebem dados de rastreamento em seu manifesto de privacidade (PrivacyInfo.xcprivacy). Veja 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 requisiçõ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 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 requisição de rede é feita.
• Se a requisição de rede falhar, chame setAdvertisingId novamente na próxima inicialização 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 após 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.

Sincronizar públicos em journeys

O ponto Sincronização de público no Journey Builder vincula sua jornada a um Público Personalizado do Meta. Toda vez que um usuário atinge esse ponto, o Pushwoosh solicita ao Meta que o adicione ou o 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 Sincronização de público.

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

   • Adicionar usuários ao público. Adiciona cada usuário que atinge 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 atinge 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 aquele usuário, e ele continua na jornada.
• Se um perfil atingir o ponto de Sincronização de público enquanto a conta de anúncios conectada estiver desconectada, a jornada para para aquele perfil e o Pushwoosh envia notificações do sistema и por e-mail.
• Se um público selecionado não for encontrado no Meta e a API retornar um erro, a jornada para para aquele 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 Sincronização de público para ver o volume de entrada, adições e remoções, e perfis pulados. Para detalhes das métricas, veja Sincronização de público em Estatísticas da Jornada do Cliente.