Referência de Endpoints da API para PC e Console

Referência completa da API para os endpoints server-to-server de PC e Console, fornecendo especificações detalhadas de parâmetros e exemplos de implementação para o rastreamento de sessões e o reporte de eventos.

Parâmetros S2S compartilhados: Os endpoints, a autenticação e os parâmetros de requisição comuns são definidos uma única vez no hub de Fundamentos de S2S . Esta referência abrange apenas as especificidades de PC e Console.

Recurso Enterprise: A atribuição de jogos de PC e Console é um recurso enterprise. Para saber mais, leia o FAQ de Atribuição de Jogos de PC e Console ou entre em contato com o seu Customer Success Manager.

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

Endpoint de Notificação de Sessão

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

Especificação do Endpoint

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

Finalidade

Use o Endpoint de Notificação de Sessão para reportar todos os lançamentos de jogos (primeiras sessões e sessões subsequentes) em tempo quase real. O primeiro lançamento de jogo recebido pelo Singular para uma instalação identificada pelo Singular Device ID aciona o processo de atribuição.

Fluxo de Atribuição:

Primeira Sessão: Aciona a correspondência de atribuição de instalação contra cliques de campanhas web
Sessões Subsequentes: Rastreadas para análise de atividade do usuário, retenção e re-engajamento
Reporte em Tempo Real: Envie as notificações de sessão o mais próximo possível do lançamento real do jogo

Parâmetros de Sessão

Parâmetros Obrigatórios

A autenticação usa o parâmetro compartilhado a (SDK Key). Consulte Autenticação no hub de Fundamentos de S2S.

Parâmetro	Detalhes
`p`	`string` Obrigatório. Diferencia maiúsculas de minúsculas. Plataforma na qual o usuário joga. Valores Suportados: `pc` `xbox` `playstation` `nintendo` `metaquest` Exemplo: `pc`
`i`	`string` Obrigatório. Diferencia maiúsculas de minúsculas. Recomenda-se a notação DNS reversa. Identificador de jogo exclusivo para o seu jogo. Crítico: Deve corresponder exatamente ao Product ID do Web SDK para que a atribuição funcione. Use o mesmo valor em todas as plataformas para o mesmo jogo. Exemplo: `com.singular.game`
`sdid`	`UUID` Obrigatório. Recomenda-se o formato UUID Versão 4. Singular Device ID que identifica uma instalação de jogo e a atividade do usuário de forma exclusiva. Geração: Criado pelo jogo/servidor no primeiro lançamento, persiste durante todo o ciclo de vida da instalação do jogo. Exemplo: `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	`string` Obrigatório. Valores personalizados são suportados. Sistema Operacional ou Sistema de Jogo. 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 Exemplo: `windows`
`install_source`	`string` Obrigatório. Valores personalizados são suportados. Loja de jogos ou método de distribuição. Valores Recomendados: `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` Valores personalizados são suportados. Exemplo: `steam`
`ip`	`string` Obrigatório. Formato IPv4 ou IPv6. Não é obrigatório se `use_ip=true` . 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 requisição HTTP em vez de passá-lo explicitamente. Consulte Rede e localização no hub de Fundamentos de S2S. Exemplo: `172.58.29.235`

Parâmetros Opcionais

Propriedades genéricas de dispositivo ( ve , ua ), parâmetros de rede ( use_ip ), privacidade de dados ( data_sharing_options ) e cross-device ( custom_user_id ) são compartilhados entre todos os endpoints S2S. Consulte Parâmetros de dispositivo , Rede e localização , Privacidade de dados e Cross-device no hub de Fundamentos de S2S. Os parâmetros abaixo são específicos de PC e Console.

Parâmetro	Detalhes
`install_ref`	`string` Opcional. Apenas no primeiro lançamento. Informações do Google Install Referrer em JSON codificado em URL. Fornece a atribuição mais precisa para jogos nativos de PC distribuídos pela loja Google Play Games. Requisitos: Requer a implementação do Play Games PC SDK para passar o valor Deve ser enviado apenas no primeiro lançamento do jogo Consulte a documentação do Install Referrer do Google Play para PC Nativo para detalhes de implementação. Exemplo: `%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`	`string` Opcional. Apenas no primeiro lançamento. Identificador para correspondência de atribuição determinística entre cliques web e 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 PII, deve ser hasheado usando SHA-256 Consulte Atribuição por Match ID para detalhes de implementação. Exemplo: `matchid_12345`
`av`	`string` Opcional. Versão da aplicação ou identificador de build do jogo. Exemplo: `1.1.5.581823a`
`global_properties`	`JSON` Opcional. JSON codificado em URL. Até 5 propriedades, no máximo 200 caracteres cada. Pares de chave-valor salvos para o usuário e persistidos em todas as requisições subsequentes. Não enviar um valor previamente definido o remove. Exemplo: `%7B%22key1%22%3A%22value1%22%7D`
`install`	`boolean` Opcional. Flag de instalação que indica a primeira sessão após a instalação do jogo. Obrigatório para os recursos de rastreamento de reinstalação. Exemplo: `true`
`utime`	`integer` Opcional. Timestamp UNIX (segundos). Timestamp do lançamento do jogo em tempo UNIX. Exemplo: `1483228800`
`umilisec`	`integer` Opcional. Timestamp UNIX (milissegundos). Timestamp do lançamento do jogo em tempo UNIX. Exemplo: `1483228800000`

Exemplos de Requisição

Implementações de Exemplo

Requisição Básica de Sessão

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 Match ID

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"

Requisição Básica de Sessão

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 Match ID

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()

Requisição Básica de Sessão

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 Match ID

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();
}

Endpoint de Notificação de Evento

Suporte a Conversion API de parceiros: Para encaminhar esses eventos aos parceiros de redes de anúncios por meio das integrações de Conversion API da Singular, inclua os atributos de evento opcionais padrão (dados próprios com hash, como eventId e ehash). Consulte Atributos de evento padrão para integrações de Conversion API.

Reporte eventos in-game ao Singular para análise, otimização de campanhas e encaminhamento a parceiros.

Especificação do Endpoint

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

Finalidade

Use o Endpoint de Notificação de Evento para reportar todos os eventos in-game desejados em tempo quase real. Os dados de eventos são usados para análise, reporte, otimização de parceiros e medição de desempenho de campanhas.

Melhores Práticas de Eventos:

Eventos Padrão: Use os nomes de eventos padrão do Singular para o mapeamento automático de parceiros
Reporte em Tempo Real: Envie os eventos o mais próximo possível da ocorrência real
Eventos de Receita: Inclua parâmetros de receita para o rastreamento de compras e análise de ROI

Parâmetros de Evento

Parâmetros Obrigatórios

A autenticação usa o parâmetro compartilhado a (SDK Key). Consulte Autenticação no hub de Fundamentos de S2S.

Parâmetro	Detalhes
`p`	`string` Obrigatório. Diferencia maiúsculas de minúsculas. Plataforma na qual o usuário joga. Valores Suportados: pc, xbox, playstation, nintendo, metaquest Exemplo: `pc`
`i`	`string` Obrigatório. Diferencia maiúsculas de minúsculas. Recomenda-se a notação DNS reversa. Identificador de jogo exclusivo para o seu jogo. Deve corresponder ao valor usado nas notificações de sessão e ao Product ID do Web SDK. Exemplo: `com.singular.game`
`sdid`	`UUID` Obrigatório. Singular Device ID que identifica uma instalação de jogo de forma exclusiva. Deve corresponder ao SDID usado nas notificações de sessão. Exemplo: `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	`string` Obrigatório. No máximo 32 caracteres ASCII. Nome do evento que identifica uma ação ou marco in-game. Recomendado: Use os nomes de eventos padrão do Singular para a integração automática com parceiros. Exemplo: `sng_achievement_unlocked`
`os`	`string` Obrigatório. Valores personalizados são suportados. Sistema Operacional ou Sistema de Jogo. Deve corresponder ao valor usado nas notificações de sessão. Exemplo: `windows`
`install_source`	`string` Obrigatório. Valores personalizados são suportados. Loja de jogos ou método de distribuição. Deve corresponder ao valor usado nas notificações de sessão. Exemplo: `steam`
`ip`	`string` Obrigatório. Formato IPv4 ou IPv6. Não é obrigatório se `use_ip=true` . Endereço IP do dispositivo no momento do evento. Exemplo: `172.58.29.235`

