Guia de integração do servidor para servidor (S2S)

Observação: As integrações de servidor para servidor só estão disponíveis mediante solicitação. Fale com seu gerente de atendimento ao cliente da Singular ou com o suporte da Singular.

 

Como alternativa ao SDK da Singular, que deve ser incorporado em seus aplicativos, a Singular também fornece uma API REST que pode ser usada para criar uma integração completa que é executada a partir de seu próprio servidor.

Este guia explica como criar uma integração S2S básica com a Singular e implementar vários recursos opcionais.

Para obter uma lista completa dos pontos de extremidade da API S2S, seus parâmetros e exemplos de chamadas, consulte a Referência de pontos de extremidade S2S.

Integração básica

A integração mais básica com a Singular envolve informar à Singular quando há uma nova sessão - em outras palavras, quando o aplicativo é aberto.

Para notificar a Singular sobre uma sessão de usuário, chame o Session Notification Endpoint.

As notificações de sessão permitem que a Singular faça várias coisas:

  • Se for a primeira sessão do aplicativo no dispositivo específico, a Singular reconhece uma nova instalação e aciona o processo de atribuição de instalação.
  • Se a sessão se qualificar como uma sessão de reengajamento, o Singular aciona o processo de atribuição de reengajamento (saiba mais nas Perguntas frequentes sobre reengajamento).
  • Caso contrário, a Singular marca a sessão como uma sessão, que é usada para rastrear a atividade e a retenção do usuário.

O ponto de extremidade Session Notification tem alguns parâmetros necessários. Para obter ajuda na obtenção de todos os dados necessários para relatar uma sessão, consulte Referência:Recuperação do recibo de instalação do iOS e Referência: Recuperação de identificadores de dispositivos e dados de sessão.

Dica: Ao coletar os dados para relatar uma sessão, certifique-se de aguardar o retorno das funções assíncronas e de lidar com vários casos extremos. Esse é um problema comum que pode causar dados ausentes e atribuição parcial.

Coleta e envio do ID do conjunto de aplicativos (necessário para Android 12+)

O ID do App Set ou ASID é um novo ID de privacidade usado em dispositivos Android 12+. A ID do App Set é compartilhada por todos os aplicativos em um dispositivo que foram publicados na Google Play Store pelo mesmo desenvolvedor.

Adicione o App Set ID como um parâmetro à chamada de sessão e a cada chamada de evento, da mesma forma que você enviaria o GAID.

Para coletar o ID do App Set, use o seguinte código em seu aplicativo:

Context context = getApplicationContext();
  AppSetIdClient client = AppSet.getClient(context);
  Task<AppSetIdInfo> task = client.getAppSetIdInfo();
  
  task.addOnSuccessListener(new OnSuccessListener<AppSetIdInfo>() {
      @Override
      public void onSuccess(AppSetIdInfo info) {
          // Determine o escopo atual do ID do appset.
          int scope = info.getScope();
  
          // Leia o valor do ID do appset, que usa a versão 4 do formato UUID (identificador universalmente exclusivo).
          String id = info.getId();
      }
  });

Importante: envio do referenciador de instalação do Google Play (Android)

O referenciador de instalação contém informações sobre quem enviou um usuário para a Google Play Store. Quando o referenciador de instalação está disponível para a Singular, ele fornece a maneira mais precisa de atribuir instalações. Recupere esse valor e passe-o para o Singular na primeira chamada de notificação de sessão. Ele é necessário para alguns recursos importantes da Singular, como receber dados do Facebook em nossas exportações de nível de usuário, compartilhá-los com destinos de dados e enviar postbacks.

O Google Play coleta informações do referenciador quando um usuário chega à loja. Se o usuário instalar posteriormente o aplicativo para o qual foi direcionado, o Google Play disponibilizará as informações para o aplicativo. Para obter mais informações, consulte a documentação do Google para desenvolvedores.

Para compartilhar o referenciador de instalação com o Singular:

  1. Quando o aplicativo for aberto pela primeira vez, recupere o referenciador de instalação usando a API Play Install Referrer.
  2. Relate uma sessão para a Singular usando o ponto de extremidade Session Notification, incluindo o parâmetro install_ref. Esse parâmetro é codificado em JSON e tem os seguintes atributos:

    Atributo Descrição
    referrer O valor do referenciador recuperado da API Play Install Referrer. Este é um objeto JSON, portanto, codifique-o como uma string.
    referrer_source Especifique "service".
    clickTimestampSeconds O carimbo de data/hora do clique recebido da API Play Install Referrer (por exemplo, "1550420123").
    installBeginTimestampSeconds
    A hora em que a instalação foi iniciada, conforme recebido da API Play Install Referrer.
    current_device_time O tempo no dispositivo atual, em milissegundos (por exemplo, "1550420454906").

A seguir, um exemplo de código para relatar o evento install referrer:

Python HTTP
import requests
import json
  
  SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  referrer_values = {
        "referrer": "tracking_id%3D123456789&utm_source%3Dmdotm%26utm_medium%3Dbanner%26utm_campaign%3Dcampaign",
        "referrer_source" : "service",
        "clickTimestampSeconds" : 1550420123,
        "installBeginTimestampSeconds" : 1550420123,
        "current_device_time" : 1550420454906
      }

referrer_values = json.dumps(referrer_values, separators=(',',':')) params = { 'a': SDK_KEY, 'p': 'Android', 'i': 'com.singular.app', 'ip': '10.1.2.3', 've': '9.2', 'ma': 'samsung', 'mo': 'SM-G935F', 'lc': 'en_US', 'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b', 'andi': 'fc8d449516de0dfb', 'utime': 1483228800, 'dnt': 0, 'install':'true', 'n': 'MyCoolApp', 'c': 'wifi', 'cn': 'Comcast', 'bd': 'Build/13D15', 'fcm':'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1', 'app_v':'1.2.3', 'openuri':'myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1', 'ddl_enabled':'false', 'install_source': 'com.android.vending', 'install_time': 1510040127, 'update_time': 1510090877, 'custom_user_id': '123456789abcd', 'install_ref' : referrer_values } result = requests.get(LAUNCH_URL, params=params) print result.json()

Opcional: Envio do ID do usuário

Ao notificar a Singular sobre uma nova sessão, você pode adicionar o ID do usuário. Pode ser um nome de usuário, endereço de e-mail, string gerada aleatoriamente ou qualquer identificador que seu aplicativo use como ID de usuário. A Singular usará o ID do usuário em exportações de dados no nível do usuário, bem como em postbacks internos de BI (se você configurar algum).

Para enviar o ID do usuário, adicione o parâmetro "custom_user_id" ao chamar o Session Notification Endpoint.

Por exemplo:

Python HTTP cURL
import requests
import json
  
  SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  params = {
    'a': SDK_KEY,
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'andi': 'fc8d449516de0dfb',
    'utime': 1483228800,
    'dnt': 0,
    'install':'true',
    'n': 'MyCoolApp',
    'c': 'wifi',
    'cn': 'Comcast',
    'bd': 'Build/13D15',
    'fcm':'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1',
    'app_v':'1.2.3',
    'openuri':'myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1',
    'ddl_enabled':'false',
    'install_source': 'com.android.vending',
    'install_time': 1510040127,
    'update_time': 1510090877,
    'custom_user_id': 'player_id_1234'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

Tratamento adicional de atribuição

Atribuição para campanhas do Apple Search Ads (iOS)

OApple Search Ads é considerado uma rede de auto-atribuição (SAN). A partir do iOS 14.3, a integração do Apple Search Ads é suportada por meio de duas estruturas do iOS:

  • Para o iOS 14.2 e versões anteriores, o Apple Search Ads é compatível com a estrutura iAd.
  • Para o iOS 14.3 e superior, o Apple Search Ads é compatível com a estrutura AdServices.

Recomendamos que as estruturas iAd e AdServices sejam implementadas até que a estrutura iAd seja descontinuada em uma data futura. Como o AdServices ainda é um novo serviço da Apple, a Singular utilizará os dois serviços, mas priorizará o AdServices em relação aos sinais do iAd para atribuição e geração de relatórios.

Para obter mais informações, consulte nossa documentação de integração do Apple Search Ads.

Implementação do Apple Search Ads via iAd (iOS 14.2 e inferior)

1. Recuperação dos dadosde atribuição:

Para recuperar os dados de atribuição, use a API iAd do Apple Search Ads. Chamando requestAttributionDetails(_:):retorna um objeto JSON contendo os dados de atribuição.

Por exemplo:

Objective-C
#import <iAd/iAd.h>
  
    Class ADClientClass = NSClassFromString(@"ADClient");
  
    if (ADClientClass) {
        id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];
        
        if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
            [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
                if (attributionDetails && attributionDetails.count > 0) {
                    // Envie os detalhes de atribuição do iAd do aplicativo para o seu servidor.
                }
            }];
        }
    }
Aviso: Geralmente, os usuários que clicam em um anúncio do Search Ads baixam e abrem o aplicativo imediatamente. Se houver alguma latência nas comunicações, um MMP como o Singular pode não conseguir receber e processar o clique no anúncio a tempo de o aplicativo ser aberto e chamar a API de atribuição do Search Ads. Para evitar isso, a Apple recomenda:
  1. Definir um atraso de alguns segundos antes de recuperar os dados de atribuição.
  2. Implementar uma lógica de nova tentativa se a resposta for Falso ou um código de erro (0, 2, 3). Chame a API de atribuição da Apple novamente 2 segundos depois.

2. Enviando os dados de atribuição para a Singular:

Para compartilhar os dados de atribuição com a Singular, use o endpoint Event Notification para relatar um evento com o nome de evento reservado __iAd_Attribution__. Passe o objeto JSON que você recuperou na etapa anterior como o valor do parâmetro e , como no exemplo abaixo.

Python HTTP
import requests
import json
  
  SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
  EVENT_URL = 'https://s2s.singular.net/api/v1/evt'
  
  # !!! REPLACE WITH COLLECTED VALUE FROM APP !!!
  apple_attribution_data = {
    u'Version3.1': {
        u'iad-adgroup-id': u'1234567',
        u'iad-adgroup-name': u'Ad Group Name',
        u'iad-attribution': u'true',
        u'iad-campaign-id': u'1234567',
        u'iad-campaign-name': u'Search Campaign',
        u'iad-click-date': u'2016-05-21T12:19:31Z',
        u'iad-conversion-date': u'2016-05-21T12:19:41Z',
        u'iad-keyword': u'ballon',
        u'iad-lineitem-id': u'1234567',
        u'iad-lineitem-name': u'Line Item Name',
        u'iad-org-name': u'Cool Company',
        u'iad-purchase-date': u'2016-05-21T12:19:41Z'
    }
  }
  
  params = {
    'n': '__iAd_Attribution__',
    'e': json.dumps(apple_attribution_data),
    'a': SDK_KEY,
    'p': 'iOS',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'mo': 'iPhone9%2C4',
    'lc': 'en_US',
    'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
    'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
    'utime': 1483228800
  }
  
  result = requests.get(EVENT_URL, params=params)
  print result.json()

Observações:

  • No iOS 13+, você deve enviar o evento __iAd_Attribution__ imediatamente após a primeira sessão depois da instalação ou reinstalação. Caso contrário, os dados do Apple Search Ads não serão considerados para atribuição.
  • No iOS 14+, as respostas de atribuição do Apple Search Ads só estão disponíveis sob determinadas condições e não estão disponíveis se o status do AppTrackingTransparency for ATTrackingManager.AuthorizationStatus.denied.

Implementação do Apple Search Ads via AdServices (iOS 14.3 e superior)

1. Recuperação do token de atribuição:

Recupere o token de atribuição usando attributionToken() assim que o aplicativo for inicializado pela primeira vez após uma instalação ou reinstalação.

Por exemplo:

Objective-C
#import <AdServices/AdServices.h> 

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
if (!error && attributionToken) {
// Envie o AdServices AttributionToken do aplicativo para o seu servidor.
}
}

Observações:

  • O token de atribuição é gerado no dispositivo.
  • Após a geração, o token é armazenado em cache por 5 minutos no dispositivo. Após 5 minutos, um novo token é gerado se attributionToken() for chamado.
  • O token gerado é válido por 24 horas.

2. Envie o token de atribuição para a Singular:

Codifique o token por URL e envie-o para a Singular por meio do ponto de extremidade de notificação de sessão, anexado ao parâmetro &attribution_token=. Esse token deve ser enviado na primeira sessão após cada instalação e reinstalação para permitir que a Singular rastreie os downloads e os redownloads do Apple Search Ads.

Atribuição do referenciador de instalação do Meta Referrer (Android)

"Meta Referrer" é uma solução de medição específica para Android introduzida pelo Facebook para permitir que os anunciantes acessem dados granulares de atribuição em nível de usuário para instalações de aplicativos Android (consulte as políticas de dados do Facebook). Ela é composta pela implementação das tecnologias "Google Play Install Referrer" (consulte "Passando o Google Install Referrer") e "Meta Install Referrer" para a mensuração da instalação do aplicativo. Leia mais sobre o Meta Referrer nas Perguntas frequentes sobre o tópico.

Para compartilhar informações do Meta Install Referrer com a Singnular:

  1. Quando o aplicativo for aberto pela primeira vez, recupere o referenciador de instalação do Meta de acordo com a documentação do Meta.
  2. Relate uma sessão para a Singular usando o ponto de extremidade Session Notification, incluindo o parâmetro meta_ref. Esse parâmetro é codificado em JSON e tem os seguintes atributos:

    Atributo Descrição
    is_ct O "is_ct" conforme recebido do Meta Install Referrer. (por exemplo, 0 ou 1)
    install_referrer O "install_referrer" conforme recebido do Meta Install Referrer
    actual_timestamp O "actual_timestamp" conforme recebido do Meta Install Referrer (por exemplo, 1693978124).

Rastreamento de eventos

A Singular pode coletar dados sobre eventos in-app para ajudar a analisar o desempenho de suas campanhas de marketing. Os eventos podem incluir qualquer interação do usuário, desde logins e registros até a subida de nível em um aplicativo de jogos.

Antes de implementar uma integração SDK/S2S com a Singular, você deve ter uma lista dos eventos que sua organização deseja rastrear (consulte Definição de eventos no aplicativo).

Para notificar a Singular quando um evento ocorrer em seu aplicativo, chame o endpoint Event Notification. O nome do evento que você inclui na chamada é como o evento será identificado nos relatórios, exportações e postbacks do Singular.

Observações:

  • A Singular recomenda passar o evento usando a convenção padrão de nomenclatura de eventos e atributos da Singular. O uso de eventos padrão simplifica o mapeamento e a compatibilidade com os eventos padrão de seus parceiros em integrações.
  • É altamente recomendável passar nomes de eventos e outros atributos em inglês para compatibilidade com quaisquer parceiros e soluções analíticas de terceiros que você queira usar.
  • Os nomes de eventos são limitados a 32 caracteres ASCII. Para caracteres não ASCII, o limite é de 32 bytes após a conversão para UTF-8.
  • Os atributos e valores de eventos são limitados a 500 caracteres ASCII.

Rastreamento de receita

A Singular pode coletar dados sobre a receita obtida por meio do aplicativo para ajudar a analisar o desempenho e o ROI de suas campanhas. A Singular disponibilizará os dados para você em relatórios, exportação de registros e postbacks.

Para rastrear eventos de receita, use o mesmo endpoint de Notificação de evento que você usa para todos os eventos, mas adicione as seguintes informações:

  • is_revenue_event=true: marca o evento como um evento de receita. Você pode ignorar esse parâmetro se o nome do evento for __iap__ ou se o valor for maior que zero.
  • Recibo de compra: esse é um objeto retornado do processo de compra no aplicativo (IAP ) do Android ou do iOS. É altamente recomendável passá-lo para o Singular para que ele forneça detalhes completos sobre a transação e enriqueça seus relatórios do Singular com dados.
  • Assinatura da compra (somente Android): É altamente recomendável passar esses dados para a Singular para validar a transação e combater fraudes no aplicativo.
  • Valor da receita (por exemplo, "amt=1,99").
  • Moeda (use o código de moeda ISO 4217, por exemplo, "cur=USD").

Recuperação do recibo de compra

Após a ocorrência de um evento de receita, veja como obter o recibo de compra para que você possa enviá-lo à Singular:

  • No Android: O Google Play fornece uma API para recuperar o recibo de compra ("In-App Purchase Data") e a assinatura da compra ("In-App Data Signature"). Use o método getBuyIntent().
  • No iOS: Use a API In-App Purchases da Apple, conforme mostrado no exemplo abaixo (para obter mais informações, consulte API In-App Purchases da Apple).
Objetivo-C
// SKPaymentTransactionObserver
    + (void)paymentQueue:(id)queue updatedTransactions:(NSArray *)skTransactions {
       NSString *transactionReceipt = nil;
  
       if ([skTransaction respondsToSelector:@selector(transactionReceipt)]) {
          NSData *transactionReceiptRaw = [skTransaction performSelector:@selector(transactionReceipt)];
          if (transactionReceiptRaw) {
             transactionReceipt = [ApUtils base64Encode:transactionReceiptRaw];
          }
       }
    }

Exemplo de evento de receita personalizado

Python HTTP cURL
import requests
import json SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].' EVENT_URL = 'https://s2s.singular.net/api/v1/evt' params = { 'a': SDK_KEY, 'p': 'Android', 'i': 'com.singular.app', 'ip': '10.1.2.3', 've': '9.2', 'ma': 'samsung', 'mo': 'SM-G935F', 'lc': 'en_US',
'bd': 'Build/13D15', 'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b', 'utime': 1483228800, 'n': 'RevenueEventName',
'amt': '2.50', 'cur': 'USD',
'is_revenue_event': 'true',
'purchase_receipt': {'orderId"':'GPA.1234',
'packageName':'com.example',
'productId':'com.example.product',
'purchaseTime':1417113074914,
'purchaseState':0,
'purchaseToken':'hakfcimbk... pM'},
'receipt_signature': 'TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==',
'purchase_product_id': 'com.example.product',
'purchase_transaction_id': 'GPA.1234-1234-1234-12345' } result = requests.get(EVENT_URL, params=params) print result.json()

Suporte a deep links

Deep links são links que levam a um conteúdo específico dentro de um aplicativo. Quando um usuário clica em um link profundo em um dispositivo que tem o aplicativo instalado, o aplicativo é aberto e mostra um produto ou uma experiência específica.

Os links de rastreamento singulares podem incluir links diretos, bem como links diretos adiados (consulte nossas Perguntas frequentes sobre links diretos e as Perguntas frequentes sobre links singulares para obter mais informações).

Pré-requisitos do Deep Linking

Para iOS:

Para Android:

Suporte a deep links

Sempre que seu aplicativo for aberto por meio de um deep link, adicione a URL ao relatar a sessão ao Singular usando o parâmetro openuri. Isso é necessário ao usar Singular Links.

Ativação de Deep Links diferidos

Quando o aplicativo for aberto pela primeira vez desde a instalação, ative o fluxo de deep linking diferido adicionando os seguintes parâmetros ao relatar a sessão para a Singular:

  • install=true
  • ddl_enabled=true

A Singular verifica se o aplicativo foi instalado por meio de um link de rastreamento que incluía um deferred deep link. Se tiver sido, a chamada retorna os seguintes valores:

  • deferred_deeplink - o endereço do deep link. Isso é o que você precisa analisar para mostrar aos usuários o produto ou a experiência correta.
  • deferred_passthrough - qualquer parâmetro passthrough adicionado ao deep link.

Exemplo de chamada de notificação de sessão com suporte a Deferred Deep Link

Python
import requests
import json
  
      SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
      LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
      params = {
          'a': SDK_KEY,
          'p': 'iOS',
          'i': '162738612',
          'ip': '10.1.2.3',
          've': '9.2',
          'mo': 'iPhone9%2C4',
          'lc': 'en_US',
          'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
          'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
          'utime': 1483228800,
          'dnt': 0,
          'n': 'MyCoolApp',
          'c': 'wifi',
          'cn': 'Comcast',
          'bd': 'Build/13D15',
          'openuri':'https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue',
          'install':'true',
          'ddl_enabled':'true'
      }
  
      result = requests.get(LAUNCH_URL, params=params)
      print result.json()

Exemplo de resposta

{
    "deferred_deeplink":"myapp://deferred-deeplink",
    "status":"ok",
    "deferred_passthrough":"passthroughvalue"
  }

Manuseio de links curtos singulares

Quando o aplicativo é aberto a partir de um link curto Singular, o parâmetro a seguir deve ser enviado na solicitação de inicialização para notificar o ponto de extremidade Singular de que a url enviada em openuri deve ser resolvida para o link longo Singular.

  • singular_link_resolve_required=true

O Singular retorna o link longo e o desenvolvedor de aplicativos pode analisar os parâmetros de deep link e passthrough no manipulador de links.

Exemplo de chamada de notificação de sessão com resolução de link curto

Python
import requests
import json
  
      SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
      LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
      params = {
          'a': SDK_KEY,
          'p': 'iOS',
          'i': '162738612',
          'ip': '10.1.2.3',
          've': '9.2',
          'mo': 'iPhone9%2C4',
          'lc': 'en_US',
          'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
          'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
          'utime': 1483228800,
          'dnt': 0,
          'n': 'MyCoolApp',
          'c': 'wifi',
          'cn': 'Comcast',
          'bd': 'Build/13D15',
          'openuri':'https://myapp.sng.link/A59c0/nha7/q5a2',
          'singular_link_resolve_required':'true',
      }
  
      result = requests.get(LAUNCH_URL, params=params)
      print result.json()

Exemplo de resposta

{
    "status":"ok",
    "resolved_singular_link":"https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
  }

Suporte a parâmetros dinâmicos de passagem

Os links de rastreamento da Singular podem incluir parâmetros dinâmicos de passagem (saiba mais). Se a sua organização tiver configurado parâmetros dinâmicos de passagem para um link, o URL do deep link incluirá o parâmetro _p seguido por um valor JSON codificado por URL ou uma string não estruturada que você pode usar para mostrar ao usuário o conteúdo ou a experiência apropriada.

Opções avançadas

A integração do Singular S2S é compatível com os seguintes recursos avançados. Eles são implementados usando os mesmos endpoints de API descritos acima, mas com parâmetros e requisitos especiais.

Rastreamento de desinstalações

A Singular pode rastrear desinstalações usando as notificações push silenciosas do dispositivo. Para habilitá-lo, você precisará enviar o token push do dispositivo para o servidor Singular junto com cada notificação de sessão.

Rastreamento de desinstalações no Android

Para ativar o rastreamento de desinstalação no Android, primeiro recupere o token FCM do aplicativo chamando FirebaseInstanceId.getInstance().getToken(). Esse método retorna nulo se o token ainda não tiver sido gerado. Para obter mais informações, consulte a documentação do Google Firebase.

Em seguida, passe o token do dispositivo no parâmetro fcm ao relatar a sessão para o Singular, como no exemplo a seguir:

