Tech Doc: Client Side JavaScript SDK Integration Guide | GLP Winner

Introduction

Our client side JavaScript SDK (glp.js) offers a way to track affiliate referrals and conversions if server-to-server integration is not an option. It handles the capture of affiliate click identifiers, manages user session tracking via first-party cookies, and reports conversion events back to GLP Winner.

JavaScript SDK Features

Quick Setup: Add a simple script tag and a short initialization call to your website. Then call glp.trackConversion() to report a conversion.
Client-Side Tracking: Captures affiliate information directly from the user's browser session.
Automatic Click ID & URL Parameter Handling: The SDK automatically detects glp_click_id (and optionally glp_email) from URL query parameters.
Hosted Session Management: The script initializes with glp_click_id, hits GLP Winner's session service and returns a session_token that is then stored in a first-party cookie.

How It Works: Data Flow

User Arrives via Affiliate Link: A user clicks an affiliate link from GLP Winner and lands on your website (e.g., YourProviderSite.com?glp_click_id=UNIQUE_CLICK_ID&glp_email=ENCODED_EMAIL).
SDK Initialization (glp.init()):

The glp.js script, embedded on your page, executes.
glp.init() is called with your providerId (required) and other configurations (optional).
The SDK parses the URL for glp_click_id (required) and glp_email (optional).

Click/Session Processing (depends on useSession config):

If useSession: true (default & highly recommended):
1. The SDK sends the glp_click_id, your providerId, any captured email, and UTM parameters to GLP Winner's /api/track/v1/session endpoint.
2. GLP Winner's server logs the click details (IP, User-Agent, etc.) and associates them with the click ID and provider.
3. The server returns a unique session_token.
4. The SDK stores this session_token in a first-party cookie (e.g., _glp_sid) on your domain. The raw glp_click_id cookie (if any) is cleared.
If useSession: false:
1. The SDK stores the raw glp_click_id directly into a first-party cookie (e.g., _glp_cid) on your domain.
2. No call is made to the /api/track/v1/session endpoint. The session_token cookie (if any) is cleared.
3. Note: If going this route then on conversion, /api/track/v1/conversion must be called with an API key. i.e., you must POST via s2s postback. This implies you are using client side SDK in addition to server side postback.

User Browsing: The user navigates your site. The _glp_sid or _glp_cid cookie persists, maintaining the affiliate referral context.
Conversion Event: The user completes a conversion action (e.g., signs up, makes a purchase).
SDK Tracks Conversion (glp.trackConversion()):

1. You call glp.trackConversion() in your website's JavaScript, optionally passing conversion-specific data (e.g., user's email if not known before, your internal order ID).
2. The SDK retrieves the session_token (if useSession: true) or the glp_click_id (as transaction_id, if useSession: false) from the cookie.
3. It sends this identifier, along with your providerId and any conversionData, to GLP Winner's /api/track/v1/conversion endpoint.

GLP Winner Server Processes Conversion:

1. The server authenticates the request (trusting a valid session_token linked to your providerId, or requiring your secret api_token for S2S-like calls if transaction_id is sent without a session context).
2. It attributes the conversion to the original click, performs deduplication, and stores the conversion record.

Post-Conversion (SDK):

- If clearCookieOnConversion: true (default), the SDK clears the tracking cookies (_glp_sid, _glp_cid) after a successful conversion report.
- Internal SDK flags are updated.

Installation

Include the glp.js script on all pages of your website where you want to track affiliate referrals, especially landing pages and conversion pages. It's recommended to place it in the <head> or at the end of the <body>.

1<script src="https://glpwinner.com/js/glp.js"></script>

Initialization: glp.init()

Initialize the SDK once per page load, after the script has loaded.

1<script>
2  // Create queue stub
3 (function() {
4   if (!window.glp) {
5     window.glp = {
6       _queue: [],
7       init: function() {
8         window.glp._queue.push({method: 'init', args: arguments});
9       },
10       trackConversion: function() {
11         window.glp._queue.push({method: 'trackConversion', args: arguments});
12       },
13       trackLead: function() {
14         window.glp._queue.push({method: 'trackLead', args: arguments});
15       }
16     };
17   }
18 })();
19
20  
21  // Initialize immediately - will queue if SDK not loaded yet
22  window.glp.init({
23    providerId: YOUR_PROVIDER_ID, // Replace with your numeric Provider ID
24    testMode: false // Set to true for testing
25  });
26</script>

