Installation

Step 1: Install Saltfish

Method 1: NPM Library (Recommended)

Install the Saltfish Player as an npm package for better dependency management and easier integration with modern JavaScript applications.

npm install saltfish

Then import and use it in your application:

import saltfish from 'saltfish';

// Basic initialization
saltfish.init('YOUR_UNIQUE_API_TOKEN');

// Initialization with options
saltfish.init({
  token: 'YOUR_UNIQUE_API_TOKEN',
  sessionRecording: false // Enable detailed session recording. Default: false
});

Method 2: CDN Script Tag

Include the provided Saltfish Player JavaScript file in your website's HTML, typically before the closing </body> tag.

<script src="https://storage.saltfish.ai/player/player.js"></script>

Step 2: Initialize the Player

In your application's JavaScript, initialize the player using your unique API token. This should typically happen once when your application loads.

// Basic initialization
saltfish.init('YOUR_UNIQUE_API_TOKEN');

// Initialization with options
saltfish.init({
  token: 'YOUR_UNIQUE_API_TOKEN',
  persistence: true, // Remember user progress between visits. Default: false
  sessionRecording: false // Enable detailed session recording. Default: false

Step 3: Identify Your Users (Optional)

To track individual user progress and leverage analytics effectively, identify users when they log in or their identity becomes known.

// Example: Identify user after login
function handleUserLogin(userId, userData) {
  saltfish.identify(userId, userData); // e.g., { email: '[e-mail]', name: 'Jane Doe' }
}

Step 4: Launching Guided Tours (Playlists)

Trigger specific playlists based on user behavior, page visits, or specific events in your application.

// Example: Start onboarding tour for new users on their first visit to the dashboard
if (isNewUser && isOnDashboardPage) {
  saltfish.startPlaylist('new_user_onboarding_v1'); // Use the ID of your designed playlist
}

// Example: Launch a feature tour when a user clicks a "Learn More" button
document.getElementById('learn-feature-x').addEventListener('click', () => {
  saltfish.startPlaylist('feature_x_detailed_guide', {
    position: 'bottom-left' // Optionally override default position
  });
});

// Example: Show a playlist only once per user (requires identify() to be called first)
if (userHasBeenIdentified) {
  saltfish.startPlaylist('important_announcement_v1', {
    once: true // User will only see this playlist once, even on subsequent visits
  });
}

4. Tracking Success: Events & Analytics

Saltfish Player emits events that your application can listen to, allowing you to track engagement or trigger other actions.

// Example: Track playlist completion in your analytics tool
saltfish.on('playlistEnded', (event) => {
  console.log(`Playlist ${event.playlist.id} completed by user.`);
  // Send data to your analytics platform
  analytics.track('Saltfish Playlist Completed', { playlistId: event.playlist.id });
});

// Example: Log when a specific step starts
saltfish.on('stepStarted', (event) => {
  console.log(`User started step: ${event.step.id}`);
});

• playlistStarted: Fired when a playlist begins playing for the first time.

• playlistEnded: Fired when a playlist is fully completed.

• stepStarted: Fired when an individual step within a playlist begins playing.

• stepEnded: Fired when an individual step within a playlist ends (either by completing or transitioning away).

• playerPaused: Fired when the player transitions from a playing state to a paused state.

• playerResumed: Fired when the player transitions from a paused state back to a playing state.

• playerMinimized: Fired when the user minimizes the player interface.

• playerMaximized: Fired when the user maximizes the player interface from a minimized state.

Content Security Policy (CSP) Configuration

To ensure Saltfish Player works properly with your website's Content Security Policy, add the following directives to your CSP header:

Required CSP Directives

connect-src (API calls)

connect-src 'self' https://*.saltfish.ai

media-src (videos/audio)

media-src https://*.saltfish.ai

Key API Summary for Your Developers

• saltfish.init(tokenOrConfig): Initializes the player.

• saltfish.identify(userId, userData): Associates player usage with a specific user.

• saltfish.startPlaylist(playlistId, options): Launches a specific guided tour.

• saltfish.on(eventName, callback): Listens for player events.

• saltfish.off(eventName, callback): Stops listening for events.

• saltfish.destroy(): Shuts down the player and cleans up resources.