Launcher

The Hopscotch launcher is a floating help menu you can add to your app so users can quickly discover tours, announcements, chat, and other in-app actions.

What is the launcher?

The launcher is an optional widget that opens a menu of items you configure in Hopscotch.

Common use cases:

• Launch onboarding tours on demand
• Link to docs or support pages
• Show announcements and announcement feeds
• Open chat from your app
• Trigger custom app actions

Configure your launcher

1. Go to your launcher settings in Hopscotch.
2. Enable the launcher.
3. Set position and appearance.
4. Add one or more menu groups.
5. Add menu items to each group.

Menu item types

You can add different item types in the menu builder:

• Tour: Start a product tour
• Survey: Open a survey
• Custom link: Open a URL
• Chat: Open your configured chat provider
• Announcement feed: Show recent messages from a feed
• Announcement: Link to a specific announcement
• Custom JavaScript: Trigger a custom action in your app

Custom actions

Custom actions let you add a launcher button that triggers your own app logic.

A custom action includes:

• A required button label
• Optional inline JavaScript
• A unique itemId

Add a custom action

1. Open launcher Menu builder.
2. Click Add item.
3. Choose Custom JavaScript.
4. Enter a button label.
5. Optionally add JavaScript code.
6. Save.

Click event: hopscotch:executeCustomAction

When a custom action is clicked, Hopscotch dispatches a cancellable browser event:

window.addEventListener("hopscotch:executeCustomAction", (event) => {
  const { itemId, code } = event.detail
  console.log("Launcher action clicked", { itemId, code })
})

Event details:

If inline code exists, Hopscotch runs it after dispatching this event. Call event.preventDefault() to stop default code execution.

window.addEventListener("hopscotch:executeCustomAction", (event) => {
  const { itemId } = event.detail

  if (itemId === 123) {
    event.preventDefault()
    openSupportWidget()
  }
})

Recommended pattern

For most teams:

1. Keep inline code empty.
2. Handle all action logic in app code.
3. Route behavior by itemId.

This keeps launcher behavior versioned and testable in your codebase.

Security guidance

Custom JavaScript runs in your app's browser context. Use caution:

• Prefer event-listener handling over inline snippets
• Keep inline code minimal when used
• Never include secrets or tokens in action code
• Validate any external input used by handlers