Descripción general

Web Server-to-Server (Web S2S) envía eventos web de conversión e interacción a Singular directamente desde tu servidor, usando el mismo endpoint EVENT que la integración móvil V1. La ruta web se diferencia por el parámetro de plataforma p=Web .

Web S2S es una arquitectura asistida por el navegador . Varios valores relevantes para la atribución solo están disponibles en el navegador — location.href , document.referrer y el userAgent del navegador no pueden reconstruirse en el backend. Un fragmento ligero del lado del cliente debe recopilar estos valores y llamar al endpoint directamente o reenviarlos a tu backend, que luego realiza la llamada S2S.

No existe ningún endpoint web SESSION . El primer evento de conversión __PAGE_VISIT__ reemplaza la llamada móvil launch y establece la línea base de atribución para la visita.

Endpoint

Web S2S usa el mismo host y ruta que el endpoint móvil EVENT de V1. Establece p=Web para enrutar la solicitud a través de la ruta de atribución web.

GET https://s2s.singular.net/api/v1/evt

Generación y persistencia del SDID

El ID de dispositivo de Singular ( sdid ) vincula todos los eventos de un navegador a un único dispositivo web. En la primera carga de la página, si no existe ningún global_singular_id en localStorage , genera un UUID v4 y guárdalo. Reutiliza el mismo valor como sdid en cada evento de ese navegador hasta que se borre localStorage .

function getOrCreateSDID() {
  var KEY = 'global_singular_id';
  var sdid = localStorage.getItem(KEY);
  if (!sdid) {
    sdid = crypto.randomUUID(); // UUID v4
    localStorage.setItem(KEY, sdid);
  }
  return sdid;
}

El patrón __PAGE_VISIT__

El primer evento de cualquier visita nueva DEBE ser __PAGE_VISIT__ con conversion_event=true . Esto establece la línea base de atribución que los eventos posteriores heredan.

Los eventos que no son de conversión (por ejemplo sng_registration_complete o sng_purchase ) usan conversion_event=false y omiten attribution_data . Heredan la atribución del __PAGE_VISIT__ más reciente.

Reglas de custom_user_id

• Incluye custom_user_id después del registro o inicio de sesión, y en todos los eventos posteriores.
• Persístelo en localStorage o en una cookie propia (first-party).
• Elimínalo al cerrar sesión.
• Nunca incluyas PII. Usa un ID interno o hasheado.

Parámetros

El Web SDK envía aproximadamente 40 parámetros en __PAGE_VISIT__ , pero la mayoría son telemetría interna del SDK que los desarrolladores de S2S no deberían replicar. Las tablas siguientes cubren solo los conjuntos requeridos y recomendados.

Parámetros requeridos

Parámetros recomendados

Para la identidad del dispositivo y otros parámetros compartidos que no se enumeran arriba, consulta Parámetros comunes en Fundamentos de S2S en lugar de volver a documentarlos aquí.

attribution_data

El parámetro attribution_data transporta los datos de click-through de las ad networks como JSON codificado en URL. Envíalo solo en eventos de conversión __PAGE_VISIT__ .

{
  "partner_name": "Snapchat",
  "is_attributed": "true",
  "touch_timestamp": "",
  "partner_campaign_id": "",
  "partner_campaign_name": "Snap_campaign_1234",
  "partner_creative_id": "",
  "partner_creative_name": "",
  "partner_keyword": "",
  "partner_site": "",
  "partner_site_id": "",
  "partner_site_name": "",
  "partner_sub_site": "",
  "partner_sub_site_name": "",
  "partner_subcampaign_id": "",
  "partner_subcampaign_name": "",
  "_p": ""
}

Campos requeridos

Campos opcionales

IDs de clic web en el parámetro e

Pasa los click IDs de la network en el payload e del evento usando la clave JSON que cada partner espera:

Atribución web-a-app

Para llevar el contexto de la campaña web a un clic móvil, construye un Singular Link desde tu landing page y agrega la query string de landing capturada. Esto reenvía los parámetros de marketing al clic móvil para que la instalación de la app pueda atribuirse.

Al aterrizar, captura window.location.search (más el fragmento) cuando contenga parámetros de marketing y persístelo. Al renderizar el enlace a la tienda de apps o al smart banner, construye:

function buildWebToAppLink(baseLink, webUrl, deeplink, passthrough, deferredDeeplink) {
  var url = new URL(baseLink); // preserves existing base-link params
  if (webUrl) {
    var q = new URL(webUrl);
    var captured = q.search.slice(1) + (q.hash || ''); // landing query string (+fragment)
    url.searchParams.set('_web_params', captured); // URL-encoded on serialization
  }
  if (deeplink)         url.searchParams.set('_dl', deeplink);
  if (passthrough)      url.searchParams.set('_p', passthrough);
  if (deferredDeeplink) url.searchParams.set('_ddl', deferredDeeplink);
  return url.toString();
}

Atribución por portapapeles (Deferred Deep Link)

La atribución por portapapeles proporciona una coincidencia determinística para un deferred deep link. El fragmento web escribe un token único en el portapapeles; la app recién instalada lo lee de vuelta y hace la coincidencia por igualdad de token.

function openAppWithClipboardDdl(baseLink, deeplink, passthrough, deferredDeeplink) {
  // 1. Build the web-to-app link (see Web-to-App Attribution).
  var link = buildWebToAppLink(baseLink, capturedWebUrl, deeplink, passthrough, deferredDeeplink);

  // 2. Generate a UUID v4 and form the token.
  var uuid = crypto.randomUUID();
  var tokenUrl = location.protocol + '//' + location.hostname + '/__singular_ddl__/' + uuid;

  // 3. Write ONLY the token to the clipboard (execCommand fallback).
  copyToClipboard(tokenUrl);

  // 4. Append the token to the click as ecid.
  var url = new URL(link);
  url.searchParams.set('ecid', tokenUrl);

  // 5. Open the app / store.
  window.open(url.toString());
}

function copyToClipboard(text) {
  if (navigator.clipboard && navigator.clipboard.writeText) {
    navigator.clipboard.writeText(text);
    return;
  }
  var ta = document.createElement('textarea');
  ta.value = text;
  document.body.appendChild(ta);
  ta.select();
  document.execCommand('copy');
  document.body.removeChild(ta);
}

Ejemplos de secuencia de eventos

Primera visita y registro

1. El usuario llega desde Google Ads. Envía la visita de página inicial:

   • n=__PAGE_VISIT__
   • conversion_event=true
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f
   • attribution_data={ "partner_name": "googleadwords_int", "is_attributed": "true", "partner_campaign_name": "brand_us_en" }

2. El usuario se registra. Envía el evento de registro:

   • n=sng_registration_complete
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f (el mismo SDID)
   • custom_user_id=user_12345abc
   • Sin attribution_data

Usuario recurrente desde una nueva campaña

1. El mismo navegador regresa desde una campaña diferente. Envía una nueva visita de página:

   • n=__PAGE_VISIT__
   • conversion_event=true
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f (el mismo SDID)
   • attribution_data={ "partner_name": "facebook", "is_attributed": "true", "partner_campaign_name": "retargeting_Q1" }

2. El usuario realiza una compra. Envía el evento de compra:

   • n=sng_purchase
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f (el mismo SDID)
   • El custom_user_id persistido
   • Sin attribution_data