Javascript SDK

Easy 2-Step Install & Usage

Step 1

Copy & Paste Javascript tag in the head section across all pages of your website. Put in your project_id and environment_id.

<script src="https://www.showandtell.io/tell/?project=your_project_id&environment=your_environment_id" id="showandtell_script" ></script>

Step 2

After the page has loaded, set your options & call tada().

// Option 1: Simple Call
ShowAndTell.tada(); // shows any badges, banners, tooltips, tours & app messages for a page
// Option 2: Customize Options
var options = {
    badges: true,                       // default: true, renders badges, respects member_id whitelist/blacklists
    beacons: true,                       // default: true, renders beacons, respects member_id whitelist/blacklists
    tooltips: true,                     // default: true, renders tooltips, respects member_id whitelist/blacklists
    flags: true,                        // default: true, populates feature flags, respects member_id whitelist/blacklists
    banners: true,                      // default: true, renders banners, respects member_id whitelists/blacklists
    event: "example_event",             // fires event that can return an app message or tour, respects member_id whitelist/blacklists
    message: "example_message_name",    // renders a specific app message
    tour: "example_tour_name",          // renders a specific tour
    pop_message: true,                  // default true, set to false if you don't want app message to be shown on load
    member_id: "example_unique_id",     // unique id (ex: user_id, email of user, id of a group, any id!) to respect whitelist/blacklist's
    success_callback: function(data) {  // function called after successful server response
      console.log("Tada data:");
      console.log(data);
    }
};
ShowAndTell.tada(options); // gets all data for options and shows any badges, banners, tooltips, tours & app messages

Pro Tip:
Use Tada() to ask for EVERYTHING so you can always target a page with badges, banners, tooltips, tours & in-app messages.

How to use App Messages

Set up App Messages in the Show&Tell Admin

You will create App Messages in the admin view and then the Javascript triggers when an App Message will be shown.

Trigger via URL path

You can create App Messages that show when a user visits a URL path. Respects whitelist/blacklists if member_id is in options.

//Call Tada() on all pages you might want to show an App Message
var options = {
    member_id: "tester@example.com" // an member_id for whitelist/blacklist checking
};
ShowAndTell.tada(options); // displays any applicable app message targeting URL path of current page

Note:
URL path matching ignores query string params. The URL path matching is greedy. Here is an example:

Your user is on the URL "www.yourwebsite.com/example/longer?utm_source=ads"

  • App Message with exact match URL path trigger '/example/longer' will show.
  • If no exact match, App Message with URL path trigger '/example' will show.
  • App Message with URL path trigger '/example/short' does NOT match.
  • App Message with URL path trigger '/ex' does NOT match. Path trigger must match exact string between '/'s.
  • Query string "utm_source" is ignored
  • Don't put your domain in the URL path trigger field. Only enter the path which is after the first '/' in the URL you wish to target.
  • App message with most specific Path trigger match will show first.

Trigger Events

Trigger events around your site. Then you can create App Messages that target those events. Respects whitelist/blacklists if member_id is in options.

var options = {
    event: "first_login" // an example event for right after a user logs in the first time
};
ShowAndTell.tada(options); // triggers event and displays applicable app message

Example events to setup for the option to display a message to your users:

  • Immediately after signup
  • After the a user does a key action
  • After someone logs in and their plan has expired
  • After a major section of your website loads
  • Setup as many events as you want! Then target them later.

There is no harm in firing events that don't always show an app message because you want to have the option to at a later time.

Show Specific Message

Ask for a specific message to be shown. Does NOT respect whitelist/backlists.

var options = {
    message: "welcome_modal" // an example app message to show
};
ShowAndTell.tada(options); // gets and displays app message

More App Message options

Pass "member_id" when triggering an event to respect whitelist/blackslists. Optionally pass "pop_message" as false to get app message data but NOT show the message.

Order of App Message Checks

App Message will be shown based on the logical order below:

  1. Message with exact name requested
  2. Message targeting triggered event
  3. Message targeting current URL path

How to use Tours

Set up Tours in the Show&Tell Admin

You will create Tours in the admin view and then the Javascript triggers when an Tour will be shown.

Trigger via URL path

You can create Tours that show when a user visits a URL path. Respects whitelist/blacklists if member_id is in options.

//Call Tada() on all pages you might want to show a Tour
var options = {
    member_id: "tester@example.com" // an member_id for whitelist/blacklist checking
};
ShowAndTell.tada(options); // displays any applicable tours targeting URL path of current page

