Skip to main content

CDN Integration

Prerequisites

  1. Active siteKey from Selwise dashboard.
  2. Correct API URL ending with /api/v1.
  3. Verified storefront domain for public guard origin checks.
  4. A single base layout where script can be injected once.

Currency rule: use ISO-4217 uppercase codes and replace SITE_CURRENCY in examples with your configured site currency.

Installation

<script
  src="https://widget.selwise.com/client.js"
  data-site-key="YOUR_SITE_KEY"
  data-api-url="https://api.selwise.com/api/v1"
></script>

Required:

  • src="https://widget.selwise.com/client.js"
  • data-site-key

Optional:

  • data-api-url

Initialization

CDN mode auto-initializes and binds runtime to window.Selwise.

console.log(window.Selwise);
console.log(window.Selwise?.siteKey);
console.log(window.Selwise?.apiUrl);

Single-instance rule:

  • Place script in root/base storefront template.
  • Do not inject script in route-level partials.
await window.Selwise?.identify?.('user_42', { email: 'user@example.com' });
await window.Selwise?.setTraits?.({ loyaltyTier: 'gold' });

const consent = window.Selwise?.getConsentState?.();
console.log(consent);

window.Selwise?.grantConsent?.({ analytics: true, marketing: true, preferences: true });
window.Selwise?.revokeConsent?.(['marketing']);

Event Sending

window.Selwise?.track?.('product_view', {
  entityType: 'product',
  entityId: 'SKU-123',
  metadata: { productItemCode: 'SKU-123', title: 'Runner Pro', price: 149.9 },
});

window.Selwise?.pushDataLayer?.({
  event: 'add_to_cart',
  basket: {
    id: 'cart_001',
    currency: 'SITE_CURRENCY',
    total: 149.9,
    products: [{ sku: 'SKU-123', quantity: 1, price: 149.9 }],
  },
});

For full event catalog and canonical payloads:

Order Tracking

await window.Selwise?.trackOrder?.({
  orderId: 'ORDER-1001',
  currency: 'SITE_CURRENCY',
  total: 149.9,
  items: [{ productItemCode: 'SKU-123', quantity: 1, unitPrice: 149.9 }],
});

Search and Recommendation Usage

window.Selwise?.pushDataLayer?.({
  event: 'search_query',
  search: { query: 'running shoes', results: 120 },
});

window.Selwise?.pushDataLayer?.({
  event: 'click',
  custom: { params: { placement: 'home_reco', widgetId: 'widget_home_1' } },
});

Verification Checklist

  1. window.Selwise exists after page load.
  2. Config request succeeds: GET /public/sites/:siteKey/config.
  3. Event probe reaches POST /public/sites/:siteKey/events/batch.
  4. trackOrder probe reaches POST /public/sites/:siteKey/orders.
  5. Consent state changes are reflected.

Full runbook: Verification

Troubleshooting (Common)

  1. window.Selwise undefined.
  • Wrong script host/path or blocked script by CSP/network policy.
  1. 403 origin validation failed.
  • Domain not verified or request origin mismatch.
  1. Events missing.
  • Invalid canonical payload or consent blocking event family.

Full matrix: Integration Troubleshooting

Production Go-Live Checklist

  • Script tag exists exactly once in base template.
  • siteKey and apiUrl match target environment.
  • Domain verification completed in dashboard.
  • Event/order/consent probes validated on staging.
  • Retry/backoff behavior ready for transient failures.

Next