Parâmetros Opcionais

Parâmetro	Detalhes
`e`	`JSON` Opcional. JSON codificado em URL, no máximo 500 caracteres ASCII por atributo. Atributos de evento personalizados que fornecem informações ricas sobre o evento. Recomendado: Use os nomes de atributos padrão do Singular para compatibilidade com parceiros. Exemplo: `%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	`boolean` Obrigatório para eventos de receita. Marca o evento como um evento de receita. Pode ser omitido se o nome do evento for `__iap__` ou se um valor `amt` diferente de zero for fornecido. Exemplo: `true`
`amt`	`number` Obrigatório para eventos de receita. Valor monetário do evento de receita. Use com o parâmetro `cur` . Exemplo: `2.51`
`cur`	`string` Obrigatório para eventos de receita. Código de moeda de três letras ISO-4217 para o evento de receita. Use com o parâmetro `amt` . Referência: Códigos de Moeda ISO-4217 Exemplo: `EUR`
`av`	`string` Opcional. Versão da aplicação ou identificador de build do jogo. Exemplo: `1.1.5.581823a`
`global_properties`	`JSON` Opcional. JSON codificado em URL. Até 5 propriedades, no máximo 200 caracteres cada. Pares de chave-valor salvos para o usuário. Devem persistir em todas as requisições subsequentes, se definidos. Exemplo: `%7B%22key1%22%3A%22value1%22%7D`
`utime`	`integer` Opcional. Timestamp UNIX (segundos). Timestamp do evento em tempo UNIX. Exemplo: `1483228800`
`umilisec`	`integer` Opcional. Timestamp UNIX (milissegundos). Timestamp do evento em tempo UNIX. Exemplo: `1483228800000`

Exemplos de Requisição

Implementações de Exemplo

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 endpoints retornam respostas JSON consistentes que exigem a validação do campo de status para determinar sucesso ou erro.

Formato da Resposta

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

Para a documentação completa dos códigos de resposta e as 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
Web SDK: Visão Geral e Primeiros Passos do Web SDK
FAQ de Atribuição: FAQ de Atribuição de Jogos de PC e Console
Eventos Padrão: Referência de Eventos Padrão do Singular