Guia de integração S2S para PC e consola

Guia abrangente para a implementação da integração servidor a servidor para atribuição de jogos para PC e Consola, permitindo a medição e análise precisas de campanhas em plataformas de desktop e de jogos.

Visão geral

Integração de servidor para servidor

A Singular fornece uma API REST que permite o relatório de servidor para servidor dos dados de conversão de jogos para PC e Consola para análise de atribuição, medição do desempenho da campanha e acompanhamento do comportamento do utilizador.

Capacidades de integração:

• Rastreamento de sessão de jogo: Relate sessões de usuários e atividades em lançamentos de jogos
• Atribuição de instalação: Atribuir novas instalações de jogos a campanhas de marketing
• Análise de eventos: Acompanhe os eventos no jogo e as interações dos utilizadores para análise do funil
• Medição de receitas: Medir compras no jogo e desempenho de monetização
• Suporte multiplataforma: Rastreamento unificado em PC, Xbox, PlayStation, Nintendo e Meta Quest

Pré-requisitos

Antes de implementar a integração PC & Console S2S, certifique-se de que o Web SDK esteja configurado corretamente para um fluxo de trabalho de atribuição completo.

Arquitetura de integração

A atribuição completa de PC e Consola requer que a implementação do lado da Web e do lado do jogo trabalhem em conjunto.

Fluxo de atribuição:

1. O utilizador clica no anúncio: O utilizador clica no anúncio da campanha de marketing do seu jogo
2. Visita à página de destino: O utilizador chega à página de destino com o Singular Web SDK implementado
3. Captura de cliques: O Web SDK captura os dados do clique, incluindo a impressão digital do dispositivo e os parâmetros da campanha
4. Descarregamento do jogo: O utilizador descarrega e instala o jogo a partir da loja ou por descarregamento direto
5. Primeiro lançamento: O utilizador inicia o jogo pela primeira vez
6. Relatório de sessão: O jogo reporta a sessão através da API S2S com identificador de dispositivo
7. Attribution Matching: Singular faz a correspondência entre a instalação do jogo e o clique na Web com base na impressão digital ou na Match ID
8. Atribuição de campanha: Instalação atribuída à campanha de origem para medição do ROI

Recursos de documentação

A referência completa da API fornece especificações de ponto de extremidade, parâmetros e exemplos de implementação.

Conceitos de integração

Conceitos e requisitos essenciais para implementar a integração completa de S2S para PC e Console com Singular.

Autenticação

Requisito da chave SDK

Todas as solicitações à API S2S para PC e Console da Singular exigem autenticação da chave SDK no parâmetro a.

Privacidade do utilizador

Conformidade com a privacidade

A Singular recomenda oferecer aos utilizadores finais a possibilidade de optarem por entrar ou sair do rastreamento para preservar a privacidade do utilizador e cumprir os regulamentos relevantes.

Opções de implementação:

• Opção 1: Não enviar dados de eventos do jogo para a Singular quando o usuário optar por não participar
• Opção 2: Enviar dados de eventos do jogo, mas incluir opções de consentimento do utilizador através do parâmetro data_sharing_options com o valor "Limitar partilha de dados

Plataformas suportadas

Definição de plataforma

A plataforma representa onde o utilizador joga o jogo e deve ser passada no parâmetro pem todos os pedidos da API S2S.

Valores de plataforma suportados:

• pc - Plataformas de computadores pessoais
• xbox - Consolas de jogos Microsoft Xbox
• playstation - Consolas de jogos Sony PlayStation
• nintendo - Consolas de jogos Nintendo
• metaquest - Auriculares Meta Quest VR

Sistemas operativos e lojas

Para além da plataforma, especificar o sistema operativo/jogo através do parâmetro ose a loja de distribuição através do parâmetro install_source.

Identificador do jogo

Identificação do aplicativo

O identificador de jogo associa eventos de jogo a um jogo específico e deve ser passado no parâmetro i em cada solicitação.

Requisitos do identificador:

• Formato: Qualquer valor suportado, mas a Singular recomenda a notação DNS reversa (por exemplo, com.singular.game)
• Alinhamento do Web SDK: Deve corresponder ao ID do produto do Web SDK configurado nas páginas de destino para que a atribuição funcione
• Consistência entre plataformas: O mesmo identificador de jogo deve ser usado para o mesmo jogo em todas as plataformas suportadas

Exemplos de configuração:

const config = {
  apiKey: 'YOUR_SDK_KEY',
  productId: 'com.singular.game',  // Must match S2S identifier
  // ... other config
};

