Guía de integración S2S para PC y consola

Guía completa para implementar la integración de servidor a servidor para la atribución de juegos de PC y consola, lo que permite una medición y análisis precisos de las campañas en las plataformas de escritorio y de juegos.

Visión general

Integración de servidor a servidor

Singular proporciona una API REST que permite la generación de informes de servidor a servidor de datos de conversión de juegos de PC y consola para análisis de atribución, medición del rendimiento de la campaña y seguimiento del comportamiento del usuario.

Capacidades de integración:

• Seguimiento de sesiones de juego: Informe de las sesiones de usuario y la actividad a través de lanzamientos de juegos
• Atribución de instalaciones: Atribuya las nuevas instalaciones de juegos a las campañas de marketing.
• Análisis de eventos: Seguimiento de los eventos del juego y de las interacciones de los usuarios para el análisis del embudo.
• Medición de ingresos: Mide las compras dentro del juego y el rendimiento de la monetización
• Soporte multiplataforma: Seguimiento unificado en PC, Xbox, PlayStation, Nintendo y Meta Quest

Requisitos previos

Antes de implementar la integración de S2S en PC y consola, asegúrese de que Web SDK está correctamente configurado para un flujo de trabajo de atribución completo.

Arquitectura de integración

La atribución completa de PC y consola requiere una implementación conjunta del lado web y del lado del juego.

Flujo de atribución:

1. El usuario hace clic en el anuncio: El usuario hace clic en el anuncio de la campaña de marketing de su juego
2. Visita a la página de destino: El usuario llega a la página de destino con Singular Web SDK implementado
3. Captura de clics: Web SDK captura los datos de los clics, incluyendo la huella digital del dispositivo y los parámetros de la campaña
4. Descarga del juego: El usuario descarga e instala el juego desde la tienda o mediante descarga directa
5. Primer lanzamiento: El usuario inicia el juego por primera vez
6. Informe de sesión: El juego informa de la sesión a través de la API S2S con el identificador del dispositivo.
7. Matching de atribución: Singular hace coincidir la instalación del juego con el clic en la web basándose en la huella dactilar o el Match ID
8. Atribución de campaña: La instalación se atribuye a la campaña de origen para la medición del ROI

Recursos de documentación

La referencia completa de la API proporciona especificaciones de puntos finales, parámetros y ejemplos de implementación.

Conceptos de integración

Conceptos básicos y requisitos para implementar una integración completa de S2S para PC y consola con Singular.

Autenticación

Requisito de clave SDK

Todas las solicitudes a la API S2S de PC y consola de Singular requieren autenticación de clave SDK en el parámetro a.

Privacidad del usuario

Cumplimiento de la privacidad

Singular recomienda ofrecer a los usuarios finales la posibilidad de aceptar o rechazar el seguimiento para preservar la privacidad del usuario y cumplir con la normativa pertinente.

Opciones de implementación:

• Opción 1: No enviar datos de eventos del juego a Singular cuando el usuario opta por no participar.
• Opción 2: Enviar los datos de los eventos del juego pero incluir las opciones de consentimiento del usuario a través del parámetro data_sharing_options con el valor "Limitar el uso compartido de datos".

Plataformas compatibles

Definición de plataforma

La plataforma representa dónde juega el usuario y debe introducirse en el parámetro pen todas las solicitudes de API S2S.

Valores de plataforma admitidos:

• pc - Plataformas de ordenadores personales
• xbox - Consolas de juegos Microsoft Xbox
• playstation - Consolas de juegos PlayStation de Sony
• nintendo - Consolas Nintendo
• metaquest - Cascos Meta Quest VR

Sistemas operativos y tiendas

Además de la plataforma, especifique el sistema operativo/de juego mediante el parámetro osy el almacén de distribución mediante el parámetro install_source.

Identificador del juego

Identificador de aplicación

El identificador de juego asocia eventos de juego con un juego específico y debe pasarse en el parámetro i en cada solicitud.

Requisitos del identificador:

• Formato: Se admite cualquier valor, pero Singular recomienda la notación DNS inversa (por ejemplo, com.singular.game).
• Alineación Web SDK: Debe coincidir con el ID de producto del SDK web configurado en las páginas de destino para que funcione la atribución.
• Coherencia entre plataformas: Debe utilizarse el mismo identificador para el mismo juego en todas las plataformas compatibles.

Ejemplos de configuración:

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

Identificación de dispositivos

Seguimiento único de la instalación del juego

El identificador de instalación/dispositivo asocia eventos de juego a lo largo de múltiples sesiones de juego para la misma instalación de juego y debe pasarse en el parámetro sdiden cada solicitud.

Especificaciones del identificador:

• Formato: Formato UUID versión 4 recomendado
• Generación: Valor generado por el juego/servidor en el primer inicio del juego (instalación)
• Persistencia: Debe persistir durante toda la vida de la instalación del juego
• Unicidad: Cada instalación de juego requiere un identificador único

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

Atribución de Match ID

Match ID permite mejorar la precisión de la atribución para campañas web al pasar un identificador único del SDK web a la instalación del juego, proporcionando una alternativa de coincidencia determinista a la atribución basada en huellas dactilares.

Cómo funciona Match ID:

1. Web SDK genera Match ID: Singular Web SDKcrea un único Match ID cuando el usuario visita la página de destino.
2. Recuperación del Match ID: Utilice los métodos de Web SDK para recuperar el ID de partida de la página de destino.
3. Pasar al juego: Su implementación pasa el ID de partida de la página web al juego durante el proceso de descarga/instalación (por ejemplo, parámetro de consulta, enlace profundo, cookie)
4. Informe con el primer lanzamiento: El juego incluye el ID del partido en la notificación de la primera sesión a Singular a través del parámetro match_id
5. Partida determinista: Singular utiliza el ID de coincidencia para una coincidencia de atribución precisa.

