O RudderStack é uma plataforma de dados de clientes (CDP) de código aberto que permite às empresas recolher, unificar e encaminhar dados de clientes para vários destinos. Ele fornece uma plataforma centralizada para gerenciar pipelines de dados de clientes, permitindo que as organizações coletem facilmente dados de várias fontes, como sites, aplicativos móveis, servidores e serviços em nuvem.
O Singular pode receber dados de eventos do Rudderstack através das APIs REST do Singular Server-to-Server (S2S) para atividade móvel iOS e Android. Isso é chamado de Destino "Modo nuvem". As instruções abaixo ilustram como adicionar o Destino Singular no Rudderstack.
| Guia para | Equipes de engenharia |
| Pré-requisitos | Este artigo pressupõe que você já tenha o SDK do Rudderstack para iOS ou Android integrado ao seu aplicativo. |
Para usar essa integração, você deve estar usando os SDKs móveis do Rudderstack. Essa integração NÃO é compatível com dados de eventos não móveis. Eventos de servidor ou da Web não são suportados.
O RudderStack suporta dois tipos de eventos de rastreamento que você pode enviar para o Singular via "Cloud-Mode":
- Eventos de sessão
- Eventos personalizados
- Atribuição de instalação básica
- Atribuição do referenciador de instalação do Google
- Suporte para SkAdNetwork Versão 3 (Modo manual)
- Atribuição de anúncios de pesquisa da Apple
- Rastreamento de eventos personalizados no aplicativo
- Controlo de receitas
- ID de utilizador personalizado
- Rastreamento de desinstalação
- Suporte à versão 4 da SkAdNetwork
- SkAdNetwork Managed Mode para modelos de conversão
- Atribuição do referenciador da instalação META
- Ligação profunda
- Suporte limitado à partilha de dados
Se precisar de suporte S2S para a "Funcionalidade completa" oferecida pelo Singular, deve implementar as APIs REST S2S do Singular independentemente do Rudderstack. Consulte o Guia de integração de servidor para servidor (S2S) AQUI.
Primeiros passos
- No painel de controle do RudderStack, adicione a origem. Em seguida, na lista de destinos, selecione Singular.
- Atribua um nome ao seu destino e clique em Continuar.
Definições de ligação
Para configurar com êxito o Singular como um destino, é necessário configurar as seguintes definições:
-
Chave da API: Introduza aqui a sua "Chave SDK" do Singular. Este é um campo obrigatório.
Obtenha sua "SDK KEY" do Singular, encontrada no Singular Dashboard em "Developer Tools > SDK Integration > SDK Keys".
Nota: Para a integração "Cloud-Mode", só deve introduzir o valor da chave API (SDK Key).
Deixe o "Segredo" em branco. -
Nome do evento de sessão: Introduza os nomes dos eventos a serem utilizados como eventos de sessão. Esta configuração é aplicável apenas para o envio de eventos através do modo de nuvem.
O RudderStack envia os eventos de sessão para o Singular através da API de lançamento do Singular.
O RudderStack considera um evento como um evento de sessão somente se ele for especificado nas configurações do painel ou se for um dos três eventos de ciclo de vida a seguir:
- Aplicativo instalado
- Aplicação aberta
- Aplicativo atualizado
O RudderStack rastreia automaticamente os três eventos de ciclo de vida acima se o rastreamento de eventos de ciclo de vida estiver ativado.
- Usar o modo de dispositivo para enviar eventos: Estas opções devem ser desactivadas quando se utiliza o "Modo de nuvem". Ao utilizar as plataformas Android ou iOS, pode ativar esta definição para enviar eventos através do modo de dispositivo. Em seguida, siga o guia Modo de dispositivo Singular para obter etapas sobre como adicionar o Singular ao seu projeto.
Requisitos de evento de sessão
Mapeamentos de eventos SESSION compatíveis
Esta secção lista os mapeamentos das propriedades do evento RudderStack para os campos Singular relevantes.
A tabela a seguir lista o mapeamento dos atributos capturados automaticamente pelo RudderStack para as plataformas móveis(Android e iOS):
| Propriedade RudderStack | Atributo Singular | Presença | Descrição |
|---|---|---|---|
context.os.name |
p |
Obrigatório | A plataforma de origem (Android ou iOS). |
context.app.namespace |
i |
Obrigatório | O nome do pacote (Android) ou a ID do pacote (iOS) do seu aplicativo. |
context.app.version |
app_v |
Obrigatório | A versão da aplicação. |
context.ip / request_ip(por esta ordem) |
ip |
Obrigatório | O endereço IP do utilizador. Consulte a nota abaixo para obter informações sobre como tornar o seu IP anónimo. |
context.os.version |
ve |
Obrigatório | A versão do SO do dispositivo no momento da sessão. |
context.device.model |
mo |
Obrigatório | O modelo do dispositivo. Este parâmetro deve ser utilizado com o parâmetro ma. |
context.device.manufacturer |
ma |
Obrigatório | A marca do hardware do aparelho. Este parâmetro deve ser utilizado com o parâmetro mo. |
context.locale |
lc |
Obrigatório | A etiqueta local IETF do dispositivo utilizando o código de duas letras da língua e do país, separadas por um sublinhado. |
context.device.id |
idfv |
Obrigatório | O IdentifierForVendor em bruto em maiúsculas com traços. Isto é aplicável apenas a aplicações iOS. |
context.device.id |
andi |
Obrigatório | O ID Android em bruto em minúsculas. Aplica-se apenas a aplicações Android e só é necessário quando a ID de publicidade Android não está disponível no dispositivo. |
context.app.build |
bd |
Obrigatório | A construção do dispositivo (URL codificado). |
context.device.adTrackingEnabled |
dnt |
Obrigatório | Passe true se a opção do not track(dnt) estiver desactivada (dnt=0), caso contrário passe false(dnt=1). Isto é captado automaticamente se passar o ID de publicidade ao SDK. |
context.app.name |
n |
Opcional | O nome da aplicação legível por humanos, conforme apresentado na IU. |
utime |
Opcional | A hora da sessão (em hora UNIX). | |
context.network.wifi |
c |
Opcional | O tipo de ligação (WiFi ou operadora). |
context.network.carrier |
cn |
Opcional | O nome da operadora do provedor de Internet. |
Para tornar seu IP anônimo, você pode enviar um IP de espaço reservado no campo context.ip. O RudderStack usa-o como endereço IP em vez de o capturar automaticamente a partir do backend. No caso de SDKs móveis, você pode aproveitar o recurso Transformações para fazer isso - ao enviar eventos via modo de nuvem.
A tabela a seguir lista o mapeamento dos atributos que devem ser transmitidos por meio das propriedades do evento:
Essas propriedades não são mantidas no SDK e devem ser passadas com cada evento.
| Propriedade RudderStack | Atributo singular | Presença | Descrição |
|---|---|---|---|
properties.install_ref |
install_ref |
Obrigatório | A informação do referenciador de instalação do Google. |
properties.referring_application |
install_source |
Obrigatório | O nome do pacote de origem da instalação no Android. Utilize getInitiatingPackageName() para o obter. |
properties.install_receipt |
install_receipt |
Obrigatório | O recibo recebido da instalação. Para recuperá-lo, siga o guia de recibo de instalação do iOS. |
properties.asid |
asid |
Obrigatório | A ID do App Set para dispositivos Android v12+. |
properties.url |
openui |
Obrigatório | Se a aplicação for aberta através de um link profundo/link universal, o valor do URL codificado do link profundo. |
context.device.attTrackingStatus |
att_authorization_status |
Obrigatório | O estado de autorização do App Tracking Transparency. |
userId |
custom_user_id |
Opcional | O ID de utilizador passado através da chamada de identificação. |
properties.attribution_token |
attribution_token |
Opcional | Utilizado para atribuir anúncios de pesquisa da Apple para iOS 14.3 e superior. Mais informações aqui. |
properties.skan_conversion_value |
skan_conversion_value |
Opcional | O valor SkAdNetwork mais recente no momento da notificação da sessão. |
properties.skan_first_call_timestamp |
skan_first_call_timestamp |
Opcional | Registo de data e hora UNIX da primeira chamada efectuada à API SkAdNetwork. |
properties.skan_last_call_timestamp |
skan_last_call_timestamp |
Opcional | Registo de data e hora UNIX da última chamada feita à API SkAdNetwork no momento da notificação da sessão. |
properties.install |
install |
Opcional | O sinalizador de instalação. Definido como true na primeira sessão após a instalação da aplicação, ou false caso contrário. Necessário para a capacidade de rastreio de reinstalação. |
A tabela seguinte lista o mapeamento dos atributos que devem ser transmitidos através das propriedades do evento apenas uma vez:
Estas propriedades são mantidas no SDK e devem ser transmitidas apenas uma vez.
| Propriedade RudderStack | Atributo singular | Presença | Descrição |
|---|---|---|---|
context.device.token |
fcm |
Opcional | O token de dispositivo do Firebase Cloud Messaging. Ele é necessário para o rastreamento de desinstalação no Android. |
context.device.token |
apns_token |
Opcional | O token de dispositivo do serviço de notificação por push da Apple. É necessário para o rastreamento de desinstalação no iOS. |
context.device.advertisingId |
idfa |
Obrigatório | A ID de publicidade bruta em maiúsculas com traços. Isto aplica-se apenas a aplicações iOS. |
context.device.advertisingId |
aifa |
Necessário | Esta é a ID de publicidade bruta em minúsculas com traços. É aplicável apenas a aplicações Android. |
Para mais informações sobre a definição do token do dispositivo, consulte a documentação do SDK relevante:
O RudderStack suporta apenas fcm para mapear o token do dispositivo.
Requisitos de eventos personalizados
O RudderStack envia todos os eventos que não sejam os eventos de sessão como eventos personalizados através do ponto final evt do Singular.
Mapeamentos de EVENTOS suportados
Esta secção lista os mapeamentos das propriedades do evento RudderStack para os campos Singular relevantes.
A tabela a seguir lista o mapeamento dos atributos capturados automaticamente pelo RudderStack para as plataformas móveis(Android e iOS):
| Propriedade RudderStack | Atributo Singular | Presença | Descrição |
|---|---|---|---|
context.os.name |
p |
Obrigatório | A plataforma de origem (Android ou iOS). |
context.app.namespace |
i |
Obrigatório | O nome do pacote (Android) ou a ID do pacote (iOS) da sua aplicação. |
context.ip / request_ip(na mesma ordem) |
ip |
Obrigatório | O endereço IP do utilizador. |
context.device.advertisingId |
idfa |
Obrigatório | O IdentifierForVendor bruto em maiúsculas com traços. Isto é aplicável apenas a aplicações iOS. |
context.device.advertisingId |
aifa |
Obrigatório | O ID de publicidade bruto em minúsculas com travessões. Aplicável apenas a aplicações Android. |
context.device.id |
idfv |
Obrigatório | O IdentifierForVendor em maiúsculas e com travessões. Aplicável apenas a aplicações iOS. |
context.device.id |
andi |
Obrigatório | O ID Android em bruto em minúsculas. Aplica-se apenas a aplicações Android e é necessário apenas quando o ID de publicidade Android não está disponível no dispositivo. |
context.os.version |
ve |
Obrigatório | A versão do SO do dispositivo no momento da sessão. |
utime |
Opcional | A hora da sessão (em hora UNIX). |
A Singular prefere aifa em vez de asid e asid em vez de andi (no Android) e idfa em vez de idfv (no iOS).
A tabela seguinte lista o mapeamento dos atributos que devem ser transmitidos através das propriedades do evento:
Essas propriedades não são mantidas no SDK e devem ser passadas com cada evento.
| Propriedade RudderStack | Atributo singular | Presença | Descrição |
|---|---|---|---|
event |
n |
Obrigatório | Nome do acontecimento. Este é definido pelo utilizador. |
context.device.attTrackingStatus |
att_authorization_status |
Obrigatório | O estado de autorização do App Tracking Transparency. |
userId |
custom_user_id |
Opcional | O ID de utilizador passado através da chamada de identificação. |
properties.skan_conversion_value |
skan_conversion_value |
Opcional | O valor SkAdNetwork mais recente no momento da notificação da sessão. |
properties.skan_first_call_timestamp |
skan_first_call_timestamp |
Opcional | Carimbo de data/hora UNIX da primeira chamada efectuada à API SkAdNetwork. |
properties.skan_last_call_timestamp |
skan_last_call_timestamp |
Opcional | Registo de data e hora UNIX da última chamada feita à API SkAdNetwork no momento da notificação da sessão. |
properties.eventAttributes |
e |
Opcional | Os atributos personalizados do evento em formato JSON. É necessário passá-los com cada evento, uma vez que não são mantidos no SDK. |
properties.is_revenue_event |
is_revenue_event |
Opcional | Determina se um evento é um evento de receita. É necessário transmitir isto através das propriedades com cada evento, uma vez que não é persistido no SDK. |
A tabela seguinte apresenta o mapeamento dos atributos definidos pelo utilizador específicos dos eventos de receitas:
| Propriedade RudderStack | Atributo singular | Presença | Descrição |
|---|---|---|---|
properties.total/ properties.value / properties.revenue |
amt |
Opcional | O montante da moeda. |
properties.currency |
cur |
Facultativo | O código ISO 4217 de três letras da moeda. Deve ser utilizado em conjunto com o parâmetro amt. |
properties.purchase_receipt |
purchase_receipt |
Facultativo | O recibo recebido de uma compra. |
properties.product_id/properties.sku |
purchase_product_id |
Facultativo | O identificador SKU do produto. |
properties.orderId / properties.purchase_transaction_id(por esta ordem) |
purchase_transaction_id |
Facultativo | O identificador de transação. |
Se definir qualquer uma das propriedades valor, receita ou total, o RudderStack considera automaticamente o evento como um evento de receita, a menos que seja explicitamente mencionado pela propriedade is_revenue_event.
Algumas considerações importantes no caso de eventos personalizados estão listadas abaixo:
- O RudderStack obtém o agente do utilizador de context.userAgent para Android e das propriedades do evento no caso do iOS.
- O RudderStack armazena os atributos extras passados no evento personalizado no campo e do Singular.
Testes
Como posso verificar se os eventos são entregues com sucesso ao Singular?
Para verificar se os eventos foram entregues com sucesso ao Singular, você pode usar o recurso Destination live events do RudderStack.
Você também pode verificar a entrega do evento acessando o painel do Singular e seguindo estas etapas:
Siga o guia detalhado aqui sobre como usar o Console de teste
- Vá para "Ferramentas de desenvolvedor > Console de teste".
- Clique em Adicionar dispositivo e insira o identificador de dispositivo relevante:
- Deverá ser possível ver um registo em tempo real de todos os eventos enviados para o Singular: