Skip to main content

Connecting your Website to Surfside Analytics

The following sections describe how to integrate your website with Surfside Analytics to track ecommerce events. There are two ways to integrate your side: either with the Surfside Browser SDK or with the Surfside Node SDK.

0. Prerequisites​

Before getting started, please review the following guides:

  • The Surfside Analytics Tag: Learn about the Analytics Tag, its purpose, and the data it captures.
  • Ecommerce Events: Understand the types of ecommerce events, their associated data types, and key actions. This guide will help you identify required attributes and how to track as much data as possible.

The Surfside Inspector Chrome Extension​

The Surfside Inspector Chrome Extension is a powerful tool that allows you to inspect and debug Surfside Analytics events directly in your browser. It provides real-time feedback on the events being sent to Surfside, helping you verify that your tracking is working as expected.

How to Use

  • Install the Surfside Inspector Chrome Extension

  • Open your website in Chrome, launch the Chrome Developer Tools, and navigate to the Surfside tab to view events as they are sent.

Step 1

  • As you implement the Surfside Analytics Tag and ecommerce events, use the Inspector to confirm that events are dispatched correctly. Focus on the Ecommerce Event rows, which correspond to your tracked ecommerce actions.

Step 2

  • While navigating through your website and performing ecommerce actions, you should see these events appear in the Inspector. If you do not see the events, double-check your implementation to ensure it is correct.

  • Verify events using the Events QA Auditor. Click the “Events QA Auditor” in the extension toolbar to view each triggered event along with its associated attributes. This tool provides a structured overview of ecommerce activity, helping ensure that implementations are firing as expected.

  • Identify missing or incorrectly implemented attributes. Each event type is reviewed for required attributes—if all are present, a ✅ checkmark is shown; if not, a ⛔️ red icon indicates what’s missing or incorrect.

Step 3 Step 4

  • On the main page, to view full details about any event, click the event row to expand the event details. This will show all attributes and values associated with the event.

Step 5

Choosing the right SDK​

At this point, you have learned about the Surfside Analytics Tag, the edge.js library, what user interactions to track on your website. Now, it's time to integrate Surfside Analytics to track both website and ecommerce events.

  1. Surfside Browser SDK
    • The Surfside Browser SDK is a lightweight JavaScript library that allows you to track events on your website using the surf() command. We recommend this option if you are working with a static sites, client-side web applications, or lightweight projects using vanilla JS.
  2. Surfside Node SDK: This is a Node.js library that allows you to track events on your website using the @surfside npm packages. We recommend this option if you are working with modern web frameworks like React.js or Next.js.

Choose the SDK that best aligns with your website’s architecture and tracking needs, and carefully follow the instructions in the following sections to ensure a seamless and accurate integration. Don't hesitate to Contact Support if you need assistance.

1. Load Surfside Analytics​

To load the Surfside Analytics plugin, use the following code snippet:

accountId and sourceId are both provided by your Surfside representative

[[Unique Location ID]] is a unique identifier, such as a Store or Retail Id.

<!-- Surfside Analytics -->
<script>
  ;(function(s,u,r,f,i,n,g){if(!s[i]){s.surfContext=s.surfContext||[];
  s.surfContext.push(i);s[i]=function(){(s[i].q=s[i].q||[]).push(arguments)
  };s[i].q=s[i].q||[];n=u.createElement(r);g=u.getElementsByTagName(r)[0];n.async=1;
  n.src=f;g.parentNode.insertBefore(n,g)}}(window,document,"script","//cdn.surfside.io/sdk/1.0.0/edge.js","surf"));
  
  // Initialize Surfside Analytics
  surf('newTracker', 'digital', '//col.surfside.io', {
      appId: 'digital',
      cookieName: 'surf',
      discoverRootDomain: true,
      cookieSameSite: 'Lax',
  });
  
  // Set the accountId and sourceId
  surf('source:digital', {
      accountId: 'XXXXX', // Your account ID
      sourceId: 'XXXXX', // Your source ID
  });
  
  // Do not include these lines if you are a multi-location business
  surf('setLocation:digital', {
      id: '[[Unique Location ID]]',
      ... // other location values, see below
  });
  
  // Enable activity tracking
  surf('enableActivityTracking', {
      minimumVisitLength: 30,
      heartbeatDelay: 10,
  });
  
  // Enable link click tracking
  surf('enableLinkClickTracking')
  
  // Track a page view
  surf('trackPageView')
</script>
<!-- End Surfside Analytics -->

