HeldSway JavaScript SDK — Overview
The HeldSway JavaScript SDK enables storefronts and web apps to track affiliate referral links, visitor sessions, ecommerce funnel actions, and final order conversions.
SDK Architecture & Flow
flowchart LR
A[Visitor arrives via ref link] --> B[SDK captures ref & sets cookie]
B --> C[Pageviews & Product views tracked]
C --> D[Cart & Checkout events recorded]
D --> E[Completed order conversion attributed]
- Visitor Ingestion: When a visitor arrives via a link with
?ref=<code_or_slug>, the SDK initializes a visitor session, saves a first-party tracking cookie, and logs the click. - Session Persistence: The session token and cookie persist across navigation, ensuring conversions are accurately attributed according to your business’s cookie expiration window.
- Funnel Tracking: Track product views, cart modifications, checkouts, and visitor identification throughout the purchase funnel.
- Conversion Recording: When an order is placed,
trackOrder()attributes the sale, enforces idempotency against duplicates, and computes commissions.
SDK Method Reference
| Method | Description | Guide |
|---|---|---|
init() |
Initialize the SDK with your API key and default options. | Installation |
identify() |
Associate a logged-in user’s email or ID with the affiliate session. | Customer Login |
trackProductDetailsViewed() |
Record a product detail page view. | Product Details |
trackAddToCart() |
Record an item added to the cart. | Cart Tracking |
trackRemoveFromCart() |
Record an item removed from the cart. | Cart Tracking |
trackCheckout() |
Record customer proceeding to the checkout page. | Checkout |
trackOrder() |
Record a completed order with line items and subtotal. | Order Page |
trackThankYouPageViewed() |
Log the thank-you / receipt page visit. | Order Page |
getDiscount() |
Look up details for an affiliate promo code. | Discounts |
validateDiscount() |
Validate a promo code against a cart total. | Discounts |
destroy() |
Reset session, clear cookies, flush events, and remove listeners. | Cleanup |
Quick Start Installation
Add the script tag to your site’s <head>:
<script src="https://s3.us-east-2.amazonaws.com/cdn.rentmy.co/affiliate/prod/affiliate-sdk.min.js"></script>
Initialize the client with your public API key:
await window.AffiliateSDK.init({
apiKey: "as_live_01HXYZ1234567890",
enablePageviews: true
});
Continue with the Installation Guide for full configuration options and frontend framework integrations.