Configuration Options for glp.init(configObject):

providerId (Number, Required): Your unique numeric Provider ID assigned by GLP Winner.
useSession (Boolean, Optional, Default: true):
- true: The SDK calls /api/track/v1/session to register the click and get a session_token, which is stored in cookieNameSessionToken (_glp_sid). Recommended for most users.
- false: The SDK stores the raw glp_click_id in cookieNameClickId (_glp_cid) and does not call /api/track/v1/session.
userEmail (String, Optional, Default: null): If the user's email is known at the time of init (e.g., they are logged in on your site), you can pass it here. This email will be sent to /api/track/v1/session (if useSession: true) and stored with the click for improved soft-matching. This takes precedence over an email passed via the glp_email URL parameter.
clearCookieOnConversion (Boolean, Optional, Default: true): If true, the SDK will attempt to clear cookieNameClickId and cookieNameSessionToken after a conversion is successfully reported to the /api/track/v1/conversion endpoint.
testMode (Boolean, Optional, Default: false): If set to true, the SDK will append a ?testMode=true query parameter to all API calls it makes to /api/track/v1/session and /api/track/v1/conversion. This signals the GLP Winner backend to treat the generated data (clicks, conversions) as test data, which can be useful for integration testing without affecting production metrics. The API response will also indicate if it was processed in test mode.
cookieNameClickId (String, Optional, Default: '_glp_cid'): Custom name for the cookie that stores the raw glp_click_id (used when useSession: false).
cookieNameSessionToken (String, Optional, Default: '_glp_sid'): Custom name for the cookie that stores the session_token (used when useSession: true).
cookieExpiresDays (Number, Optional, Default: 30): Expiration period in days for the tracking cookies.
apiEndpoint (String, Optional, Default: 'https://www.glpwinner.com/api/track/v1'): The base URL for the GLP Winner tracking API endpoints. The SDK will append /session or /conversion to this base URL.

URL Parameters Handled by glp.init():

glp_click_id (Required for tracking): The SDK automatically looks for this parameter in the current page's URL. Its value is the core identifier for the affiliate click.
glp_email (Optional): If present, the SDK will decode this value and use it as the user's email when calling /api/track/v1/session (if useSession: true), unless userEmail is explicitly provided in the init configuration. The value should be URL-encoded (e.g., via encodeURIComponent).
UTM Parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content): If present in the URL, these are automatically collected by the SDK and sent to the /api/track/v1/session endpoint (if useSession: true) to be stored with the click data for analytics.

Initialization (React / Next.js): glp.init()

In top level layout.tsx or app.tsx.

1        <Script src='https://glpwinner.com/js/glp.js' strategy='beforeInteractive' />
2        <GLPInit />

GLPInit.tsx:

1'use client';
2
3import { useEffect } from 'react';
4
5declare global {
6 interface Window {
7   glp?: {
8     init: (config: GLPInitConfig) => void;
9     trackConversion: (data?: GLPConversionData) => void;
10     trackLead: (data?: GLPLeadData, step?: string) => void;
11     _queue?: Array<{ method: string; args: any[] }>;
12   };
13 }
14}
15
16interface GLPInitConfig {
17 providerId: number;
18 useSession?: boolean;
19 userEmail?: string;
20 clearCookieOnConversion?: boolean;
21 testMode?: boolean;
22 cookieNameClickId?: string;
23 cookieNameSessionToken?: string;
24 cookieExpiresDays?: number;
25 apiEndpoint?: string;
26}
27
28interface GLPConversionData {
29 email?: string;
30 conversion_id?: string;
31 ip?: string;
32}
33
34interface GLPLeadData {
35 email?: string;
36 lead_ref?: string;
37}
38
39export default function GLPInit() {
40 useEffect(() => {
41   // Check if glp_click_id exists in URL
42   const searchParams = new URLSearchParams(window.location.search);
43   if (!searchParams.has('glp_click_id')) {
44     console.log('GLP SDK: No glp_click_id found in URL, skipping initialization');
45     return;
46   }
47
48   // Create queue stub if SDK not loaded yet
49   if (!window.glp) {
50     window.glp = {
51       _queue: [],
52       init: function (...args) {
53         window.glp!._queue!.push({ method: 'init', args });
54       },
55       trackConversion: function (...args) {
56         window.glp!._queue!.push({ method: 'trackConversion', args });
57       },
58       trackLead: function (...args) {
59         window.glp!._queue!.push({ method: 'trackLead', args });
60       },
61     };
62   }
63
64   // Initialize (will queue if SDK not loaded)
65   window.glp.init({
66     providerId: YOUR_PROVIDER_ID,
67     testMode: true,
68   });
69
70   console.log('GLP SDK: Initialization called (may be queued if SDK still loading)');
71 }, []);
72
73 return null;
74}