Note:
URL path matching ignores query string params. The URL path matching is greedy. Here is an example:

Your user is on the URL "www.yourwebsite.com/example/longer?utm_source=ads"

  • Tour with exact match URL path trigger '/example/longer' will show.
  • If no exact match, Tour with URL path trigger '/example' will show.
  • Tour with URL path trigger '/example/short' does NOT match.
  • Tour with URL path trigger '/ex' does NOT match. Path trigger must match exact string between '/'s.
  • Query string "utm_source" is ignored
  • Don't put your domain in the URL path trigger field. Only enter the path which is after the first '/' in the URL you wish to target.
  • Tour with most specific Path trigger match will show first.

Trigger Events

Trigger events around your site. Then you can create Tours that target those events. Respects whitelist/blacklists if member_id is in options.

var options = {
    event: "first_login" // an example event for right after a user logs in the first time
};
ShowAndTell.tada(options); // triggers event and displays applicable tour

Example events to setup for the option to display a tour to your users:

  • Immediately after signup
  • After the a user does a key action
  • After a major section of your website loads
  • Setup as many events as you want! Then target them later.

There is no harm in firing events that don't always show a tour because you want to have the option to at a later time.

Show Specific Tour

Ask for a specific tour to be shown. Does NOT respect whitelist/backlists.

var options = {
    tour: "welcome_tour" // an example tour to show
};
ShowAndTell.tada(options); // gets and displays tour

More Tour options

Pass "member_id" when triggering an event to respect whitelist/blackslists.

Order of Tour Checks

Tour will be shown based on the logical order below:

  1. Tour with exact name requested
  2. Tour targeting triggered event
  3. Tour targeting current URL path

How to use Feature Flags

Set up Flags in the Show&Tell Admin

You will manage Feature Flags in the admin view and then the Javascript pulls them down from the server.

Show or Enable Features

Set your options, call tada() and then use the ShowAndTell object to control visibility/access to your features. Respects whitelist/blacklists if member_id is in options.

// 1. Request Feature Flags from the server
ShowAndTell.tada(); // sets your feature flags

// 2. Check Feature Flags to enable/disable a feature
if(ShowAndTell.getFlagValue('new_feature') === "true") {
  // Show or enable your feature
}

How to use Beacons, Badges, Banners & Tooltips

Set up Beacons, Badges, Banners & Tooltips in the Show&Tell Admin

You will manage these items in the admin view and then the Javascript triggers them and places them on the page.

Showing them on the page

Set your options, call tada() and then Beacons, Badges, Banners & Tooltips will magically be displayed. Respects whitelist/blacklists if member_id is in options.

Important: DOM object a Beacon, Badge, Banner or Tooltip is targeting must be present on page load. Targeted DOM object CAN be hidden on load. Can NOT be dynamically added after page load.

Customizing Styles: Beacons, Badges, Banners, Tooltips & App Messages

It's easy to customize the look & feel of Show & Tell elements.

Just include your stylesheet after the Javscript tag in the head section or your website. Then just override the styles.

All ShowAndTell element styles start with "snt_".

You can also use append "!important" to your styles in your stylesheet (not a CSS best practice but it will work).

Test Javascript SDK Installation

Test installation by adding ?showandtell to the end of the URL for a page with the Javascript installed.

If installed properly, you will see an alert.

Server-Side API

Getting Feature Flags, Beacons, Badges, Banners, Tooltips, Tours & App Messages

GET the Show&Tell Tada endpoint passing in project & environment (required). Then you add all your options.

Important Note: The endpoint is opt-out. Meaning, you will get everything unless you specify not to.

You will then get a JSON response to use Feature Flags and the other objects in your server-side code.

#Get all Flags, Beacons, Badges, Banners & Tooltips
GET https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id

#Get Flags, Beacons, Badges, Banners & Tooltips for a specific member
GET https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id&member_id=user@example.com

#Get only feature flags (Optional: Add app_version param if using flags in mobile apps)
https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id&badges=false&beacons=false&tooltips=false&banners=false&flags=true&app_version=2.12.3

#Get a specific app message
GET https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id&message=example_message_name

#Get an app message for an event
GET https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id&event=after_login

#Get an app message for a specific event and member
GET https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id&event=after_login&member_id=user@example.com

#Get a specific tour
GET https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id&tour=example_tour_name

#Get a tour for an event
GET https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id&event=after_login

#Get a tour for a specific event and member
GET https://www.showandtell.io/api/tada/?project_id=your_project_id&environment=your_environment_id&event=after_login&member_id=user@example.com