Snippet API Reference

Control tours programmatically using the global tours() function. Available after the AppPiper snippet loads.

Core Functions

tours('init', orgId)

Initialize AppPiper with your organization ID. Called automatically if the snippet is loaded, but can be called manually.

Example:

tours('init', 'org_abc123def456');

tours('start', tourId)

Start a specific tour by ID. If a tour is already running, it will be stopped first.

Example:

tours('start', 'tour_onboarding');

tours('next')

Navigate to the next step in the current tour.

Example:

tours('next');

tours('prev')

Navigate to the previous step in the current tour.

Example:

tours('prev');

tours('stop')

Dismiss the current tour and clean up.

Example:

tours('stop');

tours('goTo', stepIndex)

Jump to a specific step (0-indexed).

Example:

tours('goTo', 2); // Jump to the 3rd step

Customization

tours('theme', config)

Customize the appearance of tour tooltips.

Available options:

tours('theme', {
  primaryColor: '#3b82f6',        // Hex color for buttons
  textColor: '#ffffff',           // Tooltip text color
  backgroundColor: '#1f2937',     // Tooltip background
  borderRadius: '8px',            // Border radius
  shadowColor: 'rgba(0,0,0,0.2)', // Shadow color
  fontFamily: 'Inter, sans-serif',
  fontSize: '14px'
});

Events & Callbacks

tours('on', event, callback)

Example:

tours('on', 'ready', function() {
  console.log('AppPiper is ready!');
});

tours('on', 'start', function(tourId) {
  console.log('Tour started:', tourId);
});

tours('on', 'complete', function(tourId) {
  console.log('User completed tour:', tourId);
});

tours('off', event, callback)

Unregister an event listener.

Example:

const handleComplete = function() {
  console.log('Tour completed!');
};

tours('on', 'complete', handleComplete);

// Later, unregister:
tours('off', 'complete', handleComplete);

Available Events

ready

Fired when AppPiper has loaded and initialized.

start(tourId)

Fired when a tour starts. Passes the tour ID.

step(stepIndex, stepData)

Fired when moving to a new step. Passes the step index and step data.

next()

Fired when the user clicks the next button.

prev()

Fired when the user clicks the previous button.

complete(tourId)

Fired when the user completes all steps. Passes the tour ID.

dismiss(tourId)

Fired when the user dismisses the tour. Passes the tour ID.

error(message)

Fired if an error occurs. Passes the error message.

Advanced Usage

React Integration

'use client';

import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    // Wait for AppPiper to be ready
    window.tours?.('on', 'ready', () => {
      console.log('Ready to start tours');

      // Start a tour when user clicks a button
      document.getElementById('start-tour')?.addEventListener('click', () => {
        window.tours('start', 'tour_welcome');
      });
    });
  }, []);

  return (
    <button id="start-tour">Start Tour</button>
  );
}

SPA Integration (Vue/Angular)

When using SPAs, tours persist across page navigation. Use the ready event to initialize:

// In your main app initialization
window.tours?.('on', 'ready', () => {
  // Tours are now available
  // You can call tours() from anywhere
});

Custom Triggers

Trigger tours based on custom events:

// Show tour on user action
document.getElementById('help-button')?.addEventListener('click', () => {
  window.tours?.('start', 'tour_help');
});

// Show tour after 5 seconds
setTimeout(() => {
  window.tours?.('start', 'tour_feature_intro');
}, 5000);

// Show tour when user visits a page
if (window.location.pathname === '/dashboard') {
  window.tours?.('start', 'tour_dashboard');
}

Checking if AppPiper is Ready

The tours() function might not be available immediately. Always check before using:

if (typeof window.tours === 'function') {
  window.tours('start', 'tour_id');
} else {
  console.log('AppPiper not loaded yet');
}