Documento de referência

Referência do ponto final da API do PC e da Consola

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

Funcionalidade empresarial: A atribuição de jogos para PC e Consola é uma funcionalidade empresarial. Para saber mais, leia as Perguntas Frequentes sobre Atribuição de Jogos de PC e Consolaou contacte o seu Gestor de Sucesso do Cliente.

Guia de integração: Para obter instruções completas de implementação e melhores práticas, consulte o Guia de Integração S2S para PC e Consola.

Ponto de extremidade de notificação de sessão

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

Especificação do ponto final

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

Finalidade

Use o Session Notification Endpoint para relatar todos os lançamentos de jogos (primeiras sessões e sessões repetidas) quase em tempo real. A primeira inicialização de jogo recebida pelo Singular para instalação identificada pelo Singular Device ID aciona o processo de atribuição.

Fluxo de trabalho de atribuição:

Primeira sessão: Aciona a correspondência de atribuição de instalação com os cliques da campanha na web
Sessões subsequentes: Rastreadas para análise da atividade do utilizador, 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 de sessão

Parâmetros necessários

Parâmetro	Descrição do parâmetro	Restrições	Exemplo
`a`	Chave SDK singular para autenticação da API. Localização: Dashboard → Ferramentas do desenvolvedor → Integração SDK → Chaves SDK Importante: Use a chave SDK, não a chave da API de relatório	Necessário Cadeia de caracteres	`your_org_name_sh868sdjv`
`p`	Plataforma onde o utilizador joga o jogo. Valores suportados: `pc` `xbox` `playstation` `nintendo` `metaquest`	Obrigatório Cadeia de caracteres Sensível a maiúsculas e minúsculas	`pc`
`i`	Identificador de jogo único para o seu jogo. Crítico: Deve corresponder exatamente à ID do produto Web SDK para que a atribuição funcione. Utilize o mesmo valor em todas as plataformas para o mesmo jogo.	Obrigatório Recomenda-se a notação de DNS invertido Sensível a maiúsculas e minúsculas	`com.singular.game`
`sdid`	ID de dispositivo único que identifica a instalação única do jogo e a atividade do utilizador. Geração: Criado pelo jogo/servidor no primeiro lançamento, persiste durante toda a vida útil da instalação do jogo.	Necessário Formato UUID Versão 4 recomendado	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	Sistema operativo ou sistema de jogo. Valores personalizados suportados, mas valores recomendados por plataforma: 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	Necessá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	Necessário Valores personalizados suportados	`steam`
`ip`	Endereço IP do dispositivo no momento do lançamento do jogo. Alternativa: Utilize `use_ip=true`para extrair o IP do cabeçalho do pedido HTTP em vez de o passar explicitamente.	Obrigatório Formato IPv4 ou IPv6 Não exigido se `use_ip=true`	`172.58.29.235`

Parâmetros opcionais

Parâmetro	Descrição do parâmetro	Restrições	Exemplo
`match_id`	Identificador para atribuição determinística que faz corresponder cliques na Web a instalações de jogos. Requisitos: Deve ser enviado apenas no primeiro lançamento do jogo Deve corresponder ao valor da implementação do Web SDK Se for uma PII, tem de ser codificado com SHA-256 Consulte Atribuição de ID de correspondênciapara obter detalhes de implementação.	Opcional Cadeia de caracteres Apenas no primeiro lançamento	`matchid_12345`
`ve`	Versão do sistema operativo.	Opcional Cadeia de caracteres	`22H2`
`av`	Versão da aplicação ou identificador de compilação do jogo.	Opcional Cadeia de caracteres	`1.1.5.581823a`
`use_ip`	Extrai o endereço IP do cabeçalho do pedido HTTP em vez de exigir o parâmetro `ip` explícito. Se definido para `true`, não fornecer o parâmetro `ip`.	Opcional Booleano Predefinição: false	`true`
`ua`	Cadeia de caracteres do agente do utilizador do dispositivo.	Facultativo Cadeia de caracteres	`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`
`global_properties`	Pares chave-valor guardados para o utilizador e mantidos em todos os pedidos subsequentes. O facto de não enviar o valor previamente definido anula a sua definição. Formato: Objeto JSON codificado por URL	Opcional Até 5 propriedades 200 caracteres no máximo cada JSON codificado por URL	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	Consentimento do utilizador para partilhar informações para conformidade com a privacidade. Deve ser mantido e transmitido em cada pedido subsequente, se definido. Valores: `"limit_data_sharing":false` - O utilizador deu o seu consentimento (consentiu) `"limit_data_sharing":true` - O utilizador optou por não participar (recusou) Consulte Privacidade do utilizadorpara obter orientações de implementação.	Opcional JSON codificado por URL	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	Sinalizador de instalação que indica a primeira sessão após a instalação do jogo. Necessário para capacidades de controlo de reinstalação.	Opcional Booleano	`true`
`utime`	Marca temporal do lançamento do jogo em tempo UNIX (segundos).	Opcional Inteiro (carimbo de data/hora UNIX)	`1483228800`
`umilisec`	Registo de data e hora do lançamento do jogo em tempo UNIX (milissegundos).	Opcional Inteiro (carimbo de data/hora UNIX ms)	`1483228800000`
`custom_user_id`	Identificador de utilizador personalizado do seu sistema.	Opcional Cadeia de caracteres	`123456789abcd`

Exemplos de pedidos

Implementações de amostra

Pedido 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 partida

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 para a Singular para análise, otimização de campanhas e encaminhamento de parceiros.

Especificação do ponto final

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

Finalidade

Use o Endpoint de Notificação de Evento para relatar todos os eventos desejados no jogo quase em tempo real. Os dados do evento são utilizados para análises, 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 Singularpara 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: Incluir parâmetros de receita para rastreamento de compras e análise de ROI

Parâmetros de eventos

Parâmetros necessários

Parâmetro	Descrição	Restrições	Exemplo
`a`	Chave SDK singular para autenticação da API. Localização: Painel de controlo → Ferramentas de desenvolvimento → Integração SDK → Chaves SDK	Necessário Cadeia de caracteres	`your_org_name_sh868sdjv`
`p`	Plataforma onde o utilizador joga o jogo. Valores suportados: pc, xbox, playstation, nintendo, metaquest	Obrigatório Cadeia de caracteres Sensível a maiúsculas e minúsculas	`pc`
`i`	Identificador de jogo exclusivo para o seu jogo. Tem de corresponder ao valor utilizado nas notificações de sessão e na ID de produto do Web SDK.	Obrigatório Notação DNS inversa recomendada Sensível a maiúsculas e minúsculas	`com.singular.game`
`sdid`	ID de dispositivo singular que identifica a instalação única do jogo. Tem de corresponder ao SDID utilizado 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: Utilizar nomes de eventos padrão Singularpara integração automática de parceiros.	Obrigatório Cadeia de caracteres 32 caracteres ASCII no máximo	`sng_achievement_unlocked`
`os`	Sistema operativo ou sistema de jogo. Deve corresponder ao valor utilizado nas notificações de sessão.	Obrigatório Valores personalizados suportados	`windows`
`install_source`	Loja de jogos ou método de distribuição. Tem de corresponder ao valor utilizado nas notificações da 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 exigido se `use_ip=true`	`172.58.29.235`

Parâmetros opcionais

Parâmetro	Descrição do parâmetro	Restrições	Exemplo
`e`	Atributos de evento personalizados que fornecem informações detalhadas sobre o evento. Recomendado: Utilizar nomes de atributos padrão Singularpara compatibilidade com parceiros.	Opcional JSON codificado por URL Máximo de 500 caracteres ASCII 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 se for fornecido um `amt`diferente de zero.	Obrigatório para eventos com receitas Booleano	`true`
`amt`	Valor monetário do evento de receitas. Utilizar com o parâmetro `cur`.	Obrigatório para eventos de receitas Número decimal	`2.51`
`cur`	Código de moeda de três letras ISO-4217 para o evento de receita. Utilizar com o parâmetro `amt`. Referência: Códigos de moeda ISO-4217	Obrigatório para eventos de receitas Código ISO-4217	`EUR`
`ve`	Versão do sistema operativo.	Opcional Cadeia de caracteres	`22H2`
`av`	Versão da aplicação ou identificador de compilação do jogo.	Opcional Cadeia de caracteres	`1.1.5.581823a`
`use_ip`	Extrai o endereço IP do cabeçalho do pedido HTTP.	Opcional Booleano Predefinição: false	`true`
`ua`	Cadeia de caracteres do agente do utilizador do dispositivo.	Opcional Cadeia de caracteres	`Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
`global_properties`	Pares chave-valor guardados para o utilizador. Se definidos, devem persistir em todos os pedidos subsequentes.	Opcional Até 5 propriedades 200 caracteres no máximo cada JSON codificado por URL	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	Consentimento do utilizador para partilhar informações. Se definido, deve persistir em todos os pedidos subsequentes.	Opcional JSON codificado por URL	`%7B%22limit_data_sharing%22%3Atrue%7D`
`utime`	Registo de data e 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 do UNIX ms)	`1483228800000`
`custom_user_id`	Identificador de utilizador personalizado do seu sistema.	Opcional Cadeia de caracteres	`123456789abcd`

Exemplos de pedidos

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 standard

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 standard

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 de extremidade devolvem respostas JSON consistentes que requerem a validação do campo de estado para determinação de sucesso ou erro.

Formato da resposta

Importante: todas as respostas devolvem códigos de estado HTTP 200. Valide sempre o campo status do corpo da resposta para determinar o êxito (ok) ou a falha (error).

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

Recursos adicionais

Guia de Integração:Guia de Integração do S2S para PC e Consola
Web SDK:Visão geral e introdução ao Web SDK
FAQ de atribuição:FAQ de atribuição de jogos para PC e consola
Eventos padrão:Referência de eventos padrão singulares

PC &amp; Console - Referência do ponto final da API

Referência do ponto final da API do PC e da Consola

Ponto de extremidade de notificação de sessão

Especificação do ponto final

Finalidade

Parâmetros de sessão

Parâmetros necessários

Parâmetros opcionais

Exemplos de pedidos

Implementações de amostra

Pedido de sessão básica

Primeiro lançamento com ID de partida

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

Finalidade

Parâmetros de eventos

Parâmetros necessários

Parâmetros opcionais

Exemplos de pedidos

Implementações de amostra

Evento padrão

Evento de receita

Evento standard

Evento de receita

Evento standard

Evento de receita

Tratamento de respostas

Formato da resposta

Recursos adicionais

PC & Console - Referência do ponto final da API