Guides

Validate your scripts installation

Suggest Edits

Overview

This technical guide provides detailed validation procedures to ensure that all JOIN Stories scripts are correctly installed and functioning as expected on your website.

📘

Prerequisites

Before starting validation, complete the installation guide.

1. Global Script Validation

1.1 Script Installation

The global script must be installed in the <head> section of all pages:

<script src="https://{TEAM_ID}.my.join-stories.com/scripts/global.js" type="text/javascript"></script>

📘

Team ID Configuration

Ensure that {TEAM_ID} in the script URL corresponds to your actual team ID. You can find it in Settings dropdown.

1.2 Validation Process

Step 1: DOM Verification

  1. Open DevTools (F12)
  2. Navigate to the Elements tab
  3. Search for the script tag in the <head> section
  4. Verify the URL matches your configured domain

Step 2: Network Loading Verification

  1. Go to the Network tab in DevTools
  2. Reload the page
  3. Search for the request to global.js
  4. Verify HTTP status is < 400 (for example: 200 OK)

Step 3: JavaScript Object Verification

  1. Open the DevTools Console
  2. Execute: window.joinStories
  3. Verify the object is defined and contains the key globalScript

1.3 Success Indicators

  • ✅ Script tag present in <head> section
  • ✅ global.js file loads successfully (200 OK status)
  • ✅ window.joinStories object is defined and contains globalScript
  • ✅ JOIN_STORIES_READY event is triggered (see Events documentation)
  • ✅ Automatic detection confirmed in JOIN Stories Studio Installation page

2. Checkout Tracking Validation

2.1 Implementation Method

Checkout tracking uses the window.JoinStories.sendCartValidated() method. For detailed implementation, see Conversion Code documentation.

2.2 Validation Process

Step 1: Manual Test on Confirmation Page

  1. Complete a test purchase transaction
  2. Navigate to the confirmation/thank you page
  3. Open DevTools Console tab
  4. Verify absence of JavaScript errors (see section 5.2)

Step 2: Data Verification Test
Execute the following test in the DevTools Console ⚠️ It will trigger an event in your Analytics ⚠️:

// Test the conversion tracking function
window.JoinStories.sendCartValidated({
    transaction_id: 'TEST-12345',
    total_base_amount: 100.0,
    total_final_amount: 85.0,
    currency: 'EUR',
    products: [
        {
            product_id: 'PROD-001',
            product_variant: 'RED-L',
            product_price: 50.0,
            product_base_price: 50.0,
            product_final_price: 42.5,
            product_quantity: 2,
            currency: 'EUR',
        },
    ],
});

