Guides

Validate your scripts installation

Suggest Edits

Technical Validation Guide - JOIN Stories Scripts Installation

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.

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 200 OK

Step 3: JavaScript Object Verification

  1. Open the DevTools Console
  2. Execute: console.log(window.JoinStories)
  3. Verify the object is defined and contains necessary methods

1.3 Success Indicators

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

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

// Test the conversion tracking function
window.JoinStories.sendCartValidated({
  transaction_id: 'TEST-12345',
  total_base_amount: 100.00,
  total_final_amount: 85.00,
  currency: 'EUR',
  products: [{
    product_id: 'PROD-001',
    product_variant: 'RED-L',
    product_price: 50.00,
    product_base_price: 50.00,
    product_final_price: 42.50,
    product_quantity: 2,
    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 (https://api.dev.stories.studio/meas/)
  4. Verify the payload structure matches the Conversion Code documentation

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

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 (https://api.dev.stories.studio/meas/)
  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

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:

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

5.2 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
  • Network requests to JOIN Stories endpoints are successful

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
  • Confirm the page URL matches your configured thank you page

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
  • Check for JavaScript errors in the console
  • Ensure the function is called after the global script loads

6.4 Stories Add to Cart Issues

Symptoms: Add to cart buttons in Stories don't work

Solutions:

  • Verify Google Merchant Center connection in JOIN Stories Studio
  • 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

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 6 days ago