Installation

Step 1: Add the Saltfish Player Script

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.

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.