Documento

Referência de pontos finais da API para PC e console

Referência completa da API para pontos finais servidor-a-servidor para PC e console, fornecendo especificações detalhadas de parâmetros e exemplos de implementação para rastreamento de sessão e relatórios de eventos.

Recurso empresarial: a atribuição de jogos para PC e console é um recurso empresarial. Para saber mais, leia as Perguntas frequentes sobre atribuição de jogos para PC e console ou entre em contato com seu gerente de sucesso do cliente.

Guia de integração: para obter instruções completas de implementação e práticas recomendadas, consulte o Guia de integração S2S para PC e console.

Ponto final de notificação de sessão

Relate lançamentos e sessões de jogos ao Singular para atribuição de instalação, rastreamento de reengajamento e análise de retenção de usuários.

Especificação do endpoint

Método	URL
`GET`	`https://s2s.singular.net/api/v1/launch`

Objetivo

Use o endpoint de notificação de sessão para relatar todos os lançamentos de jogos (primeiras e repetidas sessões) quase em tempo real. O primeiro lançamento de jogo recebido pelo Singular para instalação identificado pelo ID do dispositivo Singular aciona o processo de atribuição.

Fluxo de trabalho de atribuição:

Primeira sessão: aciona a atribuição da instalação comparando com cliques da campanha na web
Sessões subsequentes: rastreadas para análise da atividade do usuário, retenção e reengajamento
Relatórios em tempo real: envia notificações de sessão o mais próximo possível do lançamento real do jogo

Parâmetros da sessão

Parâmetros obrigatórios

Parâmetro	Descrição	Restrições	Exemplo
`a`	Chave SDK única para autenticação da API. Localização: Painel → Ferramentas do desenvolvedor → Integração do SDK → Chaves do SDK Importante: use a chave SDK, não a chave API de relatórios .	Obrigatório String	`your_org_name_sh868sdjv`
`p`	Plataforma em que o usuário joga o jogo. Valores suportados: `pc` `xbox` `playstation` `nintendo` `metaquest`	Obrigatório String Distinção entre maiúsculas e minúsculas	`pc`
`i`	Identificador exclusivo do seu jogo. Crítico: Deve corresponder exatamente ao ID do produto do Web SDK para que a atribuição funcione. Use o mesmo valor em todas as plataformas para o mesmo jogo. Obrigatório	Obrigatório Notação DNS reversa recomendada Maiúsculas e minúsculas	`com.singular.game`
`sdid`	ID de dispositivo singular que identifica a instalação exclusiva do jogo e a atividade do usuário. Geração: Criado pelo jogo/servidor na primeira inicialização, persiste durante toda a vida útil da instalação do jogo.	Obrigatório Recomenda-se o formato UUID versão 4	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	Sistema operacional ou sistema do jogo. Valores personalizados são suportados, mas os valores recomendados por plataforma são: PC: Windows, Linux, macOS, SteamOS Xbox: xbox_one, xbox_360, xbox_series_s, xbox_series_x PlayStation: playstation_3, playstation_4, playstation_5 Nintendo: nintendo_switch Meta Quest: metaquest, metaquest_2, metaquest_pro	Obrigatório Valores personalizados suportados	`windows`
`install_source`	Loja de jogos ou método de distribuição. Valores recomendados: `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` Valores personalizados suportados	Obrigatório Valores personalizados suportados	`steam`
`ip`	Endereço IP do dispositivo no momento do lançamento do jogo. Alternativa: Use `use_ip=true` para extrair o IP do cabeçalho da solicitação HTTP em vez de passar explicitamente.	Obrigatório Formato IPv4 ou IPv6 Não necessário se `use_ip=true`	`172.58.29.235`

Parâmetros opcionais

Parâmetro	Descrição	Restrições	Exemplo
`install_ref`	Informações de referência de instalação do Google codificadas em JSON URL. Fornece a atribuição mais precisa para jogos nativos para PC distribuídos através da loja Google Play Games. Requisitos: Requer a implementação do Play Games PCSDK para passar o Deve ser enviado apenas na primeira inicialização do jogo Consulte a documentação do Google Play para referências de instalação nativas para PC para obter detalhes sobre a implementação.	Opcional String Apenas na primeira inicialização	`%7B%22install_time_epoch_seconds%22%3A%221568939453%22` `%2C%22install_referrer%22%3A%22utm_source%3Dgoogle-play%26utm_medium%3Dorganic%22%7D`
`match_id`	Identificador para atribuição determinística que associa cliques na web às instalações do jogo . Requisitos: Deve ser enviado apenas na primeira inicialização do jogo Deve corresponder ao valor da implementação do Web SDK Se for PII, deve ser hashado usando SHA-256 Consulte Atribuição de ID correspondente para obter detalhes sobre a implementação.	Opcional String Apenas na primeira inicialização	`matchid_12345`
`ve`	Versão do sistema operacional.	Opcional String	`22H2`
`av`	Versão do aplicativo ou identificador da compilação do jogo.	Opcional String	`1.1.5.581823a`
`use_ip`	Extraia o endereço IP do cabeçalho da solicitação HTTP em vez de exigir o parâmetro explícito `ip` . Se definido como `true`, não forneça o parâmetro `ip` .	Opcional Booleano Padrão: false	`true`
`ua`	String do agente do usuário do dispositivo.	Opcional String	`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`
`global_properties`	Par de chave-valor salvo para o usuário e mantido em todas as solicitações subsequentes. Não enviar o valor definido anteriormente o desativa. Formato: objeto JSON codificado em URL	Opcional Até 5 propriedades 200 caracteres no máximo cada JSON codificado em URL	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	Consentimento do usuário para compartilhar informações para conformidade com a privacidade. Deve ser mantido e transmitido em todas as solicitações subsequentes, se definido. Valores: `"limit_data_sharing":false` - O usuário optou por participar (consentiu) `"limit_data_sharing":true` - O usuário optou por não participar (recusou) Consulte Privacidade do usuário para obter orientações de implementação.	Opcional JSON codificado em URL	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	Sinalizador de instalação indicando a primeira sessão após a instalação do jogo. Necessário para recursos de rastreamento de reinstalação.	Opcional Booleano	`true`
`utime`	Carimbo de data/hora do lançamento do jogo em tempo UNIX (segundos).	Opcional Inteiro (carimbo de data/hora UNIX)	`1483228800`
`umilisec`	Carimbo de data/hora do lançamento do jogo em tempo UNIX (milissegundos).	Opcional Inteiro (marca temporal UNIX ms)	`1483228800000`
`custom_user_id`	Identificador de usuário personalizado do seu sistema.	Opcional String	`123456789abcd`

Exemplos de solicitação

Implementações de exemplo

Solicitação de sessão básica

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235"

Primeiro lançamento com ID de correspondência

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235" \
  --data-urlencode "match_id=abc123def456" \
  --data-urlencode "install=true"

Solicitação de sessão básica

import requests

