Referência da API do Endpoint SESSION
Rastreie sessões de usuários 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 de SDK.
Visão geral
Caso de uso Server-to-Server
O endpoint SESSION notifica a Singular quando um usuário abre seu app, alimentando a atribuição de instalação e de reengajamento e as métricas de retenção. Novo em Server-to-Server? Consulte o guia de Fundamentos de S2S para conceitos básicos e configuração compartilhada.
Recursos suportados:
- Atribuição de instalação: Atribuição first-touch a campanhas de marketing
- Atribuição de reengajamento: Atribuição multi-touch para usuários recorrentes
- Métricas de retenção: Rastreamento de engajamento baseado em sessões
Gerenciamento de sessões
O endpoint SESSION notifica a Singular sobre eventos de abertura do app para inicializar as sessões de usuários 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 de um estado totalmente fechado
- De segundo plano para 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 o timeout de sessão para evitar requisições SESSION excessivas durante breves períodos do app 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 temporizadores para gerenciar o estado da sessão
Suporte a deep link:
Sempre envie SESSION para aberturas do app via deep links, Universal Links ou App Links com o parâmetro
openuri
preenchido, independentemente do status de timeout.
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.
| Tipo de sessão | Processamento da Singular | Resultado da atribuição |
|---|---|---|
| Primeira sessão (nova instalação) | Processo de atribuição de instalação acionado | Atribui a instalação a uma campanha de marketing |
| Qualificada para reengajamento | Processo de atribuição de reengajamento acionado | Atribui o retorno do usuário a uma campanha ou deep link |
| Sessão padrão | Sessão registrada para rastreamento de retenção | Conta para as métricas de atividade e engajamento do usuário |
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.
Regras críticas de ordenação:
- Sessão antes dos eventos: Uma única SESSION deve ser recebida antes de quaisquer eventos daquela sessão
- Transmissão de eventos em tempo real: Os eventos in-app devem ser enviados em tempo real após a respectiva sessão
- Processamento sequencial: Uma ordem de sessão inválida resulta em inconsistências de dados e erros de atribuição
Especificação do Endpoint da API
O endpoint SESSION aceita requisições POST com parâmetros enviados como
application/x-www-form-urlencoded
.
Endpoint
URL base e método
POST https://s2s.singular.net/api/v1/launchCabeçalho obrigatório:
Content-Type: application/x-www-form-urlencodedFormato da requisição:
POST /api/v1/launch HTTP/1.1
Host: s2s.singular.net
Content-Type: application/x-www-form-urlencoded
param1=value1¶m2=value2Parâmetros obrigatórios
Todas as requisições SESSION devem incluir estes parâmetros obrigatórios com valores e formatação adequados.
Autenticação da API
SDK Key
| Parâmetro | Detalhes |
|---|---|
a
|
Tipo:
String
Importante: Não use a Reporting API Key. As requisições serão rejeitadas.
Exemplo:
|
Identificadores de dispositivo
Identificadores específicos da plataforma
| Parâmetro | Detalhes |
|---|---|
idfa
|
Plataforma:
iOS
|
idfv
|
Plataforma:
iOS
|
aifa
|
Plataforma:
Android
|
asid
|
Plataforma:
Android
|
amid
|
Plataforma:
Android
|
oaid
|
Plataforma:
Android
|
andi
|
Plataforma:
Android
Uso restrito: Proibido em dispositivos Google Play — use AIFA e ASID em vez disso. Envie somente se nenhum outro identificador estiver disponível e o app não for distribuído via Google Play.
Exemplo:
|
sdid
|
Plataforma:
iOS, Android, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV
|
Parâmetros de dispositivo
Informações do dispositivo
| Parâmetro | Detalhes |
|---|---|
p
|
Tipo:
String
|
ip
|
Tipo:
String
|
ve
|
Tipo:
String
|
ma
|
Plataforma:
iOS, Android
|
mo
|
Plataforma:
iOS, Android
|
lc
|
Plataforma:
iOS, Android
|
bd
|
Plataforma:
iOS, Android
|
Parâmetros da aplicação
Informações do app
| Parâmetro | Detalhes |
|---|---|
i
|
Tipo:
String
|
app_v
|
Tipo:
String
|
att_authorization_status
|
Plataforma:
iOS
Sempre obrigatório:
Mesmo que o ATT não seja implementado, passe
Exemplo:
|
| Parâmetro | Detalhes |
|---|---|
install
|
Tipo:
Boolean
|
install_time
|
Plataforma:
iOS, Android
Este é o horário de instalação do dispositivo, não o horário de instalação de atribuição da Singular. A atribuição usa o timestamp da sessão (
Consulte o Guia de Recuperação de Dados do Dispositivo para saber como obter esse valor no iOS e no Android. |
update_time
|
Plataforma:
iOS, Android
Consulte o Guia de Recuperação de Dados do Dispositivo para saber como obter esse valor no iOS e no Android. |
Parâmetros de prevenção de fraude
Validação da origem de instalação
| Parâmetro | Detalhes |
|---|---|
install_source
|
Plataforma:
Android, PC
|
install_receipt
|
Plataforma:
iOS
|
Parâmetros de deep linking
Suporte a deep link
| Parâmetro | Detalhes |
|---|---|
openuri
|
Plataforma:
iOS, Android
|
ddl_enabled
|
Plataforma:
iOS, Android
|
singular_link_resolve_required
|
Plataforma:
iOS, Android
|
Parâmetros avançados de atribuição
Aprimoramento de atribuição por plataforma
| Parâmetro | Detalhes |
|---|---|
install_ref
PC Nativo (Google Play Games)
|
Plataforma:
Android (Google Play)
|
meta_ref
|
Plataforma:
Android (Google Play)
A partir de 18 de junho de 2025: Meta Advanced Mobile Measurement (AMM) elimina a necessidade de implementar o Meta Install Referrer. Não recomendado se o AMM estiver ativado.
Meta Install Referrer em JSON codificado em URL para dados de atribuição granulares em nível de usuário.
|
attribution_token
|
Plataforma:
iOS
|
Parâmetros opcionais
Os parâmetros opcionais aprimoram os recursos de rastreamento e oferecem suporte a recursos avançados.
Parâmetros de timestamp
| Parâmetro | Detalhes |
|---|---|
utime
|
Tipo:
Integer
|
umilisec
|
Tipo:
Integer
|
Parâmetros de rede e localização
| Parâmetro | Detalhes |
|---|---|
use_ip
|
Tipo:
Boolean
Limitações:
Exemplo:
|
country
|
Tipo:
String
|
ua
|
Tipo:
String
|
c
|
Plataforma:
iOS, Android
|
cn
|
Plataforma:
iOS, Android
|
Propriedades personalizadas
| Parâmetro | Detalhes |
|---|---|
global_properties
|
Tipo:
JSON
|
Suporte a rastreamento de desinstalação
| Parâmetro | Detalhes |
|---|---|
apns_token
|
Plataforma:
iOS
|
fcm
|
Plataforma:
Android
|
Parâmetros de privacidade de dados
| Parâmetro | Detalhes |
|---|---|
data_sharing_options
|
Tipo:
JSON
|
dnt
|
Plataforma:
iOS, Android
|
dntoff
|
Plataforma:
iOS, Android
|
Suporte a múltiplos dispositivos
| Parâmetro | Detalhes |
|---|---|
custom_user_id
|
Tipo:
String
Sem PII: Não passe informações de identificação pessoal. Use um identificador interno com hash ou anonimizado de outra forma, não endereços de e-mail, números de telefone ou nomes brutos.
Exemplo:
|
Suporte a SKAdNetwork
| Parâmetro | Detalhes |
|---|---|
skan_conversion_value
|
Plataforma:
iOS
|
skan_first_call_timestamp
|
Plataforma:
iOS
|
skan_last_call_timestamp
|
Plataforma:
iOS
|
Suporte a Google Ads ICM (Beta)
| Parâmetro | Detalhes |
|---|---|
odm_info
|
Plataforma:
iOS
|
odm_error
|
Plataforma:
iOS
|
Exemplos de requisição
O código de exemplo demonstra a integração do endpoint SESSION em várias linguagens de programação.
Aviso sobre os exemplos:
Os exemplos de código podem não incluir todos os parâmetros obrigatórios. Valide a lista completa de parâmetros antes da implementação em produção. Use um
i
(identificador do app) exclusivo para desenvolvimento/testes.
Exemplo em Python
import requests
url = 'https://s2s.singular.net/api/v1/launch'
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
data = {
'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.post(url, data=data, headers=headers)
print(response.json())Exemplo em cURL
curl -X POST "https://s2s.singular.net/api/v1/launch" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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"Exemplo em HTTP
POST /api/v1/launch HTTP/1.1
Host: s2s.singular.net
Content-Type: application/x-www-form-urlencoded
Accept: application/json
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=1510090877Exemplo em Java
// Endpoint
String endpoint = "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 form-urlencoded body
StringBuilder form = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
if (form.length() > 0) form.append('&');
form.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
.append('=')
.append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
byte[] body = form.toString().getBytes(StandardCharsets.UTF_8);
// Create connection
URL url = new URL(endpoint);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setRequestProperty("Accept", "application/json");
// Write body
try (OutputStream os = conn.getOutputStream()) {
os.write(body);
}
// 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();
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
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 e Tratamento de Erros de S2S
Testes e validação
Verifique a integração S2S antes da implantação em produção usando o Singular SDK Console para validação de dados em tempo real.
Procedimento de teste
Validação de ponta a ponta
- Registre o dispositivo de teste: Obtenha o advertising ID do dispositivo e adicione ao Singular SDK Console
- Ative o log do Console: Adicione o identificador do dispositivo no SDK Console para capturar os dados de teste
-
Use um App ID de desenvolvimento:
Substitua o identificador do app pela versão de desenvolvimento (ex.:
com.singular.app.dev) para separar os dados de teste dos de produção - Abra o app: Abra o app a partir do estado encerrado para acionar a sessão
- Valide os dados do cliente: Confirme que o app envia todos os pontos de dados obrigatórios da Singular para o seu servidor
-
Verifique a requisição do servidor:
Confirme que o seu servidor envia a requisição SESSION para
https://s2s.singular.net/api/v1/launchcom todos os parâmetros obrigatórios - Verifique o SDK Console: Em segundos, o evento SESSION deve aparecer no SDK Console
- Repita os testes: Valide que a SESSION é acionada em cada entrada no app e operação em primeiro plano
Verificação crítica: Confirme que o evento SESSION ocorre na abertura/primeiro plano do app ANTES de qualquer requisição EVENT. Uma ordem inválida causa erros de atribuição.
Indicador de sucesso: Se a SESSION aparecer no SDK Console, você concluiu com sucesso o teste de integração de ponta a ponta!
Recursos adicionais
Documentação de testes
Guia completo de testes: Guia de Testes de Integração S2S