Installing the Connect Plugin

Easily install the Connect Plugin in your own website or environment

The Connect Plugin allows you to easily request authorization to manage other Shout Accounts in your own website or environment. This guide provides step by step guidance for installing the Connect Plugin as well as some configuration guidance for booting the plugin in advanced configurations.

Contents

Before You Get Started

If you've skipped over the preceding Shout guides ( no worries, we don't always read everything first either 😉), here are a few things that you'll want do before you open up your code and install a Connect Plugin:

  1. Make sure you or your organization has Shout Connect enabled on their account. If you're not sure, login to your Shout account and navigate to Settings > Services > Shout Connect. If you aren't able to access the Shout Connect page, reach out to Shout support (for production environments) or Shout Developers (for development environments) and ask to have it enabled for your organization first.
  2. Make sure that you have access to your organization's website. You'll need to install a small snippet of HTML and Javacript into the body of the page you want the plugin to be displayed on.

Step-By-Step Installation of Connect Plugin

There are three primary steps to installing a Shout Connect Plugin. These step are explained in detail with code examples below.

  1. Copy the Plugin Snippets from the Shout Connect Account.
  2. Paste the Code Snippets inside the <head></head> tags of your website.
  3. Configure the plugin to boot with the correct connect_id

Step 1: Copy the Plugin Snippets from the Shout Connect Account

Each Shout Connect account has unique code snippets that you will copy. You can get these snippets by following these instructions:

  1. Login to your Shout account and navigate to your Shout Connect services Page by clicking on Settings > Services > Shout Connect. If the page is not visible contact Shout support to have it enabled on your account.
  2. Click the "Manage" button next to the Company name and click Connect Plugin Setup.
  3. Read the instructions and copy the code snippets found there.

Step 2: Paste the Plugin Snippets into the Body of your Website

The Connect Plugin snippets should be added to the head of your website. The snippet consists of a script that will find an element with the id connect-widget-render-location element on the webpage, fetch the plugin code from Shout's servers, and then add the plugin to the page in that location.

  1. Paste the Connect Plugin Snippet into the head tag of your website.
  2. Add an div element with the id of connect-widget-render-location 
    <!-- Shout Connect Plugin will display here -->
<div id="connect-widget-render-location"></div>

    The end result of the code on your page should look something like this:

    <html>
  <head>

    <!-- Paste the snippet of your plugin above the </head> tag -->
    <script>
      (function(s, h, o, u, t) {
        u = s.getElementsByTagName('script')[0];
        o = s.createElement('script');
        o.async = 1;
        o.src = 'http://localhost:3000/p/connect_clients/some_unique_id.js';
        u.parentNode.insertBefore(o, u);
      })(document, window);
    </script>

  </head>
  <body>
    <h1>Hello World</h1>
    <p>Some text goes here.</p>

    <!-- Add a div where you want the plugin to be displayed on your page -->
    <div id="connect-widget-render-location"></div>

  </body>
</html>

Step 3: Configure the plugin ot boot with the correct Connect ID

In order for the plugin to correctly boot, it needs a connect_id to be provided to the plugin. A connect id is just the id that identifies the user who is viewing the plugin. This could be a unique customer id, a distributor id, or some other id that can be used by you or your applications to manage the Shout account of this person in future API calls. You'll simply add this connect id to the end of the link to the script stored on Shout as a url parameter ?connect_id=abc123. For example, the code snippet you paste into the head will look something like this:

<script>
  (function(s, h, o, u, t) {
    u = s.getElementsByTagName('script')[0];
    o = s.createElement('script');
    o.async = 1;
    o.src = 'http://localhost:3000/p/connect_clients/some_unique_id.js';
    u.parentNode.insertBefore(o, u);
  })(document, window);
</script>

The link portion of the script is found here:

'http://localhost:3000/p/connect_clients/some_unique_id.js'

And you'll modify the link to add the url parameter connect_id so it looks like this:

'http://localhost:3000/p/connect_clients/some_unique_id.js?connect_id=abc123'

There are many approaches for creating this modified link that contains the connect id. And the approach that you use will depend on where you store the unique identifier for those in your organization. If you need help, reach out to Shout Developers (see links in the Introduction), we'd love to help.

Notes for Single Page Applications (SPA)

If your website or application uses a single page application (spa) architecture like REACT or ANGULAR, we've found a couple of useful notes to consider and troubleshoot booting up the Connect Plugin.

  • You may need to ensure that you add the Connect Plugin snippet after the html element with the id connect-widget-render-location is already on the page. If, for example, you add the Connect Plugin script at the same time, there may be a race condition where the script will be unable to find the element on the page and fail to boot.
  • In angular implementations, we've found it easiest to wait for the angular script to be loaded before adding the Connect Plugin script.
  • In react implemenations, you can add the Connect Plugin script in the useEffect() or componentDidMount() lifestyle methods, or explore creating a custom hook of your own as described here.

Links