Referência da API do Endpoint SESSION

Rastreie sessões de usuário e habilite a atribuição para instalações de apps, reengajamento e métricas de retenção por meio da API REST da Singular usando integração server-to-server como alternativa à implementação por SDK.

Visão geral

Caso de uso Server-to-Server

A API REST da Singular permite a integração direta server-to-server, na qual os apps encaminham dados específicos do dispositivo para o seu backend, que os transmite aos servidores da Singular para processamento de atribuição e geração de relatórios de análise.

Recursos suportados:

• Atribuição de instalação: Atribuição de primeiro toque a campanhas de marketing
• Atribuição de reengajamento: Atribuição multitoque para usuários recorrentes
• Métricas de retenção: Rastreamento de engajamento baseado em sessão
• Rastreamento de eventos: Medição de eventos in-app personalizados

Arquitetura do fluxo de dados

A integração server-to-server segue um processo de transmissão de dados em quatro etapas.

1. Coleta no cliente: O app coleta os dados obrigatórios do dispositivo e da aplicação
2. Transmissão ao servidor: O app encaminha os dados coletados para o seu servidor backend
3. Chamada à API da Singular: Seu servidor envia os dados para o endpoint da API REST da Singular
4. Tratamento da resposta: Seu servidor recebe e processa a resposta da Singular

Considerações importantes

Benefícios da integração:

• Flexibilidade: Controle total sobre a coleta de dados e o momento da transmissão
• Paridade de recursos: Suporta todas as funcionalidades do SDK quando os dados adequados são fornecidos
• Implementação personalizada: Adapte a integração à arquitetura específica do seu backend

Gerenciamento de sessões

O endpoint SESSION notifica a Singular sobre eventos de abertura do app para inicializar as sessões de usuário para atribuição e rastreamento.

Quando enviar sessões

Gatilhos de sessão

Envie requisições SESSION para estes eventos do ciclo de vida do app:

• Instalações novas: Primeira abertura do app após a instalação
• Abertura a partir do estado encerrado: O app abre a partir do estado totalmente fechado
• Do segundo plano para o primeiro plano: O app retorna ao primeiro plano após o período de timeout (recomendado: 60 segundos)

Lógica de timeout de sessão

Implemente um timeout de sessão para evitar requisições SESSION excessivas durante breves períodos em que o app fica em segundo plano.

Implementação recomendada:

• Duração do timeout: 60 segundos (1 minuto)
• Primeiro plano < timeout: Não envie SESSION se o app retornar ao primeiro plano dentro do período de timeout
• Primeiro plano > timeout: Envie SESSION se o app permanecer em segundo plano além do período de timeout
• Rastreamento do ciclo de vida do app: Use eventos do ciclo de vida do app e timers para gerenciar o estado da sessão

Processamento de atribuição

Atribuição baseada em sessão

A Singular processa as requisições SESSION para determinar o tipo de atribuição e acionar os fluxos de trabalho apropriados.

Saiba mais: FAQ de atribuição de reengajamento

Requisitos de ordem dos eventos

O momento das sessões e dos eventos impacta diretamente a precisão da atribuição e a qualidade dos dados.

Opções avançadas

Funcionalidades estendidas

A integração S2S da Singular suporta recursos avançados que exigem parâmetros SESSION adicionais.

Especificação do endpoint da API

O endpoint SESSION aceita requisições GET com parâmetros de query contendo dados de dispositivo, aplicação e atribuição.

URL do endpoint

URL base e método

GET https://s2s.singular.net/api/v1/launch

Formato da requisição:

GET /api/v1/launch?param1=value1&param2=value2

Parâmetros obrigatórios

Todas as requisições SESSION devem incluir estes parâmetros obrigatórios com os valores e a formatação adequados.

Autenticação da API

SDK Key

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Identificadores de dispositivo

Identificadores específicos da plataforma

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Parâmetros de dispositivo

Informações do dispositivo

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Parâmetros de aplicação

Informações do app

O identificador do app ( i ), app_v e att_authorization_status são parâmetros compartilhados. Consulte Parâmetros de aplicação em Fundamentos de S2S .

Parâmetros de prevenção de fraude

Validação da fonte de instalação

Parâmetros de deep linking

Suporte a deep link

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

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

Parâmetros avançados de atribuição

Aprimoramento de atribuição por plataforma

{
   "installBeginTimestampSeconds":"1568939453",
   "referrer":"utm_source=google-play&utm_medium=organic",
   "clickTimestampSeconds":"0",
   "referrer_source":"service",
   "current_device_time":"1568944524"
}

{
   "install_time_epoch_seconds":"1568939453",
   "install_referrer":"utm_source=google-play&utm_medium=organic"
}

{
  "install_referrer": {
    "utm_source":"apps.facebook.com",
    "utm_campaign": "fb4a",
    "utm_content": {
      "source":{
        "data":"c7e6b890bf18a059c2185650bdb1af3dced7...",
        "nonce":"24859720343e2381daee9f39ae61"
        },
      "app":533744218636280,
      "t":1731181327
      },
    "is_ct":1,
    "actual_timestamp":1731181444
  }
}

