O RudderStack é uma plataforma de dados de clientes (CDP) de código aberto que permite que as empresas coletem, unifiquem e encaminhem dados de clientes para diversos 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 por meio das APIs REST Server-to-Server (S2S) do Singular para atividades em dispositivos móveis iOS e Android. Isso é chamado de destino "Cloud-Mode" . As instruções abaixo mostram 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 esta integração, você deve estar usando os SDKs móveis do Rudderstack. Esta integração NÃO é compatível com dados de eventos que não sejam de dispositivos móveis. Eventos de servidor ou da web não são suportados.
O RudderStack oferece suporte a dois tipos de eventos de rastreamento que você pode enviar ao Singular via "Cloud-Mode":
- Eventos de sessão
- Eventos personalizados
- Atribuição básica de instalação
- Atribuição via Google Install Referrer
- Suporte à versão 3 do SkAdNetwork (modo manual)
- Atribuição via Apple Search Ads
- Rastreamento de eventos in-app personalizados
- Rastreamento de receita
- ID de usuário personalizado
- Rastreamento de desinstalação
- Suporte a Limited Data Sharing (consentimento)
- Singular Device ID (SDID) via API v2
- Suporte à versão 4 do SkAdNetwork
- Modo gerenciado do SkAdNetwork para modelos de conversão
- Atribuição via META Install Referrer
- Deep linking
Se você precisar de suporte S2S para a "funcionalidade completa" oferecida pelo Singular, deverá implementar as APIs REST S2S do Singular de forma independente do Rudderstack. Consulte o Guia de integração Server-to-Server (S2S) AQUI .
Singular Device ID (SDID) e versão da API
A versão da API do Singular que o RudderStack usa depende dos campos de identificador presentes no evento:
-
Se o
Singular Device ID (SDID)
estiver presente no evento, o RudderStack usa automaticamente a
API v2
do Singular e ignora os identificadores tradicionais específicos de plataforma (
idfa,andi,idfv,aifa). - Caso contrário, o RudderStack recorre aos identificadores específicos de plataforma e envia o evento usando a API v1 do Singular.
Para enviar o Singular Device ID (e, opcionalmente, o consentimento de compartilhamento de dados), inclua
singularDeviceId
e
limitDataSharing
dentro do objeto
integrations.Singular
do seu evento:
rudderanalytics.track(
"Order Completed", {
revenue: 30,
currency: "USD"
}, {
integrations: {
Singular: {
singularDeviceId: "SINGULAR_DEVICE_ID",
limitDataSharing: true // optional
}
}
}
);Primeiros passos
- No seu painel do RudderStack , adicione a fonte. Em seguida, na lista de destinos, selecione Singular .
- Atribua um nome ao seu destino e clique em Continue .
Configurações de conexão
Para configurar o Singular como destino com sucesso, você precisa definir as seguintes configurações:
-
API Key:
Insira aqui a sua
"SDK Key"
do Singular. Este é um campo obrigatório.
Obtenha a sua "SDK KEY" do Singular, encontrada no Singular Dashboard em "Developer Tools > SDK Integration > SDK Keys" .
Observação: Para a integração "Cloud-Mode", você irá inserir APENAS o valor da API Key (SDK Key) .
Deixe o campo "Secret" em branco. -
Session Event Name:
Insira os nomes de eventos a serem usados como eventos de sessão. Esta configuração se aplica apenas ao envio de eventos via cloud mode.
O RudderStack envia os eventos de sessão ao Singular por meio da API launch do Singular.
O RudderStack considera um evento como evento de sessão apenas se ele estiver especificado nas configurações do painel ou se for um dos três eventos de ciclo de vida a seguir:
- Application Installed
- Application Opened
- Application Updated
O RudderStack rastreia automaticamente os três eventos de ciclo de vida acima se o rastreamento de eventos de ciclo de vida estiver ativado.
- Use device mode to send events: Essas opções devem ser desativadas ao usar o "Cloud Mode" . Ao usar as plataformas Android ou iOS, você pode ativar esta configuração para enviar eventos via device mode. Em seguida, siga o guia do Singular Device Mode para as etapas de adição do Singular ao seu projeto.
- Filtragem de eventos no lado do cliente: Especifique quais eventos devem ser bloqueados ou permitidos para o Singular. Consulte o guia Client-side Events Filtering para mais informações.
- Configurações de gerenciamento de consentimento: Configure as definições de gerenciamento de consentimento para a fonte escolhendo o provedor de gerenciamento de consentimento no menu suspenso e inserindo os IDs de categoria de consentimento relevantes. Consulte Consent Management in RudderStack para mais informações.
Configurações do SDK do Unity
A configuração a seguir se aplica ao usar o Unity como fonte:
| Configuração | Descrição |
|---|---|
| Match ID mapping | Use esta configuração para mapear o match ID do Singular para um dos seguintes campos de evento: context.device.advertisingId ou properties.match_id. |
Requisitos de eventos de sessão
Mapeamentos de eventos SESSION suportados
Esta seção lista os mapeamentos das propriedades de evento do RudderStack para os campos relevantes do Singular.
A tabela a seguir lista o mapeamento dos atributos capturados automaticamente pelo RudderStack para as plataformas móveis ( Android e iOS ):
| Propriedade do RudderStack | Atributo do 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 bundle ID (iOS) do seu aplicativo. |
context.app.version |
app_v |
Obrigatório | A versão do aplicativo. |
context.ip / request_ip(nessa ordem) |
ip |
Obrigatório | O endereço IP do usuário. Consulte a observação abaixo para obter informações sobre como anonimizar seu IP. |
context.os.version |
ve |
Obrigatório | A versão do OS do dispositivo no momento da sessão. |
context.device.model |
mo |
Obrigatório | O modelo do dispositivo. Este parâmetro deve ser usado com o parâmetro ma. |
context.device.manufacturer |
ma |
Obrigatório | O fabricante do hardware do dispositivo. Este parâmetro deve ser usado com o parâmetro mo. |
context.locale |
lc |
Obrigatório | A tag local IETF do dispositivo usando código de idioma e país de duas letras, separados por um sublinhado. |
context.device.id |
idfv |
Obrigatório | O IdentifierForVendor bruto em letras maiúsculas com hífens. Isto se aplica somente a aplicativos iOS . |
context.device.id |
andi |
Obrigatório | O Android ID bruto em letras minúsculas. Isto se aplica somente a aplicativos Android e é obrigatório se o advertising ID (aifa) e o App Set ID (asid) estiverem ausentes. Consulte o FAQ abaixo para obter mais informações. |
context.app.build |
bd |
Obrigatório | A build do dispositivo (codificada em URL). |
context.device.adTrackingEnabled |
dnt |
Obrigatório | Envie true se do not track (dnt) estiver desativado (dnt=0); caso contrário, envie false (dnt=1). Isto é capturado automaticamente se você passar o advertising ID para o SDK. |
context.app.name |
n |
Opcional | O nome do aplicativo legível por humanos, conforme exibido na UI. |
timestamp / originalTimestamp |
utime |
Opcional | O horário da sessão (em UNIX time). |
context.network.wifi |
c |
Opcional | O tipo de conexão (WiFi ou operadora). |
context.network.carrier |
cn |
Opcional | O nome da operadora do provedor de internet. |
integrations.Singular.limitDataSharing |
data_sharing_options.limit_data_sharing |
Opcional | Consentimento do usuário para compartilhamento de dados, codificado em URL no formato JSON. Ele deve persistir e ser passado em todas as solicitações de eventos subsequentes. |
Para anonimizar seu IP, você pode enviar um IP de espaço reservado no campo context.ip . O RudderStack o usa como endereço IP em vez de capturá-lo automaticamente a partir do backend. No caso dos SDKs móveis, você pode aproveitar o recurso Transformations para fazer isso - ao enviar eventos via cloud mode .
A tabela a seguir lista o mapeamento dos atributos que devem ser passados por meio das propriedades do evento:
Essas propriedades não são persistidas no SDK e devem ser passadas em cada evento.
| Propriedade do RudderStack | Atributo do Singular | Presença | Descrição |
|---|---|---|---|
properties.install_ref |
install_ref |
Obrigatório | As informações do Google Install Referrer. |
properties.referring_application |
install_source |
Obrigatório | O nome do pacote da fonte de instalação no Android. Use getInitiatingPackageName() para obter isto. |
properties.install_receipt |
install_receipt |
Obrigatório | O recibo recebido da instalação. Para obter isto, siga o guia iOS Install Receipt . |
properties.asid |
asid |
Obrigatório | O App Set ID para dispositivos Android v12+. Obrigatório se o advertising ID (aifa) e o Android ID (andi) estiverem ausentes. Consulte o FAQ abaixo para obter mais informações. |
properties.url |
openui |
Obrigatório | Se o aplicativo for aberto por meio de um deep link/universal link, o valor da URL do deep link codificada. |
context.device.attTrackingStatus |
att_authorization_status |
Obrigatório | O status de autorização do App Tracking Transparency . |
userId |
custom_user_id |
Opcional | O ID de usuário passado por meio da chamada identify. |
properties.attribution_token |
attribution_token |
Opcional | Usado para atribuir Apple Search Ads para iOS 14.3 e superior. Mais informações aqui . |
properties.skan_conversion_value |
skan_conversion_value |
Opcional | O valor mais recente do SkAdNetwork no momento da notificação da sessão. |
properties.skan_first_call_timestamp |
skan_first_call_timestamp |
Opcional | Timestamp UNIX da primeira chamada feita à API do SkAdNetwork. |
properties.skan_last_call_timestamp |
skan_last_call_timestamp |
Opcional | Timestamp UNIX da última chamada feita à API do SkAdNetwork no momento da notificação da sessão. |
properties.install |
install |
Opcional | O sinalizador de instalação. Defina como true na primeira sessão após a instalação do aplicativo, ou false caso contrário. Obrigatório para a capacidade de rastreamento de reinstalação. |
properties.install_time / timestamp / originalTimestamp |
install_time |
Opcional | O horário da instalação (em UNIX time). |
properties.update_time / timestamp / originalTimestamp |
update_time |
Opcional | O horário da atualização (em UNIX time). |
A tabela a seguir lista o mapeamento dos atributos que devem ser passados por meio das propriedades do evento apenas uma vez:
Essas propriedades são persistidas no SDK e devem ser passadas apenas uma vez.
| Propriedade do RudderStack | Atributo do Singular | Presença | Descrição |
|---|---|---|---|
context.device.token |
fcm |
Opcional | O Firebase Cloud Messaging Device Token. É obrigatório para o rastreamento de desinstalação no Android. |
context.device.token |
apns_token |
Opcional | O Apple Push Notification Service Device Token. É obrigatório para o rastreamento de desinstalação no iOS. |
context.device.advertisingId |
idfa |
Obrigatório | O advertising ID bruto em letras maiúsculas com hífens. Isto se aplica somente a aplicativos iOS . |
context.device.advertisingId |
aifa |
Obrigatório | Este é o advertising ID bruto em letras minúsculas com hífens. Isto se aplica somente a aplicativos Android . Obrigatório se o App Set ID (asid) e o Android ID (andi) estiverem ausentes. Consulte o FAQ abaixo para obter mais informações. |
Para obter mais informações sobre como definir o device token, consulte a documentação relevante do SDK:
O RudderStack oferece suporte apenas ao fcm para o mapeamento do device token.
Requisitos de eventos personalizados
O RudderStack envia todos os eventos que não sejam eventos de sessão como eventos personalizados por meio do endpoint evt do Singular.
Mapeamentos de EVENT suportados
Esta seção lista os mapeamentos das propriedades de evento do RudderStack para os campos relevantes do Singular.
A tabela a seguir lista o mapeamento dos atributos capturados automaticamente pelo RudderStack para as plataformas móveis ( Android e iOS ):
| Propriedade do RudderStack | Atributo do 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 bundle ID (iOS) do seu aplicativo. |
context.ip / request_ip(na mesma ordem) |
ip |
Obrigatório | O endereço IP do usuário. |
context.device.advertisingId |
idfa |
Obrigatório | O IdentifierForVendor bruto em letras maiúsculas com hífens. Isto se aplica somente a aplicativos iOS . |
context.device.advertisingId |
aifa |
Obrigatório | Este é o advertising ID bruto em letras minúsculas com hífens. Isto se aplica somente a aplicativos Android . Obrigatório se o App Set ID (asid) e o Android ID (andi) estiverem ausentes. Consulte o FAQ abaixo para obter mais informações. |
context.device.id |
idfv |
Obrigatório | O IdentifierForVendor bruto em letras maiúsculas com hífens. Isto se aplica somente a aplicativos iOS . |
context.device.id |
andi |
Obrigatório | O Android ID bruto em letras minúsculas. Isto se aplica somente a aplicativos Android e é obrigatório se o advertising ID (aifa) e o App Set ID (asid) estiverem ausentes. Consulte o FAQ abaixo para obter mais informações. |
context.os.version |
ve |
Obrigatório | A versão do OS do dispositivo no momento da sessão. |
timestamp / originalTimestamp |
utime |
Opcional | O horário da sessão (em UNIX time). |
integrations.Singular.limitDataSharing |
data_sharing_options.limit_data_sharing |
Opcional | Consentimento do usuário para compartilhamento de dados, codificado em URL no formato JSON. Ele deve persistir e ser passado em todas as solicitações de eventos subsequentes. |
O Singular prefere aifa a asid e asid a andi (no Android) e idfa a idfv (no iOS).
A tabela a seguir lista o mapeamento dos atributos que devem ser passados por meio das propriedades do evento:
Essas propriedades não são persistidas no SDK e devem ser passadas em cada evento.
| Propriedade do RudderStack | Atributo do Singular | Presença | Descrição |
|---|---|---|---|
event |
n |
Obrigatório | O nome do evento. Este é definido pelo usuário . |
context.device.attTrackingStatus |
att_authorization_status |
Obrigatório | O status de autorização do App Tracking Transparency . |
userId |
custom_user_id |
Opcional | O ID de usuário passado por meio da chamada identify. |
properties.skan_conversion_value |
skan_conversion_value |
Opcional | O valor mais recente do SkAdNetwork no momento da notificação da sessão. |
properties.skan_first_call_timestamp |
skan_first_call_timestamp |
Opcional | Timestamp UNIX da primeira chamada feita à API do SkAdNetwork. |
properties.skan_last_call_timestamp |
skan_last_call_timestamp |
Opcional | Timestamp UNIX da última chamada feita à API do SkAdNetwork no momento da notificação da sessão. |
properties.eventAttributes |
e |
Opcional | Os atributos do evento personalizado no formato JSON. Você precisa passá-los em cada evento, pois não são persistidos no SDK. |
properties.is_revenue_event |
is_revenue_event |
Opcional | Determina se um evento é um evento de receita. Você precisa passar isto por meio das propriedades em cada evento, pois não é persistido no SDK. |
properties.receipt_signature |
receipt_signature |
Opcional | A assinatura do recibo. |
A tabela a seguir lista o mapeamento dos atributos definidos pelo usuário específicos para eventos de receita:
| Propriedade do RudderStack | Atributo do Singular | Presença | Descrição |
|---|---|---|---|
properties.total/ properties.value / properties.revenue |
amt |
Opcional | O valor da moeda. |
properties.currency |
cur |
Opcional | O código de moeda de três letras ISO 4217. Isto deve ser usado em conjunto com o parâmetro amt. |
properties.purchase_receipt |
purchase_receipt |
Opcional | O recibo recebido de uma compra. |
properties.product_id/properties.sku |
purchase_product_id |
Opcional | O identificador SKU do produto. |
properties.orderId / properties.purchase_transaction_id(nessa ordem) |
purchase_transaction_id |
Opcional | O identificador da transação. |
Se você definir qualquer uma das propriedades value, revenue ou total , o RudderStack considera automaticamente o evento como um evento de receita, a menos que isto seja explicitamente indicado pela propriedade is_revenue_event .
Algumas considerações importantes no caso de eventos personalizados estão listadas abaixo:
- O RudderStack obtém o user agent 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 são entregues com sucesso ao Singular, você pode usar o recurso Destination live events do RudderStack.
Você também pode verificar a entrega dos eventos acessando o seu Singular dashboard e seguindo estas etapas:
Siga o guia detalhado aqui sobre como usar a Testing Console
-
Acesse
"Developer Tools > Testing Console"
.
-
Clique em
Add Device
e insira o identificador de dispositivo relevante:
-
Você deve conseguir ver um log em tempo real de todos os eventos enviados ao Singular:
FAQ
Quais atributos de device ID são obrigatórios para Android?
Para solicitações Android, o Singular requer um dos seguintes atributos, nesta ordem de preferência:
-
aifa
-
asid
-
andi
Se nenhum deles estiver disponível, você deve enviar pelo menos um com um valor vazio (em vez de null ou undefined). Se você enviar todos eles, o RudderStack descarta o atributo andi conforme as políticas de dados do Google.