Once the tracker object is created, you can leverage the following e-commerce tracking features to capture key user interactions.

2. Tracking Location​

To associate a physical location with your event, use setLocation() to specify the event's location. Location values help identify unique sites that may be part of larger accounts or sources (e.g., a store ID for a retail chain with multiple locations).

For multi-location clients, dynamically update the setLocation() method by changing the id and other relevant fields whenever a user selects a new location. This can be triggered by events like selecting a different store from a dropdown menu.

Note: The setLocation() event does not need to be fired for each ecommerce event. It only needs to be set once per session or when the user changes locations.

setLocation() can contain any of the following values to distinguish a unique location event:

KeyValue TypeRequiredDescription
idtextYESThe unique identifier, such as a Store or Retail ID.
latitudetextNoThe location latitude.
longitudetextNoThe location longitude.
country_codetextNoThe country code associated with the location.
ziptextNoThe zip code associated with the location.
state_labeltextNoThe state label associated with the location.
statetextNoThe state associated with the location.
citytextNoThe city associated with the location.
streettextNoThe street associated with the location.
nametextNoThe name associated with the location.
parenttextNoThe parent location associated with the location.
typetextNoThe type associated with the location.
categorytextNoThe category associated with the location.
<script>
  surf('setLocation', {
    id: location.id, // Store or Retail ID
    latitude: location.latitude,
    longitude: location.longitude,
    country_code: location.country_code,
    zip: location.zip,
    state_label: location.state_label,
    state: location.state,
    city: location.city,
    street: location.street,
    name: location.name,
    parent: location.parent,
    type: location.type,
    category: location.category,
  });
</script>

3. Measuring Ecommerce Actions​

Product Detail​

This event is triggered when a user views a product detail page on your website. It should only be fired once per product detail page view.

Note If a user navigates to a different product detail page, this event should be fired again with the details of the new product.

<script>
  surf('addProduct:digital', {
    id: item.id, // The ID
    name: item.name, // The name (string)
    list: item.list, // The list (string)
    brand: item.brand, // The brand (string)
    category: item.category, // The category (string)
    variant: item.variant, // The variant (string)
    price: item.price, // The price (number)
    quantity: item.quantity, //  For product detail views, this should always be 1
    coupon: item.coupon, // The coupon (number)
    position: item.position, // The position (number)
    currency: item.currency, // The currency (string)
  });

  surf('setCommerceAction:digital',
    'detail' // Product Detail Action
  );
</script>

Add to Cart​

This event should be fired when a user successfully adds an item to their cart.

<script>
  surf('addProduct:digital', {
    id: item.id,
    name: item.name,
    list: item.list,
    brand: item.brand,
    category: item.category,
    variant: item.variant,
    price: item.price,
    quantity: item.quantity, // The quantity of the product added to the cart
    coupon: item.coupon,
    position: item.position,
    currency: item.currency,
  });

  surf('setCommerceAction:digital',
    'add' // Add to Cart Action
  );
</script>

Remove from Cart​

Similar to the Add to Cart event, this event should be fired when a user successfully removes an item from their cart.

<script>
  surf('addProduct:digital', {
    id: item.id,
    name: item.name,
    list: item.list,
    brand: item.brand,
    category: item.category,
    variant: item.variant,
    price: item.price,
    quantity: item.quantity, // The quantity of the product removed from the cart
    coupon: item.coupon,
    position: item.position,
    currency: item.currency,
  });

  surf('setCommerceAction:digital',
    'remove' // Remove from Cart Action
  );
</script>

Checkout​

This event occurs when a user initiates the checkout process.

  1. Add the transaction data for the checkout. This includes the transaction ID, revenue, tax, shipping, and other details.
  2. Add the product(s) included in the checkout.
  3. Set the commerce action to checkout.

Note: If the id of the order is not know at the time of the checkout event, it does not need to be set. However, it is required for the purchase and refund events.

<script>
  // The transaction data for the checkout
  surf('addTransaction:digital', {
    id: 'TRX-7890', // Transaction ID
    affiliation: 'Nike Online Store', // Transaction Affiliation
    revenue: 239.97, // Transaction Revenue
    tax: 19.20, // Transaction Tax
    shipping: 5.99, // Transaction Shipping
    coupon: 'SUMMER2024', // Transaction Coupon
    list: 'Shopping Cart', // Transaction List
    step: 1, // Transaction Step
    option: 'Visa', // Transaction Option
    currency: 'USD', // Transaction Currency
  });

  // The product(s) included in checkout
  surf('addProduct:digital', {
    id: '12345',
    name: 'Awesome Sneakers',
    list: 'Shopping Cart',
    brand: 'Nike',
    category: 'Footwear',
    variant: 'Red Size 11',
    price: 79.99,
    coupon: 'SUMMER2024',
    position: 1,
    quantity: 3 // The quantity of the product in the cart at the time of checkout
    currency: 'USD'
  });

  surf('setCommerceAction:digital',
    'checkout' // Checkout Action
  );
