Identity and Privacy

SDK 3.0.0 denies optional processing until your consent manager supplies the visitor’s affirmative purpose choices. The SDK separates session, authenticated-user, and optional device identity. None of these identifiers should be shared across merchant workspaces.

Identity layers

Identifier	Source	Behavior
session_id	SDK session manager	Memory-only before consent; persisted after a processing purpose is granted; rotates after inactivity or reset.
user_id	Your identify() call	Optional merchant-scoped authenticated user ID.
device_id	SDK device identity	Random and memory-only before consent; persisted after grant; separately consented fingerprinting can replace it.

Identify a user after your storefront authentication succeeds and analytics or personalization consent has been granted:

window.upsurge.identify('customer_48291', {
  customer_segment: 'loyalty_member',
});

On logout or account switching:

window.upsurge.setProfileToken();
window.upsurge.reset();

Do not send raw personal data

Do not use email addresses, phone numbers, postal addresses, IP addresses, or other direct identifiers as browser event properties. Use your merchant-scoped user ID and consented, non-sensitive traits.

Signed-in customers

identify() labels events with your customer ID, but any script on a page can call it with any ID. So browser requests use what Upsurge knows about a customer (profile fields like {{profile.first_name}}, customer groups, cohorts, order history) only when your server vouches for who is signed in. Without that, overlays, chatbots, recommendations, Smart Search and workflows personalize by the visitor's own device and session, and the visitor's events update only that device's profile and audiences.

Shopify and WooCommerce storefronts do this automatically through the Upsurge app and plugin. On a custom storefront, mint a token on your server with a secret API key that has profiles:write:

curl -X POST https://api.upsur.ge/api/v1/profile-tokens \
  -H "X-API-Key: $UPSURGE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"merchant_user_id":"customer_48291"}'

The response carries data.profile_token and data.expires_at. Mint it only for the customer your storefront just authenticated, and only after they allowed personalization. Pass it to the page with the signed-in session, then:

window.upsurge.identify('customer_48291');
window.upsurge.setProfileToken(profileToken);

Tokens last five minutes. Fetch a new one from your server and call setProfileToken() again before expires_at; an expired token never breaks the page, it just leaves the visitor anonymous. Never send the secret key to the browser, and keep profiles:write keys on servers you trust: they can mint a token for any of your customers. Shopify and WooCommerce customer IDs (shopify:…, woocommerce:…) are refused here; those stores' own integrations issue their tokens.

Do Not Track

Set respectDoNotTrack: true if your privacy policy treats the browser DNT preference as an opt-out. When DNT is present, the SDK disables tracking during initialization.

Consent manager integration

Connect the SDK to the visitor’s choice. Do not hardcode these grants in production:

// Run this callback after a valid recorded choice, and whenever the visitor changes it.
function onConsentChanged(choice) {
  window.upsurge.setConsent({
    analytics: choice.analytics === true,
    personalization: choice.personalization === true,
    marketing: choice.marketing === true,
    fingerprinting: choice.fingerprinting === true,
  });
}

All four choices default to false. setConsent() updates only the supplied purposes. Your CMP retains the choice and proof of consent; supply it on each page. Loading the SDK does not grant consent. Before consent, only the site-ID runtime bootstrap can run; optional requests, automatic analytics and persistent SDK identifiers remain disabled.

Analytics enables event capture. Personalization enables recommendations and cart/profile context. Marketing plus personalization enables overlays, proactive chatbots and workflow campaigns. Partner attribution also requires analytics. A grant for one purpose does not authorize another.

Withdrawal aborts pending optional requests, discards queued events, removes SDK browser storage, stops campaign managers and invalidates late responses. Unrelated merchant storage remains intact. Regranting never replays the old queue. Already delivered server data requires the merchant’s authenticated withdrawal/erasure workflow.

Fingerprinting

Fingerprinting requires both enableFingerprinting: true in configuration and a separate consent.fingerprinting: true choice, together with a granted processing purpose. Enabling the feature alone never loads the fingerprint library.

Use setConsent({ fingerprinting: false }) or clearFingerprint() when that choice is withdrawn. Pending fingerprint work cannot recreate a stored identifier after withdrawal. isFingerprintingEnabled() reports the runtime state.

Profile personalization

updateProfilePersonalization() and clearProfilePersonalization() accept a curated merchant-scoped field set such as first name, display name, preferences, loyalty tier, lifecycle stage, value bands, and recent product/category IDs. They require analytics and personalization consent, plus consent metadata or an existing consent grant reference.

What the browser can and cannot write:

• With a profile token set (see Signed-in customers), these calls update or clear that customer's profile. SDK 3.0.8 and later send the token with the events.
• Without one, they update or clear the visitor's own record on this device, which overlays, chatbots and recommendations on the same browser read back.
• The ID you passed to identify() never picks whose profile is written, because any script on the page could pass someone else's ID. It only labels the analytics event.
• From your server, a secret API key can update any customer's profile (POST /api/v1/profile-personalization).

The SDK removes raw email, phone, address, location, and IP-shaped fields from personalization updates before queueing. These helpers use ordinary event ingestion. After analytics or personalization is withdrawn, use the authenticated server/privacy workflow to clear a stored profile; a browser clear event cannot bypass denial.

Use server-side governed imports for sensitive identity processing; do not attempt to reconstruct cross-merchant identity in the browser.

Legacy consent setters

setAttributionConsent({ analytics, advertising }) maps only to analytics and marketing. It does not grant personalization or fingerprinting. setWorkflowCommandConsent({ marketing, personalization }) maps only to those two choices. Initial legacy configuration follows the same purpose mapping, with top-level consent taking precedence. Migrate to a single setConsent() callback from your CMP. See Configuration.