Overview

Web Server-to-Server (Web S2S) sends web conversion and engagement events to Singular directly from your server, using the same EVENT endpoint as the mobile V1 integration. The web path is differentiated by the platform parameter p=Web.

Web S2S is a browser-assisted architecture. Several attribution-relevant values are only available in the browser — location.href, document.referrer, and the browser userAgent cannot be reconstructed on the backend. A thin client-side snippet must collect these values and either call the endpoint directly or forward them to your backend, which then makes the S2S call.

There is no web SESSION endpoint. The first __PAGE_VISIT__ conversion event replaces the mobile launch call and establishes the attribution baseline for the visit.

Endpoint

Web S2S uses the same host and path as the mobile V1 EVENT endpoint. Set p=Web to route the request through the web attribution path.

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

SDID Generation and Persistence

The Singular device ID (sdid) ties all events from one browser to a single web device. On first page load, if no global_singular_id exists in localStorage, generate a UUID v4 and store it. Reuse the same value as sdid on every event from that browser until localStorage is cleared.

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

The __PAGE_VISIT__ Pattern

The first event of any new visit MUST be __PAGE_VISIT__ with conversion_event=true. This establishes the attribution baseline that later events inherit.

Non-conversion events (for example sng_registration_complete or sng_purchase) use conversion_event=false and omit attribution_data. They inherit attribution from the most recent __PAGE_VISIT__.

custom_user_id rules

• Include custom_user_id after registration or login, and on all subsequent events.
• Persist it in localStorage or a first-party cookie.
• Drop it on logout.
• Never include PII. Use a hashed or internal ID.

Parameters

The Web SDK sends roughly 40 parameters on __PAGE_VISIT__, but most are SDK-internal telemetry that S2S developers should not replicate. The tables below cover the required and recommended sets only.

Required parameters

Recommended parameters

For device identity and other shared parameters not listed above, see the Common Parameters in S2S Fundamentals rather than re-documenting them here.

attribution_data

The attribution_data parameter carries click-through data from ad networks as URL-encoded JSON. Send it on __PAGE_VISIT__ conversion events only.

{
  "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": ""
}

Required fields

Optional fields

Web click IDs in the e param

Pass network click IDs in the event e payload using the JSON key each partner expects:

Web-to-App Attribution

To carry web campaign context into a mobile click, build a Singular Link from your landing page and append the captured landing query string. This forwards the marketing parameters to the mobile click so the app install can be attributed.

On landing, capture window.location.search (plus fragment) when it contains marketing params and persist it. When rendering the app-store or smart-banner link, build:

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

Clipboard Attribution (Deferred Deep Link)

Clipboard attribution provides a deterministic match for a deferred deep link. The web snippet writes a unique token to the clipboard; the freshly installed app reads it back and matches on token equality.

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

Event Sequence Examples

First visit and registration

1. User arrives from Google Ads. Send the initial page visit:

   • 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. User registers. Send the registration event:

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

Returning user from a new campaign

1. The same browser returns from a different campaign. Send a new page visit:

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

2. User purchases. Send the purchase event:

   • n=sng_purchase
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f (same SDID)
   • Persisted custom_user_id
   • No attribution_data