def report_session(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_session({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'ip_address': '172.58.29.235'
})

Primeiro lançamento com ID de correspondência

def report_first_launch(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address'],
        'match_id': config['match_id'],
        'install': 'true'
    }
    
    response = requests.get(url, params=params)
    return response.json()

Solicitação de sessão básica

async function reportSession(config) {
    const url = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportSession({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    ipAddress: '172.58.29.235'
});

Primeiro lançamento com ID de correspondência

async function reportFirstLaunch(config) {
    const url = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': config.ipAddress,
        'match_id': config.matchId,
        'install': 'true'
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

Ponto final de notificação de eventos

Relate eventos no jogo à Singular para análise, otimização de campanha e encaminhamento de parceiros.

Especificação do ponto final

Método	URL
`GET`	`https://s2s.singular.net/api/v1/evt`

Objetivo

Use o endpoint de notificação de eventos para relatar todos os eventos desejados no jogo em tempo quase real. Os dados do evento são usados para análise, relatórios, otimização de parceiros e medição do desempenho da campanha.

Práticas recomendadas para eventos:

Eventos padrão: use nomes de eventos padrão únicos para mapeamento automático de parceiros
Relatórios em tempo real: envie eventos o mais próximo possível da ocorrência real .
Eventos de receita: inclua parâmetros de receita para acompanhamento de compras e análise de ROI

Parâmetros de eventos

Parâmetros obrigatórios

Parâmetro	Descrição	Restrições	Exemplo
`a`	Chave SDK única para autenticação da API. Localização: Painel → Ferramentas do desenvolvedor → Integração do SDK → Chaves do SDK	Obrigatório String	`your_org_name_sh868sdjv`
`p`	Plataforma em que o usuário joga o jogo. Valores suportados: pc, xbox, playstation, nintendo, metaquest	Obrigatório String Distinção entre maiúsculas e minúsculas	`pc`
`i`	Identificador exclusivo do seu jogo. Deve corresponder ao valor usado nas notificações de sessão e no ID do produto do Web SDK.	Obrigatório Notação DNS reversa recomendada Maiúsculas e minúsculas	`com.singular.game`
`sdid`	ID de dispositivo singular que identifica a instalação exclusiva do jogo. Deve corresponder ao SDID usado nas notificações de sessão.	Obrigatório Formato UUID	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	Nome do evento que identifica uma ação ou marco no jogo. Recomendado: Use nomes de eventos padrão do Singular para integração automática de parceiros.	Obrigatório String 32 caracteres ASCII no máximo	`sng_achievement_unlocked`
`os`	Sistema operacional ou sistema do jogo. Deve corresponder ao valor usado nas notificações de sessão.	Obrigatório Valores personalizados suportados	`windows`
`install_source`	Loja de jogos ou método de distribuição. Deve corresponder ao valor usado nas notificações de sessão.	Obrigatório Valores personalizados suportados	`steam`
`ip`	Endereço IP do dispositivo no momento do evento.	Obrigatório Formato IPv4 ou IPv6 Não obrigatório se for um `use_ip=true`	`172.58.29.235`

Parâmetros opcionais

Parâmetro	Descrição	Restrições	Exemplo
`e`	Atributos de evento personalizados que fornecem informações detalhadas sobre o evento. Recomendado: Use nomes de atributos padrão singulares para compatibilidade com parceiros.	Opcional JSON codificado em URL 500 caracteres ASCII no máximo por atributo	`%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	Marca o evento como evento de receita. Pode ser omitido se o nome do evento for `__iap__` ou `amt` diferente de zero.	Obrigatório para eventos de receita Booleano	`true`
`amt`	Valor monetário para o evento de receita. Use com o parâmetro `cur`.	Obrigatório para eventos de receita Número decimal	`2.51`
`cur`	Código de moeda de três letras ISO-4217 para evento de receita. Use com o parâmetro `amt`. Referência: Códigos de moeda ISO-4217	Obrigatório para eventos de receita Código ISO-4217	`EUR`
`ve`	Versão do sistema operacional.	Opcional String	`22H2`
`av`	Versão do aplicativo ou identificador da compilação do jogo.	Opcional String	`1.1.5.581823a`
`use_ip`	Extrair o endereço IP do cabeçalho da solicitação HTTP.	Opcional Booleano Padrão: falso	`true`
`ua`	String do agente do usuário do dispositivo.	Opcional String	`Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
`global_properties`	Par de chave-valor salvo para o usuário. Deve persistir em todas as solicitações subsequentes, se definido.	Opcional Até 5 propriedades Máximo de 200 caracteres cada JSON codificado em URL	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	Consentimento do usuário para compartilhar informações. Deve persistir em todas as solicitações subsequentes, se definido.	Opcional JSON codificado em URL	`%7B%22limit_data_sharing%22%3Atrue%7D`
`utime`	Carimbo de data/hora do evento em tempo UNIX (segundos).	Opcional Inteiro (carimbo de data/hora UNIX)	`1483228800`
`umilisec`	Carimbo de data/hora do evento em tempo UNIX (milissegundos).	Opcional Inteiro (carimbo de data/hora UNIX em milissegundos)	`1483228800000`
`custom_user_id`	Identificador de usuário personalizado do seu sistema.	Opcional String	`123456789abcd`

Exemplos de solicitação

Implementações de amostra

Evento padrão

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=sng_level_achieved" \
  --data-urlencode 'e={"sng_attr_level":"5","sng_attr_score":"1250"}' \
  --data-urlencode "ip=172.58.29.235"

Evento de receita

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=__iap__" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=9.99" \
  --data-urlencode "cur=USD" \
  --data-urlencode "ip=172.58.29.235"

Evento padrão

import requests
import json

def report_event(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': config['event_name'],
        'ip': config['ip_address']
    }
    
    if 'attributes' in config:
        params['e'] = json.dumps(config['attributes'])
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_event({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'event_name': 'sng_level_achieved',
    'attributes': {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    'ip_address': '172.58.29.235'
})

Evento de receita

def report_revenue(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config['amount'],
        'cur': config['currency'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_revenue({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'amount': 9.99,
    'currency': 'USD',
    'ip_address': '172.58.29.235'
})

Evento padrão

async function reportEvent(config) {
    const url = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'n': config.eventName,
        'ip': config.ipAddress
    });
    
    if (config.attributes) {
        params.append('e', JSON.stringify(config.attributes));
    }
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportEvent({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    eventName: 'sng_level_achieved',
    attributes: {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    ipAddress: '172.58.29.235'
});

Evento de receita

async function reportRevenue(config) {
    const url = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config.amount,
        'cur': config.currency,
        'ip': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportRevenue({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    amount: 9.99,
    currency: 'USD',
    ipAddress: '172.58.29.235'
});

Tratamento de respostas

Ambos os pontos finais retornam respostas JSON consistentes que exigem a validação do campo status para determinar o sucesso ou o erro.

Formato de resposta

Importante: Todas as respostas retornam códigos de status HTTP 200. Sempre valide o campo status do corpo da resposta para determinar o sucesso (ok) ou a falha (error).

Para obter a documentação completa dos códigos de resposta e estratégias de tratamento de erros, consulte Códigos de resposta S2S e tratamento de erros.

Recursos adicionais

Guia de integração:Guia de integração S2S para PC e console
SDK da Web:Visão geral do SDK da Web e introdução
Perguntas frequentes sobre atribuição:Perguntas frequentes sobre atribuição de jogos para PC e console
Eventos padrão:Referência de eventos padrão do Singular

PC e console - Referência de ponto final da API

Referência de pontos finais da API para PC e console

Ponto final de notificação de sessão

Especificação do endpoint

Objetivo

Parâmetros da sessão

Parâmetros obrigatórios

Parâmetros opcionais

Exemplos de solicitação

Implementações de exemplo

Solicitação de sessão básica

Primeiro lançamento com ID de correspondência

Solicitação de sessão básica

Primeiro lançamento com ID de correspondência

Solicitação de sessão básica

Primeiro lançamento com ID de correspondência

Ponto final de notificação de eventos

Especificação do ponto final

Objetivo

Parâmetros de eventos

Parâmetros obrigatórios

Parâmetros opcionais

Exemplos de solicitação

Implementações de amostra

Evento padrão

Evento de receita

Evento padrão

Evento de receita

Evento padrão

Evento de receita

Tratamento de respostas

Formato de resposta

Recursos adicionais