Tracking Conversions: glp.trackConversion()

When a user completes a desired action (e.g., completes a purchase, submits a sign-up form), call glp.trackConversion().

Simplest Usage (No Optional Data): This is the most common way to call it if you don't have additional details like email or an internal conversion ID to pass. The SDK will automatically use the stored affiliate tracking information.

1// Example: Call on a "Thank You" page or after a successful form submission
2if (window.glp && window.glp.trackConversion) {
3  window.glp.trackConversion(); // Call with no arguments
4}

Usage with Optional Data: You can also pass an object with additional details if they are available.

1// Example: Call on a "Thank You" page or after a successful form submission
2if (window.glp && window.glp.trackConversion) {
3  window.glp.trackConversion({
4    email: 'converted_user@example.com',        // If email is known at conversion
5    conversion_id: 'YOUR_INTERNAL_ORDER_ID' // Your internal reference for this conversion. Useful for tracking conversions to orders during invoicing.
6    // ip: 'USER_IP_ADDRESS'                   // Rarely needed from client; server usually detects IP
7  });
8}

Parameters for glp.trackConversion(conversionData):

conversionData (Object, Optional): An object containing additional data about the conversion.
- email (String, Optional): The user's email address at the time of conversion. Useful for soft-matching if primary identifiers are missing.
- ip (String, Optional): The user's IP address. Useful for soft-matching if primary identifiers are missing.
- conversion_id (String, Optional but recommended): Your internal unique identifier for this conversion (e.g., order ID, user ID). This lets us map orders with conversions. This information can be surfaced at invoicing.

Authentication Note for trackConversion: The SDK's trackConversion method does not directly send your secret api_token.

If useSession: true was used during init, the /api/track/v1/conversion endpoint can authenticate the request using the session_token (which the SDK sends automatically). This is the recommended and more secure approach for client-side conversion tracking.
If useSession: false was used, the SDK sends the raw glp_click_id (as transaction_id). In this scenario, the /api/track/v1/conversion endpoint currently requires your main secret api_token for authentication. Since the SDK cannot securely store or send this secret token, conversion tracking initiated by the SDK with useSession: false will fail authentication unless you have a custom setup (e.g., a proxy server that injects the token, or using server side post back to POST conversion). It is strongly recommended to use useSession: true for SDK-based conversion tracking.

Troubleshooting / FAQ

No data appearing in GLP Winner:
- Check browser console for any SDK error messages.
- Verify glp.init() is called with the correct providerId.
- Ensure glp_click_id is present in the URL on landing pages from affiliate links. For testing, you can generate a test UUID here.
- Check network requests in browser developer tools to see if calls to /api/track/v1/session and /api/track/v1/conversion are being made and what the responses are.
Cookies not being set:
- Ensure the SDK script is loaded and glp.init() is called correctly.
- Check browser cookie settings; ensure first-party cookies are not blocked.
- Verify the domain/path for cookies in setCookie function (SDK handles this automatically to your site's root domain).
Ad Blockers: The SDK script is named glp.js and API calls are made to the configured apiEndpoint (https://www.glpwinner.com/api/track/...). While these names are chosen to be reasonably neutral, some aggressive ad/privacy blockers might still interfere by blocking requests to domains or paths known or suspected to be involved in tracking. Common path segments like /track/ or /conversion/ can sometimes be targeted by filter lists. Using the Server-to-Server (S2S) integration is the most robust method to avoid client-side ad blocker interference.

For questions or support, please contact email us.

Client Side JavaScript SDK Integration Guide

Introduction

How It Works: Data Flow

Installation

Initialization: glp.init()

Initialization (React / Next.js): glp.init()

Tracking Conversions: glp.trackConversion()

Troubleshooting / FAQ

Keep Reading

Server-to-Server (S2S) API Integration Guide

Google Analytics & Tag Manager Setup Guide

Curated by