OutOfTheBlue Pulse Node.js SDK

Introduction

The OutOfTheBlue Pulse Node.js SDK enables third-party analytics for Shopify stores with a headless setup, featuring advanced session management and cross-platform e-commerce support.

Purpose

For headless Shopify stores, the standard Shopify App Pixel cannot be used to gather customer events. This SDK bridges that gap by enabling the collection of standard customer events in headless setups with comprehensive session tracking and multi-platform support.

Key Features

• Comprehensive Event Collection: Supports all standard customer events as defined in the Shopify Web Pixels API documentation
• Advanced Session Management: Industry-standard session handling with privacy compliance (GDPR, CCPA)
• Multi-Platform Support: Automatic detection and integration with Shopify, BigCommerce, WooCommerce, Magento, and generic platforms
• Cross-Tab Session Consistency: Maintains session state across browser tabs and windows
• Privacy-Compliant Tracking: Secure user identification without compromising privacy
• Automatic Activity Tracking: Session refresh based on user interactions
• Designed specifically for headless e-commerce store architecture
• Seamless integration with Node.js-based frontend applications

Getting Started

To begin using the OutOfTheBlue Pulse Node.js SDK, refer to our installation and setup guide in the following sections.

Installation

Install @out-of-the-blue-ai/pulse with npm

npm i @out-of-the-blue-ai/pulse --save

OutOfTheBlue Pulse Integration Guide

Usage/Examples

There are two ways to push standard customer events to OutOfTheBlue Pulse:

• Using Hydrogen Analytics UI SDK
• Placing Pulse SDK in onClick() handlers (Coming Soon)

Supported Events

The SDK supports the following standard e-commerce events:

• alert_displayed
• cart_viewed
• checkout_address_info_submitted
• checkout_completed
• checkout_contact_info_submitted
• checkout_shipping_info_submitted
• checkout_started
• collection_viewed
• page_viewed
• payment_info_submitted
• product_added_to_cart
• product_removed_from_cart
• product_viewed
• search_submitted
• ui_extension_errored

1. Using Hydrogen Analytics UI SDK

If the Hydrogen Analytics SDK is already installed in your frontend repository, integrating our SDK becomes much easier.

Step 1: Understand Hydrogen Analytics

Refer to the Hydrogen Analytics documentation for background information.

Step 2: Add Event Subscriptions

In the useEffect() hook, add subscriptions for all the standard customer events.

Step 3: Implement Pulse SDK

Here's how to integrate the Pulse SDK:

import { useAnalytics } from '@shopify/hydrogen';
import { useEffect } from 'react';
import { pulsePush } from "@out-of-the-blue-ai/pulse";

export function ThirdPartyAnalyticsIntegration() {
  const { subscribe } = useAnalytics();
  const { ready } = register('Third Party Analytics Integration');

  useEffect(() => {
    // Subscribe to all standard customer events
    const events = [
      'alert_displayed',
      'cart_viewed',
      'checkout_address_info_submitted',
      'checkout_completed',
      'checkout_contact_info_submitted',
      'checkout_shipping_info_submitted',
      'checkout_started',
      'collection_viewed',
      'page_viewed',
      'payment_info_submitted',
      'product_added_to_cart',
      'product_removed_from_cart',
      'product_viewed',
      'search_submitted',
      'ui_extension_errored'
    ];

    events.forEach(event => {
      subscribe(event, (data) => {
        pulsePush(event, data, "customer_event");
      });
    });

    // Mark this analytics integration as ready
    ready();
  }, []);

  return null;
}

Advanced Features

Session Management

The SDK automatically handles session management with the following features:

• Automatic Session Creation: Creates unique session IDs for tracking user journeys
• Session Persistence: Maintains sessions across page reloads and tab switches
• Platform Detection: Automatically detects and integrates with your e-commerce platform
• Privacy Compliance: Follows GDPR and CCPA guidelines for user tracking

Event Payload Structure

Each event sent to OutOfTheBlue Pulse includes comprehensive context:

{
  event_type: "customer_event",
  event_name: "product_viewed",
  event_details: { /* your event data */ },
  shop: "your-store.myshopify.com",
  user_agent: "Mozilla/5.0...",
  event_timestamp: "2024-01-01T12:00:00.000Z",
  page_url: "https://your-store.com/products/example",
  event_source: "pulse_sdk",
  session_id: "unique-session-id",
  user_id: "unique-user-id",
  platform: "shopify",
  platform_session: "platform-specific-session-id",
  is_new_session: false
}

Manual Session Management

For advanced use cases, you can manually control sessions:

import { sessionManagerAPI } from "@out-of-the-blue-ai/pulse";

// Get current session information
const sessionInfo = sessionManagerAPI.getSessionInfo();

// Set a user ID for authenticated users
sessionManagerAPI.setUserId("user123");

// Start a new session manually
sessionManagerAPI.startNewSession();

// Refresh the current session
sessionManagerAPI.refreshSession();

2. Direct Event Tracking

You can also use the SDK directly without Hydrogen Analytics:

import { pulsePush } from "@out-of-the-blue-ai/pulse";

// Track a page view
pulsePush("page_viewed", {
  page_title: "Home Page",
  page_type: "home"
}, "customer_event");

// Track a product view
pulsePush("product_viewed", {
  product_id: "123",
  product_title: "Example Product",
  product_price: 29.99,
  product_vendor: "Example Vendor"
}, "customer_event");

// Track add to cart
pulsePush("product_added_to_cart", {
  product_id: "123",
  quantity: 1,
  variant_id: "456"
}, "customer_event");

Error Handling

The SDK includes built-in error handling and validation:

• Event Type Validation: Ensures only valid event types are accepted
• Event Name Validation: Validates event names against supported standards
• Network Error Handling: Gracefully handles network failures
• Privacy Protection: Automatically handles cases where cookies or localStorage are unavailable

Best Practices

1. Complete Event Tracking: Subscribe to all standard customer events to ensure comprehensive analytics coverage
2. User Privacy: The SDK automatically handles privacy compliance, but ensure your usage aligns with your privacy policy
3. Performance: The SDK is optimized for performance with minimal impact on page load times
4. Testing: Test your integration in development before deploying to production

Debugging

For development and debugging purposes, you can access session information:

// In development environments, access debug information
if (window._OTBSessionDebug) {
  console.log("Current session:", window._OTBSessionDebug.getSessionInfo());
}

// Access the session manager API globally
if (window.OTBSessionManager) {
  console.log("Session ID:", window.OTBSessionManager.getSessionId());
}

Need Help?

If you encounter any issues or have questions, please refer to our documentation or contact our support team at [email protected].