개요

Web Server-to-Server(Web S2S)는 모바일 V1 연동과 동일한 EVENT 엔드포인트를 사용하여 서버에서 직접 Singular로 웹 전환 및 인게이지먼트 이벤트를 전송합니다. 웹 경로는 플랫폼 파라미터 p=Web 으로 구분됩니다.

Web S2S는 브라우저 보조 아키텍처 입니다. 여러 어트리뷰션 관련 값은 브라우저에서만 사용할 수 있습니다 — location.href , document.referrer , 그리고 브라우저 userAgent 는 백엔드에서 재구성할 수 없습니다. 얇은 클라이언트 측 스니펫이 이러한 값을 수집하여 엔드포인트를 직접 호출하거나, S2S 호출을 수행하는 백엔드로 전달해야 합니다.

웹 SESSION 엔드포인트는 존재하지 않습니다 . 첫 번째 __PAGE_VISIT__ 전환 이벤트가 모바일 launch 호출을 대체하고 해당 방문에 대한 어트리뷰션 기준을 설정합니다.

엔드포인트

Web S2S는 모바일 V1 EVENT 엔드포인트와 동일한 호스트 및 경로를 사용합니다. 요청을 웹 어트리뷰션 경로로 라우팅하려면 p=Web 를 설정하세요.

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

SDID 생성 및 유지

Singular 디바이스 ID( sdid )는 한 브라우저에서 발생하는 모든 이벤트를 하나의 웹 디바이스에 연결합니다. 첫 페이지 로드 시 localStorage 에 global_singular_id 가 존재하지 않으면 UUID v4를 생성하여 저장합니다. localStorage 가 지워질 때까지 해당 브라우저의 모든 이벤트에서 동일한 값을 sdid 로 재사용하세요.

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

__PAGE_VISIT__ 패턴

새 방문의 첫 이벤트는 반드시 conversion_event=true 가 설정된 __PAGE_VISIT__ 여야 합니다. 이는 이후 이벤트가 상속하는 어트리뷰션 기준을 설정합니다.

비전환 이벤트(예: sng_registration_complete 또는 sng_purchase )는 conversion_event=false 를 사용하고 attribution_data 를 생략 합니다. 이들은 가장 최근의 __PAGE_VISIT__ 로부터 어트리뷰션을 상속합니다.

custom_user_id 규칙

• 등록 또는 로그인 이후, 그리고 이후의 모든 이벤트에 custom_user_id 를 포함하세요.
• 이를 localStorage 또는 퍼스트파티 쿠키에 유지하세요.
• 로그아웃 시 제거하세요.
• 절대 PII를 포함하지 마세요. 해시된 ID 또는 내부 ID를 사용하세요.

파라미터

Web SDK는 __PAGE_VISIT__ 에서 약 40개의 파라미터를 전송하지만, 대부분은 S2S 개발자가 복제해서는 안 되는 SDK 내부 텔레메트리입니다. 아래 표는 필수 및 권장 세트만 다룹니다.

필수 파라미터

권장 파라미터

디바이스 식별자 및 위에 나열되지 않은 기타 공통 파라미터에 대해서는 여기서 다시 문서화하지 않고 S2S Fundamentals의 공통 파라미터 를 참조하세요.

attribution_data

attribution_data 파라미터는 광고 네트워크의 클릭스루 데이터를 URL 인코딩된 JSON으로 전달합니다. __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": ""
}

필수 필드

선택 필드

e 파라미터의 웹 클릭 ID

각 파트너가 요구하는 JSON 키를 사용하여 네트워크 클릭 ID를 이벤트 e 페이로드에 전달하세요:

Web-to-App 어트리뷰션

웹 캠페인 컨텍스트를 모바일 클릭으로 전달하려면 랜딩 페이지에서 Singular Link를 생성하고 캡처한 랜딩 쿼리 문자열을 추가하세요. 이렇게 하면 마케팅 파라미터가 모바일 클릭으로 전달되어 앱 설치를 어트리뷰션할 수 있습니다.

랜딩 시 window.location.search (및 프래그먼트)가 마케팅 파라미터를 포함할 때 이를 캡처하여 유지하세요. 앱스토어 또는 스마트 배너 링크를 렌더링할 때 다음을 생성하세요:

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

클립보드 어트리뷰션(디퍼드 딥링크)

클립보드 어트리뷰션은 디퍼드 딥링크에 대한 결정론적 매칭을 제공합니다. 웹 스니펫이 고유 토큰을 클립보드에 기록하면, 새로 설치된 앱이 이를 다시 읽어 토큰 일치 여부로 매칭합니다.

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

이벤트 시퀀스 예시

첫 방문 및 등록

1. 사용자가 Google Ads에서 도착합니다. 초기 페이지 방문을 전송하세요:

   • 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. 사용자가 등록합니다. 등록 이벤트를 전송하세요:

   • n=sng_registration_complete
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f (동일한 SDID)
   • custom_user_id=user_12345abc
   • attribution_data 없음

새 캠페인에서 돌아온 사용자

1. 동일한 브라우저가 다른 캠페인에서 돌아옵니다. 새 페이지 방문을 전송하세요:

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

2. 사용자가 구매합니다. 구매 이벤트를 전송하세요:

   • n=sng_purchase
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f (동일한 SDID)
   • 유지된 custom_user_id
   • attribution_data 없음