Parâmetros opcionais

Os parâmetros opcionais aprimoram os recursos de rastreamento e dão suporte a recursos avançados.

Parâmetros de timestamp

Parâmetros de rede e localização

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Propriedades personalizadas

Suporte a rastreamento de desinstalação

Parâmetros de privacidade de dados

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Suporte entre dispositivos

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Suporte a SKAdNetwork

Suporte a Google Ads ICM (Beta)

Exemplos de requisição

Os exemplos de código demonstram a integração com o endpoint SESSION em várias linguagens de programação.

import requests

params = {
    'a': 'sdk_key_here',
    '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',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'install': 'true',
    'n': 'MyCoolAppName',
    'bd': 'Build/13D15',
    'app_v': '1.2.3',
    'openuri': 'myapp://home/page?queryparam1=value1',
    'ddl_enabled': 'true',
    'install_source': 'com.android.vending',
    'install_time': 1510040127,
    'update_time': 1510090877
}

response = requests.get('https://s2s.singular.net/api/v1/launch', params=params)
print(response.json())

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=sdk_key_here" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.singular.app" \
  --data-urlencode "ip=10.1.2.3" \
  --data-urlencode "ve=9.2" \
  --data-urlencode "ma=samsung" \
  --data-urlencode "mo=SM-G935F" \
  --data-urlencode "lc=en_US" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "install=true" \
  --data-urlencode "n=MyCoolAppName" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "app_v=1.2.3" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1" \
  --data-urlencode "ddl_enabled=true" \
  --data-urlencode "install_source=com.android.vending" \
  --data-urlencode "install_time=1510040127" \
  --data-urlencode "update_time=1510090877"

GET /api/v1/launch
    ?a=sdk_key_here
    &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
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &install=true
    &n=MyCoolAppName
    &bd=Build%2F13D15
    &app_v=1.2.3
    &openuri=myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1
    &ddl_enabled=true
    &install_source=com.android.vending
    &install_time=1510040127
    &update_time=1510090877 HTTP/1.1
Host: s2s.singular.net
Accept: application/json

// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/launch";

// Parameters
Map<String, String> params = new HashMap<>();
params.put("a", "sdk_key_here");
params.put("p", "Android");
params.put("i", "com.singular.app");
params.put("ip", "10.1.2.3");
params.put("ve", "9.2");
params.put("ma", "samsung");
params.put("mo", "SM-G935F");
params.put("lc", "en_US");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("install", "true");
params.put("n", "MyCoolAppName");
params.put("bd", "Build/13D15");
params.put("app_v", "1.2.3");
params.put("openuri", "myapp://home/page?queryparam1=value1");
params.put("ddl_enabled", "true");
params.put("install_source", "com.android.vending");
params.put("install_time", "1510040127");
params.put("update_time", "1510090877");

// Build URL with encoded parameters
StringBuilder urlBuilder = new StringBuilder(baseUrl);
urlBuilder.append('?');

for (Map.Entry<String, String> entry : params.entrySet()) {
    if (urlBuilder.length() > baseUrl.length() + 1) {
        urlBuilder.append('&');
    }
    urlBuilder.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
        .append('=')
        .append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}

// Create connection
URL url = new URL(urlBuilder.toString());
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

// Get response
int responseCode = conn.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(conn.getInputStream())
);

String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();

// Check status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

Códigos de resposta e erros

O endpoint SESSION retorna códigos de status HTTP e respostas JSON indicando o sucesso ou a falha da requisição.

Documentação completa de erros: Códigos de resposta de S2S e tratamento de erros

Teste e validação

Verifique a integração S2S antes da implantação em produção usando o SDK Console da Singular para validação de dados em tempo real.

Procedimento de teste

Validação de ponta a ponta

1. Registrar dispositivo de teste: Obtenha o ID de publicidade do dispositivo e adicione-o ao SDK Console da Singular
2. Habilitar log no Console: Adicione o identificador do dispositivo no SDK Console para capturar os dados de teste
3. Usar o App ID de desenvolvimento: Substitua o identificador do app pela versão de desenvolvimento (por exemplo, com.singular.app.dev ) para separar os dados de teste dos de produção
4. Abrir o app: Abra o app a partir do estado encerrado para acionar a sessão
5. Validar os dados do cliente: Confirme que o app envia todos os dados obrigatórios da Singular ao seu servidor
6. Verificar a requisição do servidor: Confirme que seu servidor envia a requisição SESSION para https://s2s.singular.net/api/v1/launch com todos os parâmetros obrigatórios
7. Verificar o SDK Console: Em poucos segundos, o evento SESSION deve aparecer no SDK Console
8. Repetir os testes: Valide que a SESSION é acionada a cada entrada no app e operação de primeiro plano

Recursos adicionais

Documentação de teste

Guia abrangente de testes: Guia de testes de integração S2S