p=pc&i=com.singular.game

p=xbox&i=com.singular.game

p=playstation&i=com.singular.game

Identificação do dispositivo

Rastreio único da instalação do jogo

O identificador de instalação/dispositivo associa eventos de jogo em várias sessões de jogo para a mesma instalação de jogo e deve ser passado no parâmetro sdidem cada pedido.

Especificações do identificador:

• Formato: Formato UUID versão 4 recomendado
• Geração: Valor gerado pelo jogo/servidor no primeiro lançamento do jogo (instalação)
• Persistência: Deve persistir durante toda a vida útil da instalação do jogo
• Singularidade: Cada instalação de jogo requer um identificador único

Exemplo: sdid=40009df0-d618-4d81-9da1-cbb3337b8dec

Atribuição de ID de correspondência

O Match ID permite uma melhor precisão de atribuição para campanhas na Web, passando um identificador exclusivo do Web SDK para a instalação do jogo, fornecendo uma alternativa de correspondência determinística à atribuição baseada em impressões digitais.

Como funciona o Match ID:

1. O Web SDK gera o Match ID:O Singular Web SDKcria um Match ID único quando o utilizador visita a página de destino
2. Recuperar o Match ID: Utilizar os métodos do Web SDK para recuperar o Match ID da landing page
3. Passar para o jogo: Sua implementação passa o Match ID da página da Web para o jogo durante o processo de download/instalação (por exemplo, parâmetro de consulta, link profundo, cookie)
4. Relatório com o primeiro lançamento: O jogo inclui a ID da partida na notificação da primeira sessão para o Singular através do parâmetro match_id
5. Correspondência determinística: A Singular usa a ID de correspondência para uma correspondência de atribuição precisa

Métodos de ID de correspondência do Web SDK

Implementação nativa

O Singular Web SDK fornece métodos nativos para recuperar, definir e limpar valores de Match ID em landing pages.

Métodos disponíveis:

Exemplos de implementação

// Get the Singular-generated Match ID
const matchId = window.singularSdk.getMatchID();
console.log('Match ID:', matchId);

// Store Match ID for passing to game
localStorage.setItem('singular_match_id', matchId);

// Set your own Match ID value
const customMatchId = 'your-custom-match-id-123';
window.singularSdk.setMatchID(customMatchId);

console.log('Custom Match ID set:', customMatchId);

// Clear custom Match ID and revert to default
window.singularSdk.clearMatchID();

// Get the new default Match ID
const defaultMatchId = window.singularSdk.getMatchID();
console.log('Default Match ID restored:', defaultMatchId);

// Initialize Web SDK
const config = new SingularConfig(sdkKey, sdkSecret, productId)
  .withInitFinishedCallback(() = {
    console.log('Singular SDK initialized');
  });

singularSdk.init(config);

// Handle download button click
document.getElementById('download-button').addEventListener('click', function() {
  // Get Match ID before redirecting to download
  const matchId = window.singularSdk.getMatchID();
  
  // Pass Match ID to download page via query parameter
  const downloadUrl = `https://example.com/download?match_id=${matchId}`;
  
  // Redirect to download page
  window.location.href = downloadUrl;
});

<script>
  // Match ID Management Functions for GTM

  // Get Match ID from Singular Web SDK
  function getMatchID() {
    if (window.singularSdk && window.singularSdk.getMatchID) {
      return window.singularSdk.getMatchID();
    }
    console.warn('Singular SDK not initialized');
    return null;
  }

  // Set custom Match ID
  function setMatchID(data) {
    if (!data.matchId) {
      console.warn('No matchId provided');
      return;
    }
    
    if (window.singularSdk && window.singularSdk.setMatchID) {
      window.singularSdk.setMatchID(data.matchId);
      console.log('Match ID set:', data.matchId);
    } else {
      console.warn('Singular SDK not initialized');
    }
  }

  // Clear Match ID
  function clearMatchID() {
    if (window.singularSdk && window.singularSdk.clearMatchID) {
      window.singularSdk.clearMatchID();
      console.log('Match ID cleared');
    } else {
      console.warn('Singular SDK not initialized');
    }
  }

  // Make functions available globally
  window.singularMatchID = {
    get: getMatchID,
    set: setMatchID,
    clear: clearMatchID
  };
</script>

// Get Match ID
const matchId = window.singularMatchID.get();
console.log('Match ID:', matchId);

// Set custom Match ID
window.singularMatchID.set({ matchId: 'custom-id-123' });

// Clear Match ID
window.singularMatchID.clear();