Python HTTP cURL
import requests
import json
  
  SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  params = {
    'a': SDK_KEY,
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'andi': 'fc8d449516de0dfb',
    'utime': 1483228800,
    'dnt': 0,
    'n': 'MyCoolApp',
    'c': 'wifi',
    'cn': 'Comcast',
    'bd': 'Build/13D15',
    'fcm': 'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

Rastreamento de desinstalações no iOS

A Singular pode rastrear desinstalações no iOS usando as notificações push da Apple. Se seu aplicativo ainda não for compatível com as notificações por push, consulte o guia da Apple. Quando seu aplicativo for compatível com as notificações por push, passe o token do dispositivo retornado do APNS ao relatar a sessão para a Singular.

Observações:

  • Presumimos que você já tenha uma implementação de notificação por push da qual está recuperando um token de dispositivo.
  • O token APNS geralmente é um dado binário no formato nativo. Passe-o para a Singular como recebido do APNS. Se o seu aplicativo estiver alterando o tipo de dados do token para outra finalidade, certifique-se de passá-lo como uma cadeia de caracteres codificada em hexadecimal, por exemplo: encodedb0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052
Python HTTP cURL
import requests
import json
  
  SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  params = {
    'a': SDK_KEY,
    'p': 'iOS',
    'i': '162738612',
    'ip': '10.1.2.3',
    've': '9.2',
    'mo': 'iPhone9%2C4',
    'lc': 'en_US',
    'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
    'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
    'utime': 1483228800,
    'dnt': 0,
    'n': 'MyCoolApp',
    'c': 'wifi',
    'cn': 'Comcast',
    'bd': 'Build/13D15',
    'apns_token': 'b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

Conformidade com as leis de privacidade de dados

A Singular fornece a funcionalidade de proteção da privacidade para ajudá-lo a cooperar com quaisquer parceiros que possam estar em conformidade com as leis de privacidade do consumidor, como GDPR e CCPA. Esses parceiros querem ser notificados se o usuário final consentiu em compartilhar suas informações privadas.

Se você tiver implementado uma forma de solicitar o consentimento dos usuários para compartilhar suas informações, use os parâmetros data_sharing_options para notificar a Singular sobre a escolha do usuário:

  • Passe "limit_data_sharing":false para indicar que o usuário consentiu (optou por participar) em compartilhar suas informações.
  • Passe "limit_data_sharing":true se o usuário recusou.

A Singular usa limit_data_sharing em "Postbacks de privacidade do usuário", bem como repassa essas informações a parceiros que as exigem para cumprir os regulamentos relevantes. Consulte "Privacidade do usuário e limite de compartilhamento de dados" para obter mais informações.

Observação:

  • O uso do método é opcional, mas pode haver informações de atribuição que o parceiro compartilhará com a Singular somente se for especificamente notificado de que o usuário optou por participar.
  • Lembre-se de codificar a URL do objeto JSON se você o passar em uma solicitação GET.
Campo Tipo de campo Descrição do campo Uso
limit_data_sharing boolean

Passe esse valor opcional em cada solicitação de inicialização ou evt para indicar as preferências do usuário final.

data_sharing_options=
%7B%22limit_data_sharing%22%3Atrue%7D

Referência: Recuperação do recibo de instalação do iOS

Como você pode ver na referência do ponto final Session Notification, ao relatar uma sessão para um aplicativo iOS, você deve passar o recibo de instalação no parâmetro install_receipt.

Para recuperar esse valor, adicione o seguinte código ao seu aplicativo:

Objective-C
+ (NSString*)installReceipt {
      // install receipts are iOS 7.0+
      if (NSFoundationVersionNumber < NSFoundationVersionNumber_iOS_7_0) {
          return nil;
      }
      
      NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
      
      if (receiptURL) {
          NSData *receipt = [NSData dataWithContentsOfURL:receiptURL];
          
          if (receipt) {
              return [receipt base64EncodedStringWithOptions:0];
          }
      }
      
      return nil;
  }

Referência: Recuperação de identificadores de dispositivos e dados de sessão

Esta seção detalha como você pode recuperar determinados valores exigidos na API REST. Esses valores são padrão do setor, e a Apple e o Google também têm documentação sobre eles. Fornecemos algumas implementações de referência para sua conveniência.

Recuperação do ID de publicidade do Google/Limite de rastreamento de anúncios (identificadores do Android)

O SDK do Google Play Services é necessário para obter o ID de publicidade em seu aplicativo. Adicione a seguinte tag como um elemento filho do seu aplicativo em AndroidManifest.xml:

XML
<meta-data android:name="com.google.android.gms.version"
             android:value="@integer/google_play_services_version" />

Se a compilação do seu aplicativo estiver direcionada para o Android 12/API nível 31 ou superior, adicione permissões para acessar o ID de publicidade do Google:

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

Código de amostra para obter os parâmetros de ID de publicidade do Google/Limite de rastreamento de anúncios:

Java
import com.google.android.gms.ads.identifier.AdvertisingIdClient;
import com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
import com.google.android.gms.common.GooglePlayServicesAvailabilityException;
import com.google.android.gms.common.GooglePlayServicesNotAvailableException;
import java.io.IOException;
  
  // Não chame esta função do thread principal. Caso contrário, uma IllegalStateException será lançada.
  public void getIdAndLAT() {
      Info adInfo = null;
      try {
          adInfo = AdvertisingIdClient.getAdvertisingIdInfo(mContext);
      } catch (IOException e) {
          // Erro irrecuperável ao conectar-se aos serviços do Google Play (por exemplo, a versão antiga do serviço não oferece suporte à obtenção de AdvertisingId).
      } catch (GooglePlayServicesAvailabilityException e) {
          // Encontrou um erro recuperável ao conectar-se aos serviços do Google Play.
      } catch (GooglePlayServicesNotAvailableException e) {
          // Os serviços do Google Play não estão totalmente disponíveis.
      }
  
final String GAID = adInfo.getId(); final boolean limitAdTracking = adInfo.isLimitAdTrackingEnabled(); }

Recuperação de localidade, dispositivo e compilação para Android

Java
  // Locale - lc= query parameter
  String locale = Locale.getDefault();
  
  // Model - mo= query parameter
  String device = Build.MODEL;
  
  // Build - bd= query parameter
  String build = "Build/" + Build.ID;

Recuperação do status de autorização do App Tracking Transparency (iOS)

A partir do iOS 14.5, o App Tracking Transparency é necessário para recuperar o IDFA do dispositivo. Se você mostrar o prompt do App Tracking Transparency, certifique-se de implementar o prompt e o manipulador antes de tentar recuperar o IDFA.

Abaixo está um exemplo de como implementar o prompt ATT (opcional) e como recuperar o status de autorização ATT (obrigatório):

Objective-C
#import <AppTrackingTransparency/ATTrackingManager.h>
  
// OPCIONAL se você decidir mostrar o prompt ATT. Mostrar prompt e manipular o valor. Aparecerá apenas uma vez, mesmo se for chamado várias vezes [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status){ // your authorization handler here }];
// OBRIGATÓRIO Leitura do status atual de autorização ATT ATTrackingManagerAuthorizationStatus status = [ATTrackingManager trackingAuthorizationStatus];

Recuperação do IDFA/limite de rastreamento de anúncios (identificadores do iOS)

Apartir do iOS 14.5, o App Tracking Transparency é necessário para recuperar o IDFA. Se você decidir mostrar o prompt do App Tracking Transparency, certifique-se de implementar o prompt e o manipulador antes de tentar recuperar o IDFA.

Se você não planeja exibir o App Tracking Transparency, o IDFA ainda poderá ser recuperado (o valor será zero). O IDFV deve ser recuperado e enviado em qualquer caso, já que o Singular volta a ele se o IDFA não estiver disponível ou estiver todo zerado.

O sinalizador limit-ad-track(isAdvertisingTrackingEnabled) é obrigatório para o iOS 13 e versões anteriores e é usado para indicar se um usuário optou por não aceitar o rastreamento de anúncios. Para iOS 14+, o sinalizador está obsoleto e é um valor estático se recuperado. A Singular e seus parceiros confiarão no valor mais recente do status de autorização da ATT para o tratamento de dados dos fluxos de privacidade.

Abaixo está um exemplo de recuperação do IDFA, IDFV e do status de limitação de rastreamento de anúncios:

Objective-C Swift
// Importe a classe AdSupport na parte superior do seu arquivo
@import AdSupport;

Código de amostra para obter os parâmetros IDFA/Limit Ad Tracking:

Objective-C Swift
  NSString* IDFA = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
  NSString* IDFV = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
  
  BOOL isAdvertisingTrackingEnabled = [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled];

Recuperação de localidade, dispositivo e compilação para iOS

Objective-C Swift
  // Locale - lc= query parameter
  NSString *locale = [[NSLocale currentLocale] localeIdentifier];
  
  // Model - mo= query paramter
  #import <sys/sysctl.h>
  NSString *device() {
      size_t bufferSize = 64;
      NSMutableData * buffer = [[NSMutableData alloc] initWithLength:bufferSize];
      int status = sysctlbyname("hw.machine", buffer.mutableBytes, &bufferSize, NULL, 0);
      if (status != 0) {
          return nil; 
      }
      return [[NSString alloc] initWithData:buffer encoding:NSUTF8StringEncoding];
  }
  
  // Build - bd= query parameter
  NSString * build () { 
      size_t bufferSize = 64;
      NSMutableData *buffer = [[NSMutableData alloc] initWithLength:bufferSize];
      int status = sysctlbyname("kern.osversion",buffer.mutableBytes, &bufferSize, NULL, 0);
      if (status != 0) {
          return nil;
      }
      return [[NSString alloc] initWithData:buffer encoding:NSUTF8StringEncoding];
  }