HelpHero

https://helphero.co/docs
Admin
HelpHero is an interactive product tour and user onboarding platform that enables teams to create,...
Tokens:26,591
Snippets:321
Trust Score:7.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### HelpHero.startTour(tourId, [options])

Source: https://helphero.co/docs/javascript

Starts a tour with the specified tour ID. The tour will only start if the user is on a URL that matches the starting URL match specified in the tour. Options can override default behavior.

```APIDOC
## HelpHero.startTour(tourId, [options])

### Description
Starts a tour with the specified tour ID. The tour will only start if the user is on a URL that matches the starting URL match specified in the tour.

### Method
startTour

### Parameters
- **tourId** (string) - Required - The ID of the tour to start.
- **options** (object) - Optional - An object containing options to override default behavior.
  - **skipIfAlreadySeen** (boolean) - Optional - If true, the tour will only start if the user has NOT already seen the tour.
  - **redirectIfNeeded** (boolean) - Optional - If true, performs a redirect before starting the tour if the current page does not match the starting URL match.
  - **stepId** (string) - Optional - The ID of the step to start the tour from. Defaults to the first step.

### Request Examples
Start tour even if user has already seen tour:

```js
HelpHero.startTour("<TOUR_ID>")
```

Start tour only if user has NOT already seen tour:

```js
HelpHero.startTour("<TOUR_ID>", { skipIfAlreadySeen: true })
```

Perform a redirect before starting the tour:

```js
HelpHero.startTour("<TOUR_ID>", { redirectIfNeeded: true })
```

Start the tour at a later step:

```js
HelpHero.startTour("<TOUR_ID>", { stepId: "<STEP_ID>" })
```
```

--------------------------------

### Successful wildcard matches

Source: https://helphero.co/docs/url-match

Examples of URLs that match the /shop/{*any} pattern.

```txt
https://example.com/shop/
https://example.com/shop/checkout
https://example.com/shop/settings
https://example.com/shop/settings/currency
```

--------------------------------

### HelpHero.startChecklist(checklistId)

Source: https://helphero.co/docs/javascript

Starts a checklist with the specified checklist ID. The checklist will only start if the user is on a matching URL, all conditions are satisfied, and at least one item is eligible.

```APIDOC
## HelpHero.startChecklist(checklistId)

### Description
Starts the checklist with the given checklist ID. The checklist will only start if the user is on a URL that matches the starting URL match, all conditions are satisfied, and at least one checklist item is eligible to be displayed.

### Method
Function call

### Endpoint
HelpHero.startChecklist(checklistId)

### Parameters
#### Path Parameters
- **checklistId** (string) - Required - The ID of the checklist to start.

### Request Example
```js
HelpHero.startChecklist("<CHECKLIST_ID>")
```

### Response
No return value documented.
```

--------------------------------

### HelpHero.startTour with skipIfAlreadySeen

Source: https://helphero.co/docs/javascript

Starts the tour only if the user has not already seen it.

```js
HelpHero.startTour("<TOUR_ID>", { skipIfAlreadySeen: true })
```

--------------------------------

### Start tour with JavaScript API on button click

Source: https://helphero.co/docs/starting-tours

Use the HelpHero JavaScript API to start a tour when a button is clicked. Replace '<TOUR_ID>' with the actual tour ID from the HelpHero Editor. Tours can always be started via the JavaScript API regardless of auto start and on demand settings.

```html
<button type="button" onclick="HelpHero.startTour('<TOUR_ID>')">Start tour</button>
```

--------------------------------

### Successful hash URL match

Source: https://helphero.co/docs/url-match

Example of a URL that matches the /home#admin pattern.

```txt
https://example.com/home#admin
```

--------------------------------

### Successful any domain matches

Source: https://helphero.co/docs/url-match

Examples of URLs that match the /shop/checkout pattern across different domains.

```txt
https://example.com/shop/checkout
https://app.example.com/shop/checkout
https://mysite.com/shop/checkout
```

--------------------------------

### Successful specific domain match

Source: https://helphero.co/docs/url-match

Example of a URL that matches the //www.example.com/shop/checkout pattern.

```txt
https://www.example.com/shop/checkout
```

--------------------------------

### HelpHero.startTour with stepId

Source: https://helphero.co/docs/javascript

Starts the tour at a specific step ID instead of the first step.

```js
HelpHero.startTour("<TOUR_ID>", { stepId: "<STEP_ID>" })
```

--------------------------------

### Successful dynamic URL matches

Source: https://helphero.co/docs/url-match

Examples of URLs that match the /user/{user_id}/profile pattern.

```txt
https://example.com/user/3523/profile
https://example.com/user/2345/profile
https://example.com/user/6345/profile
```

--------------------------------

### Failed wildcard match

Source: https://helphero.co/docs/url-match

Example of a URL that fails to match the /shop/{*any} pattern.

```txt
https://example.com/other/settings
```

--------------------------------

### Absolute Tour Link Example

Source: https://helphero.co/docs/tour-links

The standard format for a HelpHero tour link including the full domain and query parameter.

```txt
https://www.example.com/my_page?helphero_tour=Fv6n43b24
```

--------------------------------

### HelpHero.startTour basic usage

Source: https://helphero.co/docs/javascript

Starts a tour by its ID, ignoring whether the user has already seen it.

```js
HelpHero.startTour("<TOUR_ID>")
```

--------------------------------

### HelpHero.startTour with redirectIfNeeded

Source: https://helphero.co/docs/javascript

Performs a redirect to the tour's starting URL if the current page does not match.

```js
HelpHero.startTour("<TOUR_ID>", { redirectIfNeeded: true })
```

--------------------------------

### Successful optional segment matches

Source: https://helphero.co/docs/url-match

Examples of URLs that match the /settings/{?page} pattern.

```txt
https://example.com/settings
https://example.com/settings/currency
```

--------------------------------

### Successful plus modifier matches

Source: https://helphero.co/docs/url-match

Examples of URLs that match the /shop/{+any} pattern.

```txt
https://example.com/shop/checkout
https://example.com/shop/settings
https://example.com/shop/settings/currency
```

--------------------------------

### Match any domain

Source: https://helphero.co/docs/url-match

Patterns starting with a single slash match against any domain.

```txt
/shop/checkout
```

--------------------------------

### Failed specific domain matches

Source: https://helphero.co/docs/url-match

Examples of URLs that fail to match the //www.example.com/shop/checkout pattern.

```txt
https://app.example.com/shop/checkout
https://mysite.com/shop/checkout
```

--------------------------------

### Failed hash URL match

Source: https://helphero.co/docs/url-match

Example of a URL that fails to match the /home#admin pattern.

```txt
https://example.com/home
```

--------------------------------

### Creating lists with ol and ul

Source: https://helphero.co/docs/html

Create numbered lists with <ol> and bullet points with <ul>. The example shows both list types with sample items.

```html
<p>Sometimes you want numbered lists:</p>

<ol>
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
</ol>

<p>Sometimes you want bullet points:</p>

<ul>
  <li>Start a line with a star</li>
  <li>Profit!</li>
</ul>
```

--------------------------------

### Track a button click with HelpHero.update()

Source: https://helphero.co/docs/funnels/user-events

Example of tracking a button click by passing an object directly to HelpHero.update() instead of a function. This is useful for events not dependent on existing user properties.

```html
<script>
  document.getElementById("cancel").addEventListener("click", function() {
    HelpHero.update({ hasCancelled: true }); 
  });
</script>

<button id="cancel">Cancel</button>
```

--------------------------------

### Links with target attribute

Source: https://helphero.co/docs/html

Create links that open in the same window by default, or use the target attribute to open in a new window/tab. The example shows both a default link and one with target="_blank".

```html
<p>By default links open in the same window eg:<br>

<a href="https://helphero.co">link to HelpHero</a>

<p>If you want your link to open in a new window/tab you can use the target attribute:<br>

<a href="https://helphero.co" target="_blank">link to HelpHero</a>
```

--------------------------------

### Failed dynamic URL match

Source: https://helphero.co/docs/url-match

Example of a URL that fails to match because the variable only covers a single path segment.

```txt
https://example.com/user/admin/2344/profile
```

--------------------------------

### Embedding images

Source: https://helphero.co/docs/html

Embed images in tour steps using the <img> tag. The example shows an image with a source URL, alt text, and dimensions.

```html
<p>If you want to embed images, this is how you do it:</p>

<img src="https://helphero.co/images/logo@2x.png" alt="logo" width="170px" height="40px">
```

--------------------------------

### Failed optional segment match

Source: https://helphero.co/docs/url-match

Example of a URL that fails to match because it contains more than one segment.

```txt
https://example.com/settings/currency/edit
```

--------------------------------

### Relative Tour Link Example

Source: https://helphero.co/docs/tour-links

A modified tour link with the domain removed, allowing it to be relative to the current site where it is embedded.

```txt
/my_page?helphero_tour=Fv6n43b24
```

--------------------------------

### Text formatting with HTML tags

Source: https://helphero.co/docs/html

Use HTML tags like <strong>, <em>, <del>, and <a> to format text in tour steps. The example shows bold, italic, combined, strikethrough, and linked text.

```html
Would you like to make some words <strong>bold</strong> and other words <em>italic</em>.<br>

This will also be <strong>bold</strong> and this will be <em>italic</em>.<br>

<em>You <strong>can</strong> combine them</em> or <del>strike things out</del>.<br>

You can even <a href="https://google.com">link to Google!</a>
```

--------------------------------

### Failed plus modifier match

Source: https://helphero.co/docs/url-match

Example of a URL that fails to match the /shop/{+any} pattern because it requires at least one segment.

```txt
https://example.com/shop/
```

--------------------------------

### Show/hide Intercom launcher during HelpHero tours

Source: https://helphero.co/docs/intercom

Use this script to hide the Intercom launcher when a HelpHero tour starts and show it again when the tour completes, is cancelled, or is interrupted. Adjust the logic as needed for your use case.

```html
<script>
  function showIntercom() {
    window.Intercom('show');
    window.Intercom('update', { hide_default_launcher: false });
  }
  function hideIntercom() {
    window.Intercom('hide');
    window.Intercom('update', { hide_default_launcher: true });
  }
  window.HelpHero.on('tour_started', hideIntercom);
  window.HelpHero.on('tour_completed', showIntercom);
  window.HelpHero.on('tour_cancelled', showIntercom);
  window.HelpHero.on('tour_interrupted', showIntercom);
</script>
```

--------------------------------

### Pass user properties with HelpHero.identify

Source: https://helphero.co/docs/funnels/user-properties

Use the HelpHero.identify method to pass user-specific data, such as isAdmin, to HelpHero. This implementation example uses PHP to dynamically inject the user ID and admin status into the script.

```html
<script>
  HelpHero.identify('<?php echo get_current_user_id(); ?>', {
    isAdmin: <?php echo get_current_user_is_admin() ? 'true' : 'false'; ?>
  }); 
</script>
```

--------------------------------

### HelpHero.update(properties)

Source: https://helphero.co/docs/javascript

Updates user properties and checks if any tours should be auto started based on the new properties. Accepts an object of properties or a function that receives current properties and returns new properties.

```APIDOC
## HelpHero.update(properties)

### Description
Updates the current user's properties and checks if any tours should be auto started based on the new properties.

### Method
update

### Parameters
- **properties** (object or function) - Required - An object of user properties to update, or a function that receives current properties and returns an object of new properties.

### Request Example
```js
HelpHero.update({
  hasPlan: true
});
```

Or pass function to update based on current properties:

```js
HelpHero.update(function(currentProperties) {
  return {
    hasPlan: !currentProperties.hasPlan
  };
});
```
```

--------------------------------

### Track checkout visits with HelpHero.update()

Source: https://helphero.co/docs/funnels/user-events

Add this script to the checkout page after the HelpHero installation scripts. It increments the checkoutVisits user property by 1, starting from 1 if not already set.

```html
<script>
  HelpHero.update(function(user) {
    return { 
      checkoutVisits: user.checkoutVisits ? user.checkoutVisits + 1 : 1
    };
  }); 
</script>
```

--------------------------------

### Match specific domain

Source: https://helphero.co/docs/url-match

Patterns starting with a double slash match only the specified domain.

```txt
//www.example.com/shop/checkout
```

--------------------------------

### HelpHero.advanceTour([options])

Source: https://helphero.co/docs/javascript

Moves the current active tour forward one step. Accepts an optional options object to override default behavior, such as specifying a step ID or relative step count.

```APIDOC
## HelpHero.advanceTour([options])

### Description
Moves the current active tour forward one step. Ignored when the current step is a highlight that requires user interaction.

### Method
Function call

### Endpoint
HelpHero.advanceTour([options])

### Parameters
#### Options (optional)
- **stepId** (string | number) - Optional - Specifies a specific step ID to move to, or a relative number of steps from the current step (e.g., -2 to move back 2 steps).

### Request Example
```js
HelpHero.advanceTour()
HelpHero.advanceTour({ stepId: "<STEP_ID>" })
HelpHero.advanceTour({ stepId: -2 })
```

### Response
No return value documented.
```

--------------------------------

### HelpHero.setOptions(options)

Source: https://helphero.co/docs/javascript

Sets global HelpHero options by passing an object. Options include toggling display of all content, controlling beacon visibility, and customizing navigation behavior.

```APIDOC
## HelpHero.setOptions(options)

### Description
Allows setting HelpHero options by passing an object. Options can control display of all content, beacon visibility, and navigation behavior.

### Method
Function call

### Endpoint
HelpHero.setOptions(options)

### Parameters
#### Options (required)
- **show** (boolean) - Optional - Toggle display of all HelpHero content (tours, hotspots, checklists). Default is true.
- **showBeacon** (boolean) - Optional - Control whether the checklist beacon is visible. Overrides default visibility.
- **navigate** (function) - Optional - Function to handle navigation between pages. Defaults to location.assign if not set.

### Request Example
```js
HelpHero.setOptions({ show: false })
HelpHero.setOptions({ showBeacon: false })
function handleNavigate(url) {
  try {
    history.pushState({}, '', url);
  } catch (err) {
    location.assign(url);
  }
}
HelpHero.setOptions({ navigate: handleNavigate });
```

### Response
No return value documented.
```

--------------------------------

### HelpHero.openChecklist()

Source: https://helphero.co/docs/javascript

Opens the checklist if one is available for the current page.

```APIDOC
## HelpHero.openChecklist()

### Description
Opens the checklist if there is one available for the current page.

### Method
Function call

### Endpoint
HelpHero.openChecklist()

### Parameters
None

### Request Example
```js
HelpHero.openChecklist()
```

### Response
No return value documented.
```

--------------------------------

### HelpHero.on([eventName], listenerFn, [context])

Source: https://helphero.co/docs/javascript

Registers a listener function that will be invoked when tour, checklist, or hotspot events occur. The eventName parameter is optional; if omitted, the listener is called for all events. The listener receives an event object and an info object with details about the event.

```APIDOC
## HelpHero.on([eventName], listenerFn, [context])

### Description
Register a listener function that will be invoked when tour events occur. The eventName is optional; if omitted, the listener is called for all events.

### Method
on

### Parameters
#### Optional Parameters
- **eventName** (string) - Optional - The name of the event to listen for. If omitted, the listener is called for all events.
- **listenerFn** (function) - Required - The function to be invoked when the event occurs. It receives (event, info) arguments.
- **context** (object) - Optional - The context to use as `this` when calling the listener function.

### Event Types
- **tour_started** - A tour has been started either automatically, from a checklist or via the API.
- **tour_completed** - A tour has been completed from start to finish.
- **tour_advanced** - A tour has been advanced to the next step either by the user, by a funnel step or via the API.
- **tour_backtracked** - A tour has backtracked to a previous step either by the user or a funnel step.
- **tour_cancelled** - A tour has been cancelled either by the user or via the API.
- **tour_interrupted** - A tour was interrupted due to user navigating away from the page or because the appropriate element to highlight was not found within the timeout specified.
- **tour_dismissed** - A tour has been dismissed by the user clicking on a special dismiss button.
- **checklist_item_completed** - An item in a checklist has been completed.
- **checklist_completed** - All the items in a checklist have been completed.
- **hotspot_visited** - Hotspot popup was opened by the user.
- **hotspot_dismissed** - A hotspot has been dismissed by the user clicking on a special dismiss button.

### Event and Info Objects
For tour events, the listener receives:
- **event** (Event) - An object with kind (EventKind), tourId (string), stepId (string).
- **info** (Info) - An object with tour (Tour: {id, name}) and step (Step: {id, name}).

For checklist events, the listener receives:
- **event** (Event) - An object with kind (EventKind), checklistId (string), itemId (string or null).�
- **info** (Info) - An object with checklist (Checklist: {id, name, items}) and item (ChecklistItem or null).

For hotspot events, the listener receives:
- **event** (Event) - An object with kind (EventKind), hotspotId (string).
- **info** (Info) - An object with hotspot (Hotspot: {id, name}).

### Examples
Registering a listener for a specific event:

```js
HelpHero.on("tour_started", function(event, info) {
  console.log(event, info);  
})
```

Registering a listener for all events:

```js
HelpHero.on(function(event, info) {
  console.log(event, info);  
})
```

```

--------------------------------

### HelpHero.advanceTour() with relative step index

Source: https://helphero.co/docs/javascript

Moves the tour forward or backward by a relative number of steps.

```js
HelpHero.advanceTour({ stepId: -2 })
```

--------------------------------

### HelpHero.setOptions({ show })

Source: https://helphero.co/docs/javascript

Toggles the display of all HelpHero content, such as tours, hotspots, and checklists. The default value is true.

```js
HelpHero.setOptions({ show: false })
```

--------------------------------

### HTML element with dynamic ID in href

Source: https://helphero.co/docs/steps/highlight-selectors

Example of an HTML anchor element whose href contains a dynamic ID, making it unreliable for selector generation.

```html
<a href="/nav/company/21343">company</a>
```

--------------------------------

### Embedding videos with iframe

Source: https://helphero.co/docs/html

Embed videos from YouTube or Vimeo using their embed codes. The example shows a Vimeo iframe with width, height, frameborder, and allowfullscreen attributes.

```html
<iframe src="https://player.vimeo.com/video/15069551" width="100%" height="360" frameborder="0" allowfullscreen></iframe>
```

--------------------------------

### HelpHero.advanceTour()

Source: https://helphero.co/docs/javascript

Advances the current active tour to the next step. This method is ignored if the current step is a highlight requiring user interaction.

```js
HelpHero.advanceTour()
```

--------------------------------

### Identify user with projectId and taskId for tour redirect with URL match variables

Source: https://helphero.co/docs/checklists

Use this script to provide values for URL match variables in tour URLs, enabling checklists to show and redirect to tours on any page. Replace '<USER_ID>', '<PROJECT_ID>', and '<TASK_ID>' with actual values.

```html
<script>
  HelpHero.identify('<USER_ID>', {
    projectId: <PROJECT_ID>,
    taskId: <TASK_ID>
  }); 
</script>
```

--------------------------------

### Rendered tour step text

Source: https://helphero.co/docs/steps/personalization

The placeholder is replaced with the actual user property value when the tour is viewed.

```text
Hello James! Want to take a quick tour?
```

--------------------------------

### HelpHero.update() script to assign user variant

Source: https://helphero.co/docs/funnels/split-testing

Add this script after your HelpHero installation scripts. It assigns a user to variant 'A' or 'B' randomly. Returning null when the user already has a variant ensures they are only assigned once.

```html
<script>
HelpHero.update(function(user) {
  // user is already assigned variant do nothing
  if (user.variant) return null

  var variants = ['A','B']
  // assign user to variant
  return { variant: variants[Math.floor(Math.random() * variants.length)] }
})
</script>
```

--------------------------------

### Responsive video with aspect ratio

Source: https://helphero.co/docs/html

Create a responsive video that maintains a 16:9 aspect ratio using a div with padding-bottom and an absolutely positioned iframe. Set the preferred width in the styling tab of the step configuration.

```html
Heres an example with a 16:9 aspect ratio

<div style="position:relative;padding-bottom:56.25%;">
  <iframe src="//fast.wistia.net/embed/iframe/j38ihh83m5" style="width:100%;height:100%;position:absolute;left:0px;top:0px;" frameborder="0" width="100%" height="100%" allowfullscreen allow="autoplay">
  </iframe>
</div>
```

--------------------------------

### Pass version property to HelpHero

Source: https://helphero.co/docs/funnels/releases

Identifies the user with a version property to control tour visibility. Includes an alternative for anonymous tracking. The code varies depending on server language and frameworks.

```html
<script>
  HelpHero.identify('<?php echo get_current_user_id(); ?>', {
    version: 1.1
  }); 

  // OR if using anonymous tracking
  // HelpHero.anonymous({ version: 1.1 });
</script>
```

--------------------------------

### Pass daysSinceSignup user property to HelpHero

Source: https://helphero.co/docs/funnels/new-vs-existing-legacy

Use this JavaScript snippet to pass a daysSinceSignup user property to HelpHero, assuming a user object with id and createdAt exists. The implementation will vary depending on your development setup.

```html
<script>
  // assumes user object with id (string or number) and createdAt (Date) exists in scope
  // the implementation will varying depending on your development setup
  HelpHero.identify(user.id, {
    daysSinceSignup: Math.floor((Date.now() - user.createdAt.getTime()) / 86400000)
  }); 
</script>
```

--------------------------------

### HelpHero.setOptions({ navigate })

Source: https://helphero.co/docs/javascript

Defines a custom navigation handler for HelpHero. If not set, it defaults to location.assign.

```js
function handleNavigate(url) {
  // use history or your frameworks router to change location
  // if using history please ensure your app responds to history changes
  try {
    history.pushState({}, '', url);
  } catch (err) {
    location.assign(url);
  }
}
HelpHero.setOptions({ navigate: handleNavigate });
```

--------------------------------

### HelpHero.setOptions({ showBeacon })

Source: https://helphero.co/docs/javascript

Controls the visibility of the HelpHero checklist beacon, overriding the default visibility settings.

```js
HelpHero.setOptions({ showBeacon: false })
```

--------------------------------

### Pass createdAt user property to HelpHero

Source: https://helphero.co/docs/funnels/triggered-by

Use HelpHero.identify to pass a createdAt date property to HelpHero. This code assumes a user object with id and createdAt exists in scope. The implementation will vary depending on your development setup.

```html
<script>
  // assumes user object with id (string or number) and createdAt (Date) exists in scope
  // the implementation will varying depending on your development setup
  HelpHero.identify(user.id, { createdAt: user.createdAt }); 
</script>
```

--------------------------------

### Custom CSS for HelpHero dialog components

Source: https://helphero.co/docs/theming

Paste this CSS into the Custom CSS field in the HelpHero Editor to apply advanced styling to the dialog header, footer, and body. It sets fonts, weights, text transforms, padding, background colors, and a background image. The example uses !important to override default styles.

```css
.hlp-dialog-header,
.hlp-dialog-footer {
  font-family: "Open Sans", sans-serif !important;
  font-weight: 800 !important;
  text-transform: uppercase !important;
}

.hlp-dialog-footer button {
  text-transform: uppercase !important;
  border-radius: 2px !important;
  background: black !important;
}

.hlp-dialog-footer {
  padding-bottom: 20px !important;
}

.hlp-dialog-body {
  padding: 40px 20px !important;
}

.hlp-dialog-header {
  font-size: 25px !important;
  padding: 40px 40px !important;
  height: 230px !important;
  background-size: 550px 300px;
  display: flex;
  align-items: center;
  justify-content: center;
}

.hlp-dialog-body {
  font-size: 1.1em !important;
  padding: 20px 40px !important;
}

.hlp-dialog-footer,
.hlp-dialog-header {
  text-align: center !important;
}

.hlp-dialog-header button {
  height: auto !important;
}

.hlp-dialog-footer button {
  font-size: 1.1em !important;
  padding: 8px 30px !important;
}

.hlp-dialog-header .hlp-content {
  padding-right: 0 !important;
}

.hlp-dialog-header {
  background-color: black !important;
  background-image: url(https://sandbox.helphero.co/images/examples/theme.jpg) !important;
}
```
Tokens:
Raw