Visão geral

O Web Server-to-Server (Web S2S) envia eventos de conversão e engajamento da web para o Singular diretamente do seu servidor, usando o mesmo endpoint EVENT da integração móvel V2. O caminho da web é diferenciado pelo parâmetro de plataforma p=Web .

O Web S2S é uma arquitetura assistida pelo navegador . Vários valores relevantes para atribuição estão disponíveis apenas no navegador — location.href , document.referrer e o userAgent do navegador não podem ser reconstruídos no backend. Um trecho de código leve no lado do cliente precisa coletar esses valores e chamar o endpoint diretamente ou encaminhá-los para o seu backend, que então faz a chamada S2S.

Não há endpoint SESSION da web . O primeiro evento de conversão __PAGE_VISIT__ substitui a chamada launch móvel e estabelece a linha de base de atribuição para a visita.

Endpoint

O Web S2S usa o mesmo host, caminho e método POST do endpoint EVENT V2 para dispositivos móveis. Defina p=Web para rotear a solicitação pelo caminho de atribuição web.

POST https://s2s.singular.net/api/v2/evt

Cabeçalho obrigatório:

Content-Type: application/x-www-form-urlencoded

Geração e persistência do SDID

O ID de dispositivo do Singular ( sdid ) vincula todos os eventos de um navegador a um único dispositivo web. No primeiro carregamento da página, se nenhum global_singular_id existir no localStorage , gere um UUID v4 e armazene-o. Reutilize o mesmo valor como sdid em todos os eventos daquele navegador até que o localStorage seja limpo.

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

O padrão __PAGE_VISIT__

O primeiro evento de qualquer nova visita DEVE ser __PAGE_VISIT__ com conversion_event=true . Isso estabelece a linha de base de atribuição que os eventos posteriores herdam.

Eventos de não conversão (por exemplo sng_registration_complete ou sng_purchase ) usam conversion_event=false e omitem attribution_data . Eles herdam a atribuição do __PAGE_VISIT__ mais recente.

Regras de custom_user_id

• Inclua custom_user_id após o registro ou login, e em todos os eventos subsequentes.
• Persista-o no localStorage ou em um cookie de primeira parte.
• Remova-o no logout.
• Nunca inclua PII. Use um ID interno ou com hash.

Parâmetros

O Web SDK envia aproximadamente 40 parâmetros no __PAGE_VISIT__ , mas a maioria é telemetria interna do SDK que os desenvolvedores de S2S não devem replicar. As tabelas abaixo cobrem apenas os conjuntos obrigatórios e recomendados.

Parâmetros obrigatórios

Parâmetros recomendados

Para identidade de dispositivo e outros parâmetros compartilhados não listados acima, consulte a referência do endpoint EVENT em vez de redocumentá-los aqui.

attribution_data

O parâmetro attribution_data carrega dados de click-through de ad networks como JSON codificado em URL. Envie-o somente em eventos de conversão __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 obrigatórios

Campos opcionais

IDs de clique da web no parâmetro e

Passe os IDs de clique da network no payload e do evento usando a chave JSON que cada parceiro espera:

Atribuição web-to-app

Para levar o contexto de campanha da web para um clique móvel, crie um Singular Link a partir da sua landing page e anexe a query string de landing capturada. Isso encaminha os parâmetros de marketing para o clique móvel para que a instalação do app possa ser atribuída.

Ao chegar na landing page, capture window.location.search (mais o fragmento) quando ela contiver parâmetros de marketing e persista-o. Ao renderizar o link da app store ou do smart banner, construa:

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

Atribuição por clipboard (deferred deep link)

A atribuição por clipboard fornece uma correspondência determinística para um deferred deep link. O trecho de código web grava um token único no clipboard; o app recém-instalado o lê de volta e faz a correspondência por igualdade 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);
}

Exemplos de sequência de eventos

Primeira visita e registro

1. O usuário chega pelo Google Ads. Envie a page visit 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. O usuário se registra. Envie o evento de registro:

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

Usuário retornante de uma nova campanha

1. O mesmo navegador retorna de uma campanha diferente. Envie uma nova page visit:

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

2. O usuário faz uma compra. Envie o evento de compra:

   • n=sng_purchase
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f (mesmo SDID)
   • custom_user_id persistido
   • Sem attribution_data