### Q: What is `partner.js`? `partner.js` is Agoda's frontend SDK solution that enables partners to securely associate each booking attempt with a verified browser session. It generates a booking token that must be included in booking requests sent to Agoda's Affiliate Book API. This token allows Agoda to perform enhanced fraud analysis during booking processing, helping protect both partners and customers ### Q: Why do I need to integrate `partner.js`? For all Agoda merchant-of-record transactions, partners must integrate with `partner.js`. This is a mandatory requirement that: Enables enhanced fraud detection and prevention - Provides verified session and device context for each booking - Helps reduce fraudulent transactions and chargebacks - Ensures compliance with Agoda's booking security requirements ### Q: What are the main steps of the integration? The `partner.js` solution consists of three key steps: - Include `partner.js` on your website – Load the SDK script on your checkout page (and optionally on landing/search pages) - Initialize a session in the browser – Call the SDK initialization method to initialize the FE script - Generate and submit the booking context token – Invoke the checkout method to generate a token and include it in your Affiliate Book API request ### Q: Where should I include the `partner.js` script? Required: - Checkout page (mandatory) Recommended: - Landing page - Search results page - Property details page Loading `partner.js` earlier in the customer journey (e.g., landing page) establishes the session sooner, providing better coverage and more comprehensive fraud detection signals. ### Q: How do I initialize the SDK? Example Place the script in the or before the closing tag: ### Q: What callbacks/events should I register? You should register handlers for three key events: ### Q: When and how do I generate the booking context token? Immediately before submitting the booking to your backend, invoke the SDK's checkout method to generate the verification token. The token will be returned via the "token" event callback you registered earlier. Your frontend must then forward this token to your backend, which will include it unchanged in the Affiliate Book API request. ### Q: Is the SDK blocking? Will it slow down my page? No. The SDK is designed to be non-blocking and collects browser and device context signals asynchronously. It won't interfere with your page load performance or user experience. ### Q: When should the token be generated? The booking context token must be treated as an opaque value. Follow these critical rules: ✅ DO: - Treat the token as opaque (a black box) - Store temporarily in memory only(if needed only) - Forward unchanged to your backend - Pass unchanged to Agoda's Affiliate Book API ❌ DO NOT: - Decode, parse, or modify the token - Persist to localStorage or sessionStorage - Log the token (or mask it if logging is unavoidable) - Attempt to read or interpret the token contents Why? The token contains cryptographically signed data. Any modification will invalidate it and cause booking failures. ### Q: What is Content Security Policy (CSP) and why do I need to update it? Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) and other code injection attacks by controlling which resources can be loaded on your website. `partner.js` dynamically loads additional scripts and sends browser beacons for fraud detection and telemetry. To ensure full functionality, you must update your CSP to allow: Agoda SDK CDN - Riskified endpoints (fraud detection vendor) - Bento analytics endpoints (telemetry) Without these updates, your browser will block required network calls and the SDK won't function properly. ### Q: What CSP directives do I need to update? You need to update the following CSP directives: 1. script-src (allow loading SDK and beacon scripts): Agoda SDK CDN: Riskified: Bento analytics domains (provided during onboarding) If using nonces: 'nonce-YOUR_NONCE_VALUE' 2. connect-src (allow XHR/fetch/beacon network calls): Agoda SDK backend endpoints (provided during onboarding) Riskified: https\://\*.riskified.com Bento analytics collection endpoints (provided during onboarding) 3. img-src (allow pixel beacons): Riskified: data: (only if your policy already allows inline data URIs) Bento image endpoints (if applicable, provided during onboarding) 4. frame-src / child-src (if needed): Rarely required; onboarding will indicate if needed 5. report-uri or report-to (recommended): Collect CSP violation reports during rollout ### Q: How can I implement CSP updates? 1. Option A: Add CSP via HTML meta tag 2. Option B: Set CSP in HTTP response headers (recommended) Configure CSP at your web server, CDN, or gateway level for consistent, centralized management: ``` Content-Security-Policy: script-src 'self' 'unsafe-inline' 'unsafe-eval' ; connect-src 'self' ws: wss:; worker-src 'self' https\://\*.agoda.local; ``` Generate the token when the user initiates a booking action (for example, clicking the “Book” button) to ensure the token is fresh and valid. ### Q: What if I use nonces for CSP? If you use nonces, you can pass your nonce value to the SDK during initialization: ``` window.partnerSDK.init({ siteId: "12345", environment: "production", cspNonce: "rAnd0m12345", // Your page's CSP nonce // ... other config }); ``` Also include 'nonce-YOUR_NONCE_VALUE' in your CSP script-src directive. ### Q: What does my backend need to do? Your backend has two simple responsibilities: - Accept the booking context token from your frontend (e.g., via a form field or API parameter). - Forward the token unchanged to Agoda's Affiliate Book API as part of the booking request. - The token must be included exactly as received—do not modify, decode, or parse it. ### Q: How do I pass the token from frontend to backend? Your frontend should send the token to your backend as part of the booking submission. Common approaches: - Hidden form field: Include the token in a hidden input field in your booking form. - API parameter: Send the token as a parameter in your AJAX/fetch booking request. - Request header: Pass the token in a custom HTTP header. - Choose the method that best fits your existing architecture. What field name should I use in the Affiliate Book API? Refer to the Affiliate Book API documentation provided by Agoda for the exact parameter name and format. The documentation will specify where and how to include the booking context token in your API request. ### Q: Can the script be loaded asynchronously? Yes. Asynchronous loading is supported and recommended to minimize performance impact. Ensure initialization happens after the script loads. ### Q: Is the script required in sandbox and production environments? Yes. Integration is required in both environments. Test thoroughly in a sandbox before moving to production. ### Q: What data does the script collect? The script collects frontend signals necessary for fraud detection and risk assessment. No action is required from the partner beyond integration. ### Q: What happens if token generation fails? You should implement error handling and retry logic. If the issue persists, log the error and contact support. ### Q: SDK loads but beacons don’t run (or errors appear in console) under strict CSP CSP blocks the SDK CDN and/or Bento/Riskified endpoints. Prefer setting CSP via HTTP response headers and allow required domains. If using nonces, pass cspNonce. ### Q: Sandbox works but production fails (or vice versa) Ensure environment/env matches your backend environment. ### Q: Works on checkout page but signals are weak / inconsistent Include script (and call init()) globally on each page, or at least from landing onward ### Q: SDK loads slowly and delays checkout Script loaded too late (only on checkout page), no preloading / caching or slow connection to CDN region ### Q: Can we avoid sending PAN/CVV to the SDK? Per current interface, checkout() accepts raw card inputs in the affiliate flow (“Phase 1”). If/when tokenization changes in later phases, the integration contract may evolve. ### Q: Do we need to call destroy() on multi-page websites? On multi-page sites, destroy() is usually not required for page reloads, but since the SDK sessionId persists in cookies for up to ~2 hours, you should call destroy() when you need to force a fresh session context (e.g., user abandons checkout and later restarts, account/user changes, or you explicitly want a new risk session for a new attempt)