<script>
  // Trigger on button click
  document.addEventListener('DOMContentLoaded', function() {
    const downloadButton = document.getElementById('download-button');
    
    if (downloadButton) {
      downloadButton.addEventListener('click', function() {
        // Get Match ID via GTM function
        const matchId = window.singularMatchID.get();
        
        if (matchId) {
          // Push to dataLayer for GTM
          window.dataLayer = window.dataLayer || [];
          window.dataLayer.push({
            'event': 'download_click',
            'singular_match_id': matchId
          });
          
          // Redirect with Match ID
          const downloadUrl = `https://example.com/download?match_id=${matchId}`;
          window.location.href = downloadUrl;
        }
      });
    }
  });
</script>

Passagem do ID da partida para o jogo

Estratégias de implementação

Depois de recuperar o Match ID do Web SDK, implemente um mecanismo para passar o valor da página de destino para a instalação do jogo.

Abordagens comuns:

https://example.com/download?match_id=abc123

document.cookie = `match_id=${matchId}; path=/; max-age=86400`;

localStorage.setItem('singular_match_id', matchId);

mygame://install?match_id=abc123

Implementação da API S2S

Comunicar o ID do jogo

Assim que o jogo recuperar o Match ID da implementação web, incluir na notificação da primeira sessão para a Singular para correspondência de atribuição.

Solicitação de sessão com ID de correspondência:

import requests

def report_first_session_with_match_id(sdk_key, game_id, device_id, platform, match_id):
    """
    Report first game session with Match ID for attribution
    """
    session_url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'os': 'windows',
        'install_source': 'steam',
        'ip': get_user_ip(),
        'match_id': match_id  # Include Match ID for attribution
    }
    
    response = requests.get(session_url, params=params)
    return response.json()

# Example: First launch with Match ID
report_first_session_with_match_id(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    match_id='abc123def456'  # Retrieved from landing page
)

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --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"

async function reportFirstSessionWithMatchId(config) {
    const sessionUrl = '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': await getUserIP(),
        'match_id': config.matchId  // Include Match ID
    });
    
    const response = await fetch(`${sessionUrl}?${params.toString()}`);
    return await response.json();
}

// Example: First launch with Match ID
reportFirstSessionWithMatchId({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    matchId: 'abc123def456'  # Retrieved from landing page
});

Melhores práticas de Match ID

Lista de verificação de implementação

Para obter detalhes completos da metodologia de atribuição e solução de problemas, consulte Perguntas frequentes sobre atribuição de jogos para PC e console.

Rastreamento de sessão de jogo

O relatório de sessões de jogos para a Singular é necessário na integração de PC e Console, permitindo a atribuição de instalação, rastreamento de reengajamento e análise de retenção de usuários.

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

Requisito de implementação

Chamar o Session Notification Endpoint sempre que o jogo for iniciado para notificar a Singular sobre a sessão do jogo.

Processamento de sessão

Fluxo de trabalho de atribuição

As notificações de sessão permitem que a Singular execute várias funções de atribuição e análise com base no contexto da sessão.

Lógica de processamento:

• Primeira sessão (instalação): Se for a primeira sessão de jogo após uma instalação única, o Singular reconhece a nova instalação e aciona o processo de atribuição de instalação
• Sessão de reengajamento: Se a sessão for qualificada como reengajamento (em breve), o Singular aciona o processo de atribuição de reengajamento (consulte a FAQ sobre reengajamento)
• Sessão regular: Caso contrário, é marcada como sessão de jogo para rastreamento da atividade e retenção do usuário

Melhores práticas de implementação

Recolha de dados assíncrona

Ao coletar dados para relatar a sessão do jogo, aguarde o retorno das funções assíncronas e manipule várias funcionalidades antes de enviar a notificação da sessão.

Exemplo de solicitação de sessão

Exemplo de implementação

import requests

def report_game_session(sdk_key, game_id, device_id, platform, os_version, store):
    """
    Report game session to Singular
    """
    session_url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'os': os_version,
        'install_source': store,
        'ip': get_user_ip()
    }
    
    try:
        response = requests.get(session_url, params=params, timeout=10)
        
        if response.status_code == 200:
            data = response.json()
            if data.get('status') == 'ok':
                print("Session reported successfully")
                return True
            else:
                print(f"Session error: {data.get('reason')}")
                return False
        else:
            print(f"HTTP error: {response.status_code}")
            return False
            
    except Exception as e:
        print(f"Exception reporting session: {e}")
        return False

# Example usage
report_game_session(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    os_version='windows',
    store='steam'
)

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235"