Step 3: Network Request Verification

  1. Open DevTools Network tab
  2. Look for requests to JOIN Stories Analytics endpoints (e.g. https://api.stories.studio/meas/ or your configured analytics URL)
  3. Verify the payload structure matches the Conversion Code documentation. For example, ensure there are products and total_base_amount has the correct value.

2.3 Success Indicators

  • ✅ sendCartValidated function executes without errors
  • ✅ Data is correctly formatted and sent
  • ✅ Network request successfully reaches JOIN Stories endpoints
  • ✅ Automatic detection confirmed in JOIN Stories Studio Installation page

3. Add to Cart Tracking Validation

3.1 Implementation Method

Add to cart tracking uses the window.JoinStories.sendProductAddToCart() method. For detailed implementation, see Conversion Code documentation.

3.2 Validation Process

Step 1: Functional Test

  1. Navigate to a product page
  2. Click the "Add to cart" button
  3. Open DevTools Console tab
  4. Verify absence of JavaScript errors (see section 5.2)

Step 2: Data Verification Test
Execute the following test in the DevTools Console:

// Test the add to cart tracking function
window.JoinStories.sendProductAddToCart({
    product_id: 'PROD-TEST',
    product_variant: 'BLUE-M',
    product_price: 29.99,
    product_base_price: 34.99,
    product_final_price: 29.99,
    product_quantity: 1,
    currency: 'EUR',
});

Step 3: Network Request Verification

  1. Open DevTools Network tab
  2. Filter by XHR/Fetch requests
  3. Look for requests to JOIN Stories Analytics endpoints (e.g. https://api.stories.studio/meas/ or your configured analytics URL)
  4. Verify the payload structure matches the Conversion Code documentation

3.3 Success Indicators

  • ✅ sendProductAddToCart function executes without errors
  • ✅ Function triggers correctly when adding products to cart
  • ✅ Product data is accurately transmitted
  • ✅ Automatic detection confirmed in JOIN Stories Studio Installation page

4. Stories Add to Cart Validation

4.1 Technical Prerequisites

Required Integration Components:

Stories Configuration Requirements:

  • Products connected via Google Merchant Center
  • Shopping interaction configured in Story builder
  • CTA type configured in "Add to cart" mode

4.2 Validation Process

Step 1: Visual Functionality Test

  1. Open a Story containing products
  2. Verify the "Add to cart" button is visible
  3. Click the button
  4. Confirm the action executes correctly

Step 2: Technical Integration Test

  1. Open DevTools before interacting with the Story
  2. Click "Add to cart" button in the Story
  3. Monitor network calls in the Network tab
  4. Verify the product is effectively added to the site's cart
  5. Verify absence of JavaScript errors in the Console (see section 5.2)

4.3 Success Indicators

  • ✅ "Add to cart" button is visible in Stories
  • ✅ Button click functions without JavaScript errors
  • ✅ Product is successfully added to the website's cart
  • ✅ Product data synchronization works correctly

5. Debugging and Troubleshooting

5.1 Debugging Console Commands

Check JOIN Stories Availability:

console.log('JOIN Stories available:', !!window.joinStories);

Monitor Loading State:

document.addEventListener('JOIN_STORIES_READY', () => {
    console.log('JOIN Stories ready and initialized!');
});

Listen to Analytics Events:

Use document (not window) to listen for JOIN Stories custom events:

document.addEventListener('JOIN_ANALYTICS', (event) => {
    console.log('JOIN Stories analytics event:', event.detail);
});

5.2 Verify Absence of JavaScript Errors

When the guide asks to "verify absence of JavaScript errors", follow this process so that integration and analytics payload issues are not missed.

Where to look

  1. Open DevTools (F12) and go to the Console tab.
  2. Leave the Console open while you perform the action (e.g. load the confirmation page, click add to cart, or run the test snippet).
  3. Check for red error messages. Warnings (yellow) are less critical but worth noting.

Errors caused by analytics payload validation

The conversion and add-to-cart methods validate the payload shape before sending events to JOIN Stories Analytics. If the payload does not match the expected structure, the validation layer throws and the event is not sent. You will see a JavaScript error in the Console instead of a successful network request.

  • When it happens: Right after calling window.JoinStories.sendCartValidated(...) or window.JoinStories.sendProductAddToCart(...) (or when your page does so on load, e.g. on the thank-you page).
  • Typical causes and messages:
    • Missing required field: Decoder may throw about a missing key (e.g. currency, product_id, products, total_base_amount, total_final_amount).
    • Wrong type for a number field: "Value must be either a string or a number." — numeric fields accept both number and string (e.g. 100 or "100"). Other types (e.g. object, null for required fields) will fail.
    • Invalid number: "Value must return a valid number when parsed with parseFloat." — e.g. a string that is not a number.
    • Empty products array (sendCartValidated only): "Array must contain at least one element." — products must have at least one item.
  • What to do: Ensure the payload matches the Conversion Code documentation: correct property names, required fields present, and types (number/string for amounts and quantities, string for currency and ids). Fix the payload in your integration and re-test; the error should disappear and a request to the analytics endpoint should appear in the Network tab.

Quick checklist

  • No red errors in the Console when the action is performed.
  • If you see an error right after a conversion or add-to-cart call, treat it as a payload/DTO issue first and validate the payload structure.

5.3 Validation Checklist

Use this comprehensive checklist to verify your installation:

  • Global script loads successfully and window.joinStories is defined
  • JOIN_STORIES_READY event is triggered on page load
  • Checkout page: sendCartValidated function works correctly
  • Product pages: sendProductAddToCart function works correctly
  • Stories: "Add to cart" buttons are functional
  • Automatic detection confirmed in JOIN Stories Studio Installation page
  • No JavaScript errors appear in the console (see 5.2 Verify absence of JavaScript errors)
  • Network requests to JOIN Stories endpoints are successful. Ensure they are not blocked by your ad blocker extension.

6. Common Issues and Solutions

6.1 Global Script Loading Issues

Symptoms: window.joinStories is undefined

Solutions:

  • Verify the domain URL in the script tag
  • Check network connectivity and firewall settings
  • Review Content Security Policy (CSP) configurations
  • Ensure script is placed in the <head> section

6.2 Conversion Tracking Issues

Symptoms: Checkout conversions are not recorded

Solutions:

  • Verify script placement on the confirmation page
  • Ensure data placeholders are replaced with actual values
  • Validate product data structure matches documentation
  • Check browser console for JavaScript errors (including payload validation errors)
  • Confirm the page URL matches your configured thank you page

Symptoms: Events are properly sent but my Analytics page reports 0 revenue

Solutions:

  • Verify the list of products is not empty
  • Verify total_base_amount and total_final_amount have the correct value

6.3 Add to Cart Tracking Issues

Symptoms: Add to cart events are not tracked

Solutions:

  • Verify script integration on product and cart pages
  • Validate product data structure (see Conversion Code documentation and payload validation)
  • Check for JavaScript errors in the console
  • Ensure the function is called after the global script loads (e.g. after JOIN_STORIES_READY or JOIN_ANALYTICS_READY)

6.4 Stories Add to Cart Issues

Symptoms: When clicking add to cart, it redirects to the product page instead of adding the product to the cart

Solutions:

  • Verify Google Merchant Center connection in JOIN Stories Studio (See "Shopping" tab in your settings)
  • In the Shopping interaction, make sure CTA type is configured as "Add to cart"

Symptoms: Add to cart buttons in Stories don't work / do nothing when clicked

Solutions:

  • Verify Google Merchant Center connection in JOIN Stories Studio (See "Shopping" tab in your settings)
  • Confirm your Story includes a "Shopping" interaction module
  • Check that CTA type is configured as "Add to cart"
  • Ensure product IDs match between your site and Google Merchant Center
  • Verify callback functions are properly implemented. See Add to cart : Plug stories add-to-cart to my website

7. Support and Resources

For additional assistance:

If issues persist after following this guide, contact JOIN Stories technical support with:

  • Your team ID
  • Specific error messages from the browser console
  • Screenshots of the Network tab showing failed requests
  • Details about your current implementation

Updated 14 days ago