Métodos de Match ID del Web SDK

Implementación nativa

Singular Web SDK proporciona métodos nativos para recuperar, establecer y borrar los valores de Match ID en las páginas de destino.

Métodos disponibles:

Ejemplos de implementación

// 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>

Pasar el ID de partido al juego

Estrategias de implementación

Tras recuperar el ID de partida del SDK web, implemente un mecanismo para pasar el valor de la página de destino a la instalación del juego.

Enfoques comunes:

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

Implementación de la API S2S

Informe del ID de la partida

Una vez que el juego recupera el ID de partido de la implementación web, se incluye en la notificación de la primera sesión a Singular para la comparación de atribuciones.

Solicitud de sesión con Match ID:

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

Mejores prácticas de ID de partido

Lista de comprobación de la implementación

Para obtener información completa sobre la metodología de atribución y la resolución de problemas, consulte las Preguntas frecuentes sobre la atribución de juegos para PC y consola.

Seguimiento de sesiones de juego

En la integración de PC y consola se requiere la notificación de las sesiones de juego a Singular, lo que permite la atribución de la instalación, el seguimiento del reenganche y el análisis de la retención de usuarios.

Punto final de notificación de sesión

Requisitos de implementación

Llame al punto final de notificación de sesión cada vez que se inicie el juego para notificar a Singular sobre la sesión de juego.

Procesamiento de la sesión

Flujo de trabajo de atribución

Las notificaciones de sesión permiten a Singular realizar múltiples funciones de atribución y análisis basadas en el contexto de la sesión.

Lógicade procesamiento:

• Primera sesión (instalación): Si se trata de la primera sesión de juego después de una instalación única, Singular reconoce la nueva instalación y activa el proceso de atribución de instalación.
• Sesión de reenganche: Si la sesión se califica como de nueva participación (próximamente), Singular activa el proceso de atribución de nueva participación (consulte las preguntas frecuentes sobre nueva participación).
• Sesión normal: En caso contrario, se marca como sesión de juego para el seguimiento de la actividad y retención del usuario

Mejores prácticas de implementación

Recogida asíncrona de datos

Al recopilar datos para informar de la sesión de juego, espere a que las funciones asíncronas devuelvan y gestionen diversas funciones antes de enviar la notificación de sesión.

Ejemplo de solicitud de sesión

Ejemplo de implementación

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

Seguimiento de eventos en el juego

Realice un seguimiento de los eventos del juego y las interacciones de los usuarios para analizar el rendimiento de las campañas de marketing, optimizar los embudos de usuarios y medir el compromiso a lo largo del recorrido del jugador.

Planificación de eventos

Definición de eventos

Antes de implementar la integración S2S, defina los eventos que su organización desea rastrear para el análisis de la campaña y la medición del comportamiento del usuario.

Guía de planificación de eventos:Definición de eventos en el juego

Punto final de notificación de eventos

Notificación de eventos

Llame al punto final de notificación de eventos cuando se produzca un evento en el juego para notificarlo a Singular para el análisis de atribución y la optimización de campañas.

El nombre del evento incluido en la llamada a la API determina cómo se identifica el evento en los informes, exportaciones y postbacks de Singular.

Mejores prácticas de denominación de eventos

Eventos estándar

Singular recomienda el uso de una convención estándar de nomenclatura de eventos y atributos para agilizar la integración de socios y la compatibilidad analítica.

Seguimiento de eventos de ingresos

Medición de ingresos

Realice un seguimiento de los ingresos procedentes de las compras dentro del juego para analizar el rendimiento de la campaña y el retorno de la inversión, con datos disponibles en informes, exportaciones de registros y postbacks.

Implementación de eventos de ingresos: Utilice el punto final de notificación de eventos con parámetros de ingresos adicionales para designar eventos de ingresos.

Parámetrosde ingresos requeridos:

• is_revenue_event=true - Marca el evento como evento de ingresos (opcional si el nombre del evento es __iap__ o el importe es superior a cero)
• amt=1.99 - Importe de ingresos
• cur=USD - Código de moneda ISO 4217

Ejemplos de solicitud de eventos

Ejemplos de implementación

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

Pasos siguientes

Complete su integración de PC & Consola S2S con recursos y asistencia adicionales.

Recursos adicionales

Documentación y asistencia

• Web SDK:Descripción general y primeros pasos de Web SDK
• Referencia de API:Referencia de puntos finales de S2S para PC y consola
• Guía de atribución:Preguntas frecuentes sobre la atribución de juegos para PC y consola
• Planificación de eventos:Definición de eventos en el juego
• Eventos Estándar:Referencia de Eventos Estándar Singulares
• Códigos de respuesta:Códigos de respuesta S2S y gestión de errores

Canales de asistencia

Obtener Ayuda

Póngase en contacto con el equipo de Singular para obtener asistencia en la implementación y soporte técnico.

• Ingeniero de soluciones: Consulte con Singular Solution Engineer para funciones avanzadas y planificación de la integración.
• Gestor de Éxito del Cliente: Póngase en contacto con CSM para la habilitación de funciones empresariales y la configuración de cuentas
• Equipo de soporte: Envíe tickets de soporte para problemas técnicos y asistencia en la resolución de problemas