Documentation

Slickstream Client API:  Version 1 BETA

Kingston Duffie
Kingston Duffie

Customers have asked us for a client-side API that they can use to integrate even more closely with Slickstream features.

Note: This API is in beta and is subject to change at any time

Events

Add an event listener on the document object to be notified when certain events occur:

slickstream-ready: This event fires when the slickstream API is ready for use.

slickstream-user-status-change:  This event fires when the current user's sign-in state changes.

slickstream-favorite-change: This event fires when the favorite state of the current page for the current viewer has changed.

 

Accessing the API

Once loaded, the Slickstream API is available via the window object:

window.slickstream.v1

 

User

The user member of the API object provides access to features related to signing in, signing up, identity, etc.

status:  This tells you the login status of the user (i.e., the current viewer of the page).  It is one of:

  • 'anonymous':  This is for any user that has not been authenticated;
  • 'signed-in':  This is for any user that has been authenticated via Slickstream sign-in;
  • 'client-auth':  This is for a user who has been authenticated because of meta-tags added by the site itself (e.g., based on Slickstream's WordPress plugin for viewers signed into WordPress)

emailAddress:  If the current user is authenticated, this is the email address of that user.

name:  If the current user is authenticated, and their name is known, this returns that value.

openSignInDialog(emailAddress?): This causes Slickstream's sign-in dialog to be shown to the viewer.  If the email address is provided, it will be used to pre-populate the corresponding field in that dialog.  Note that this covers both sign-in and sign-up scenarios.  Nothing is returned.

signOut():  This tells Slickstream to sign-out the current viewer if appropriate.  Note that this will not affect the status of a viewer in the 'client-auth' state -- as we cannot affect WordPress (or other site server) sign-in state.  This returns a Promise when the operation is complete.

 

Favorites

The favorites member of the API object is an object supporting the Favorites feature:

getState(): This method returns true if the current page is a favorite of the current viewer.

setState(isFavorite): This method sets or clears whether the current page is a favorite of the current viewer. It is asynchronous and returns a Promise.

 

Sample Javascript Code

// This sample assumes you have a favorite button and
// its text content shows the current favorite state.
// Likewise, it assumes you have a login button that
// toggles between 'sign in' and 'sign out' depending
// on status
const fb = document.querySelector('#favStatusButton');
const lb = document.querySelector('#loginButton');
 
// This returns the Slickstream API object,
// waiting if necessary for loading to complete
 
async function ensureSlickstream() {
   if (window.slickstream) {
       return window.slickstream.v1;
   }
   return new Promise((resolve, reject) => {
      document.addEventListener('slickstream-ready', () => {
         resolve(window.slickstream.v1);
      });
   }); 
}
 
async function updateFavoriteButtonState() {
   const slickstream = await ensureSlickstream();
   const isFavorite = slickstream.favorites.getState();
   fb.textContent = slickstream.favorites.getState() ? `I'm a favorite` : `I'm not a favorite`;
}
 
// The login button in this example handle three different cases.
// For normal cases, it shows "log in" or "log out" appropriately.
async function updateLoginButton() {
   const slickstream = await ensureSlickstream();
   switch (slickstream.user.status) {
      case 'signed-in':
         lb.textContent = 'Log out';
         lb.disabled = false;
         break;
      case 'client-auth':
         lb.textContent = slickstream.user.emailAddress;
         lb.disabled = true; // User cannot affect state 
         break;
      case 'anonymous':
         lb.textContent = 'Log in';
         lb.disabled = false;
         break;
   }
}
 
fb.addEventListener('click', async() => {
   const slickstream = await ensureSlickstream();
   const state = slickstream.favorites.getState();
   slickstream.favorites.setState(!state);
});
 
lb.addEventListener('click', async() => {
   const slickstream = await ensureSlickstream();
   switch(slickstream.user.status) {
      case 'signed-in':
         slickstream.user.signOut();
         break;
      case 'anonymous':
         slickstream.user.openSignInDialog();
   }
});
 
// If the favorite state has changed this event will fire and
// this ensures your display of the state remains correct
document.addEventListener('slickstream-favorite-change', () => {
  updateFavoriteButtonState();
});
 
// If the current user state changes, this will update the 
// text in the login button accordingly
document.addEventListener('slickstream-user-status-change', () => {
  updateLoginButton();
}
 
// After the page loads, this will ensure your display
// is updated as soon as the info is available
updateFavoriteButtonState();
updateLoginButton();