async function reportGameSession(config) {
    const sessionUrl = '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': await getUserIP()
    });
    
    try {
        const response = await fetch(`${sessionUrl}?${params.toString()}`);
        const data = await response.json();
        
        if (data.status === 'ok') {
            console.log('Session reported successfully');
            return true;
        } else {
            console.error('Session error:', data.reason);
            return false;
        }
    } catch (error) {
        console.error('Exception reporting session:', error);
        return false;
    }
}

// Example usage
reportGameSession({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam'
});

Rastreamento de eventos no jogo

Acompanhe os eventos no jogo e as interações dos utilizadores para analisar o desempenho das campanhas de marketing, otimizar os funis de utilizador e medir o envolvimento no percurso do jogador.

Planeamento de eventos

Definição do evento

Antes de implementar a integração S2S, defina os eventos que a sua organização pretende acompanhar para análise de campanhas e medição do comportamento do utilizador.

Guia de planeamento de eventos:definição de eventos no jogo

Ponto final de notificação de eventos

Relatório de eventos

Chame o Event Notification Endpoint quando ocorrer um evento no jogo para notificar a Singular para análise de atribuição e otimização de campanha.

O nome do evento incluído na chamada da API determina como o evento é identificado nos relatórios, exportações e postbacks da Singular.

Melhores práticas de nomenclatura de eventos

Eventos padrão

A Singular recomenda o uso de eventos padrão e convenção de nomenclatura de atributos para integração simplificada com parceiros e compatibilidade analítica.

Rastreamento de eventos de receita

Medição de receitas

Acompanhe as receitas das compras no jogo para analisar o desempenho da campanha e o ROI, com dados disponíveis em relatórios, exportações de registos e postbacks.

Implementação de eventos de receita: Use o Ponto de extremidade de notificação de evento com parâmetros de receita adicionais para designar eventos de receita.

Parâmetros de receita necessários:

• is_revenue_event=true - Marca o evento como evento de receita (opcional se o nome do evento for __iap__ ou o valor for maior que zero)
• amt=1.99 - Valor da receita
• cur=USD - Código de moeda ISO 4217

Exemplos de solicitação de evento

Implementações de amostra

import requests

def report_game_event(sdk_key, game_id, device_id, platform, event_name, event_attributes=None):
    """
    Report in-game event to Singular
    """
    event_url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'n': event_name,
        'ip': get_user_ip()
    }
    
    if event_attributes:
        import json
        params['e'] = json.dumps(event_attributes)
    
    response = requests.get(event_url, params=params)
    return response.json()

# Example: Level complete event
report_game_event(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    event_name='sng_level_achieved',
    event_attributes={
        'level': '5',
        'score': '1250'
    }
)

def report_revenue_event(sdk_key, game_id, device_id, platform, amount, currency):
    """
    Report revenue event to Singular
    """
    event_url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': amount,
        'cur': currency,
        'ip': get_user_ip()
    }
    
    response = requests.get(event_url, params=params)
    return response.json()

# Example: $9.99 purchase
report_revenue_event(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    amount=9.99,
    currency='USD'
)

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --data-urlencode "n=sng_level_achieved" \
  --data-urlencode 'e={"level":"5","score":"1250"}' \
  --data-urlencode "ip=172.58.29.235"

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --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"

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

// Example: Level complete
reportGameEvent({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    eventName: 'sng_level_achieved',
    attributes: {
        level: '5',
        score: '1250'
    }
});

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

// Example: $9.99 purchase
reportRevenueEvent({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    amount: 9.99,
    currency: 'USD'
});

Próximos passos

Complete a sua integração PC & Console S2S com recursos e suporte adicionais.

Recursos adicionais

Documentação e suporte

• Web SDK:Visão geral e introdução ao Web SDK
• Referência da API:Referência do ponto final S2S para PC e Consola
• Guia de atribuição:Perguntas frequentes sobre atribuição de jogos para PC e consola
• Planeamento de eventos:Definição de eventos no jogo
• Eventos padrão:Referência de eventos padrão singulares
• Códigos de resposta:Códigos de resposta S2S e tratamento de erros

Canais de suporte

Obter ajuda

Contacte a equipa da Singular para obter assistência na implementação e suporte técnico.

• Engenheiro de Soluções: Consultar o Engenheiro de Soluções da Singular para recursos avançados e planejamento de integração
• Gerente de Sucesso do Cliente: Contactar o CSM para ativação de funcionalidades empresariais e configuração de contas
• Equipe de suporte: Enviar tickets de suporte para questões técnicas e assistência na resolução de problemas