</script>

Purchase​

Very similar to the checkout event, this event occurs when a user completes a purchase.

  1. Add the transaction data for the purchase. This includes the transaction ID, revenue, tax, shipping, and other details.
  2. Add the product(s) included in the purchase.
  3. Set the commerce action to purchase.
<script>
  // The transaction data for the purchase
  surf('addTransaction:digital', {
     id: 'TRX-7890',
     affiliation: 'Nike Online Store',
     revenue: 239.97,
     tax: 19.20,
     shipping: 5.99,
     coupon: 'SUMMER2024',
     list: 'Shopping Cart',
     step: 1,
     option: 'Visa',
     currency: 'USD',
  });

  // The product(s) included in purchase
  surf('addProduct:digital', {
    id: '12345',
    name: 'Awesome Sneakers',
    list: 'Shopping Cart',
    brand: 'Nike',
    category: 'Footwear',
    variant: 'Red Size 11',
    price: 79.99,
    coupon: 'SUMMER2024',
    position: 1,
    quantity: 3 // The quantity of the product the user purchased
    currency: 'USD'
  });

  surf('setCommerceAction:digital',
    'purchase' // Purchase Action
  );
</script>

Measuring Refunds (Optional)​

To refund an entire transaction, set a refund action and provide the transaction ID:

<script>
  // The transaction data for the refund
  surf('addTransaction:digital', {
    id: orderId, // Transaction ID
  });
  // Refund an entire transaction
  surf('setCommerceAction:digital', 'refund');
</script>

To measure a partial refund, set a refund action and specify the transaction ID, product ID(s), and product quantities to be refunded:

<script>
  // The transaction data for the refund
  surf('addTransaction:digital', {
    id: orderId,
    affiliation: affiliation,
    revenue: revenue,
    tax: tax,
    shipping: shipping,
    coupon: coupon,
    list: list,
    step: step,
    option: option,
    currency: currency,
  });

  // The product(s) being refunded
  surf('addProduct:digital', {
    id: item.id,
    name: item.name,
    list: item.list,
    brand: item.brand,
    category: item.category,
    variant: item.variant,
    price: item.price,
    quantity: item.quantity,
    coupon: item.coupon,
    position: item.position,
    currency: item.currency,
  });

  surf('setCommerceAction:digital',
    'refund' // Refund Action
  );
</script>

4. Measuring Impressions (Optional)​

Product impressions are measured using the addImpression command.

Note: An impression must have a name or id value. All other values are optional and don't need to be set.

<script>
  surf('addImpression:digital', {
    id: item.id,
    name: item.name
    list: item.list
    brand: item.brand
    category: item.category
    variant: item.varian
    price: item.price
    quantity: item.quantity
    coupon: item.coupon
    position: item.position
    currency: item.currency
  });
</script>

An impressionFieldObject must have a name or id value. All other values are optional and don't need to be set.

Combining Impressions and Actions​

In cases where you have both product impressions and an action, it is possible to combine and measure this in a single hit.

Note: No events are fired until the setCommerceAction function is called which is used to associate any specific addImpression or addProduct events to the

<script>
  surf('addImpression:digital', {
    id: item.id,
    name: item.name,
    list: item.list,
    brand: item.brand,
    category: item.category,
    variant: item.variant,
    price: item.price,
    quantity: item.quantity,
    coupon: item.coupon,
    position: item.position,
    currency: item.currency,
  });

  // The product in focus that was clicked on / viewed in detail
  surf('addProduct:digital', {
    id: item.id,
    name: item.name,
    list: ',
    brand: item.brand,
    category: item.category,
    variant: item.variant,
    price: item.price,
    quantity: item.quantity,
    coupon: item.coupon,
    position: item.position,
    currency: item.currency,
  });

  surf('setCommerceAction:digital',
    'detail' // View Product Action
  );
</script>

Contact Support​

If you need assistance with integration or have any questions, please contact our technical support team: