Setting up

Contact your Minerva Account Manager (AM) to get an API key. You will need to provide your AM with the domains on which you wish to embed the Minerva widget.

Note: Minerva guides used to be called "recipes," so you will see references to recipes in the code. This is synonymous (from a product perspective) with guide.

Installing

On your web page (the end of the body tag is a good location), include the following code:

<script>

(function(win, doc, tag, url) {
  var Minerva = win.Minerva || (win.Minerva = {});

  /* Configure the SDK. */
  /* NOTE: You'll have to update your API Key */
  Minerva.config = { apiKey: 'YOUR_API_KEY' }

  /* Include the SDK. */
  var script = doc.createElement(tag)
  script.src = url
  script.async = true
  var entry = doc.getElementsByTagName(tag)[0]
  entry.parentNode.insertBefore(script, entry)

})(window, document, 'script', '//sdk.minervaknows.com/widget.js');

</script>

Launching a Guide

Each of these options take precedence in the specified order.

Magic URL (e.g., a “minerva” query parameter)

Once you have your API key for your domains, the share link for guides on your domain will no longer point to the Minerva web app. Instead, that URL will lead to your own website with an appended “minerva” query parameter. Something like: www.example.com/?minerva=someRandomString

When this URL loads, the SDK will automatically launch the guide encoded in the query parameter.

Global Configuration

The SDK can be told which guide to launch by assigning global variables before the SDK is injected.

<script>

(function() {
  /* Configure the launch guide. */
  /* NOTE: You'll have to update the Guide ID */
  window.MINERVA_START_RECIPE = 'GUIDE_ID'
  window.MINERVA_START_STEP = 0; // optional (default=0)

  // Proceed with configuration + include snippet...
})();

</script>

This is suitable if you're showing a single guide on page load.

The guide ID can be found in the URL share link before the /follow. An example is bolded and underlined below.  https://minervaknows.com/app/guides/af01316b-683b-41c6-a7ee-3c0c13580dde/follow

Programmatic Access

The SDK API provides a mechanism for launching a guide dynamically. Make the following call in your application code to launch a guide:

Minerva.init(function () {
  /* NOTE: You'll have to update the Guide ID */
  Minerva.start({ recipe: 'GUIDE_ID' });
});

Note: Using the Minerva#init method ensures the callback fires when the SDK is fully loaded.

This method is ideal in situations where global configuration is not suitable, e.g., dynamically invoking guides each time the page loads.

Optional parameters for Minerva.start:

• persist - a boolean that controls whether to store progress after guide launch. It may be useful in single-page applications where the page won’t reload and there’s no desire for the SDK to restore progress. This is enabled by default.
• step - a zero-indexed positive integer. It will start the guide on a specific step.

Identifying Users for Curated Guidebooks and Guides

The SDK provides a mechanism to identify and group your end users so that they may be shown curated Guidebooks and Guides via the SDK. At a bare minimum you will want to identify which Group a user belongs to, by specifying the space parameter. Identifying your users will make it easier to manage the Groups on the Minerva Web App. The group names that are specified here will populate within your Organization on the Minerva Dashboard and you will be able to use them to specify which Guidebooks are assigned to which Groups.

// Use to identify the end user and personalize Guidebook content.
Minerva.setUser({
    id: "unique identifier",
    friendlyName: "User Name",
    space: "Group Name",
})

Here's a quick example of how to use an obscured version of email to get the functionality you'd like (assuming you have access to a user object):

const email = user.email
// john.doe@example.com
const splitEmail = email.split('@')
// ["john.doe", "example.com"]
const fullAlias = splitEmail[0]
// "john.doe"
const fullDomain = splitEmail[1]
// "example.com"
const shortDomain = fullDomain.split(".")[0]
// "example"
const minUniqueID = fullAlias + " from " + shortDomain
// "john.doe from example"

// Use to identify the end user and personalize Guidebook content.
Minerva.setUser({
    id: minUniqueID,
    friendlyName: minUniqueID,
    space: shortDomain,
})

Putting it together

  <script>

    (function(win, doc, tag, url) {
      var Minerva = win.Minerva || (win.Minerva = {});

      /* Configure the SDK. */
      /* NOTE: You'll have to update your API Key*/
      Minerva.config = { apiKey: 'API_KEY' }

      /* Include the SDK. */
      var script = doc.createElement(tag)
      script.src = url
      script.async = true
      var entry = doc.getElementsByTagName(tag)[0]
      entry.parentNode.insertBefore(script, entry)
    })(window, document, 'script', '//sdk.minervaknows.com/widget.js');

    /* THESE ARE BETA FEATURES. NOT PART OF STABLE RELEASE YET. */
    /* USE WITH CAUTION. */

    /* Use Minerva.start to load a guide as soon as your page loads */
    const startMinerva = (Minerva) => {
      Minerva.init(() => {
        /* NOTE: You'll have to update your Guide ID*/
        /* You can grab this from your Minerva dashboard */
        Minerva.start({ recipe: 'GUIDE_ID' })
      })
    }

    /* Use Minerva.on with Minerva.destroy to automatically close */
    /* the Minerva widget when the guide is complete */
    const closeOnComplete = (Minerva) => {
      Minerva.on('recipe_completed', () => {
        Minerva.destroy()
      })
    }

    /* Use this function to initialize Minerva with */
    /* your chosen functions on page load */
    window.addEventListener('load', () => {
      const Minerva = window.Minerva || (window.Minerva = {})
      startMinerva(Minerva)
      setTimeout(() => { closeOnComplete(Minerva) }, 1000)
    })

  </script>