Installation Guide

Last Updated: 26 Feb 2019

This entire manual refers to a feature that was added in version 5.4.5.0

Prerequisites

The Drop-in-apps Connector requires a minimum Squiz Matrix version of 5.4.5.0 or above.

The following guide also assumes a small amount of technical work is needed, specifically a number of hours for:

  • Squiz Support to:
    • Install the Drop-in-apps Connector Package in your Squiz Hosted system, so that the connector asset can be created by your Matrix Administrator or a Squiz Implementer. This will be completed by Squiz (for free) during the new app request process.
  • Your own Matrix Administrator or a Squiz Implementor to:
    • Create and configure a Drop-in-apps Connector Asset. This only has to be done once per Matrix instance.
    • Update one or more Design Files so that it can load the app bootstrap. This needs to be done once for each website design that needs to use an app.
    • Update one or more Paint Layouts with the app embed snippet. This will vary per website and number of locations required.

Please contact your Squiz Account Manager (or contact your local Squiz office) if technical assistance is required.

Get the app keys ready

Every new app deployment (for every customer) comes with a snippet of embed code that is copy and pasted into Matrix where required. Each app also comes with client specific app keys; one key (the API Secret Key) is applied to the connector asset during configuration and the second key (the API Client Key) is used in the app embed code.

These details are provided during the process of requesting a new app. To request a new app, visit the Squiz Marketplace, choose the app you want, then select the "Get this app" button.

Setup the connector for app authentication

The following connector example (with the asset name of "Apps Connector") assumes the one connector is being used for multiple apps across a single Matrix instance. Repeat this process if different connectors are required for custom permission scenarios.

Avoid creating more than one connector

When a new app is requested, the Squiz App Team will check to see if the required Matrix install is already using one or more apps. If the Matrix install already uses an app, then the new app will be able to reuse the existing secret key. This helps to avoid having to set up multiple connectors.

Multiple connectors are only required when there is a need to customise different permissions. In these cases each new connector should still be able to use the same secret key.

Organise your connectors

It is recommended that connector assets are organised within your existing site structure so that they are easy to locate and easier to centrally manage.

Each Drop-in-apps Connector Asset requires a URL in order to work, so it is best to add new connectors to a single folder located underneath an existing website that already has a URL applied.

In this example image shown above, a folder called "Drop-in Connectors" was created directly underneath the website where the app is used. Please note that site structure and information architecture may vary between systems.

Create the connector

Locate the folder where connector assets are managed.

  1. Right click on the folder.
  2. Select New Child > Connectors > Drop-in-apps Connector.
  3. Enter a meaningful name, for example "Apps Connector".
  4. Click Save. The new asset will be created.

Apply the API secret key

Each drop-in requires a private (secret) and public key to work as expected. The secret key is applied to the Drop-in Connector Asset and the public key is applied to the embed snippet.

On the Details Screen of the Drop-in-apps Connector Asset:

  1. Enter the secret key into the API Secret Key field.
  2. Click Save.

Configure Matrix user details for authentication

Each app requires the connector to first authenticate so that it can then pass Matrix user information to work as expected. The connector provides this as customisable keyword replacements inside a JSON format.

For each connector, on the Details Screen:

  1. Copy and paste the following code into the User Data field.

    {
        "username"  :   "%globals_user_attribute_username^json_encode%",
        "firstName" :   "%globals_user_attribute_first_name^json_encode%",
        "lastName"  :   "%globals_user_attribute_last_name^json_encode%",
        "admin"     :   %asset_has_write_access^eq:1:true:false%
    }
    
  2. Click Save.

Enable the in-page administration features

Each app comes with a number of inline management features that can only be seen if you have a minimum of Write Access to the Drop-in Connector.

A System Administrator (who is logged into Matrix) will automatically see these features when viewing the site.

For anyone else who may need to use these inline management features, make sure that their User or User Group is assigned with a minimum of Write Access to the related Drop-in-apps Connector Asset.

To assign a User or User Group inline administrator rights:

  1. Right click on the related Drop-in-apps Connector Asset in the Asset Tree.
  2. From the menu, select Permissions.
  3. Apply a User or User Group under Write Access where required.

Publish the connector

For site visitors to see apps on the site, the related Drop-in-apps Connector Asset needs to be made Live and have at least Read Access granted to the Public User.

To make the Drop-in-apps Connector live:

  1. On the Details screen, select Approve and Make Live in the Change Status field.
  2. Click Save. The Status of the connector will change to Live.

To check the Permissions of the Drop-in-apps Connector:

  1. Right click on the related Drop-in-apps Connector Asset in the Asset Tree.
  2. From the menu, select Permissions.
  3. Make sure that the Public User is listed in the Read Permissions section of the screen.

Embed the app into your websites

App snippets can be pasted into any asset that Squiz Matrix prints as HTML to the browser. However, to make it easier to manage and reuse snippets, it is advised that apps are embedded using the following instructions.

Bootstrap the site designs

For each website that needs to load an app, locate the related Design File and add the following line of code. In most cases this should be placed just before the closing body tag.

<script type="text/javascript" src="https://apps.squiz.systems/cdn/shared/bootstrap.js" async></script>

Prepare the paint layouts

App embed code should be pasted into RAW HTML containers situated inside of the layouts that control the look and feel of page content.

  1. Locate your Paint Layout, right click on Default Format, and then select Edit Contents.
  2. Select the plus icon at the bottom of the page. The Insert New Content Container pop up will appear.
  3. In the Presentation field, select Raw (no formatting).
  4. In the Content Type field, select Raw HTML.
  5. Click the Insert button. A new Raw HTML container will be added to the bottom of the page.

Copy and paste the embed snippets

Select which app you are using and copy / paste the related snippet into the Paint Layout where needed.

Commenting snippet

<!-- When pasting this snippet into home page replace id with home-%globals_site_assetid%  -->
<dropin-commenting>
  <script type="application/json">
    {
      "id"       : "page-%frontend_asset_assetid%",
      "user_url" : "./?a=replace with connector asset-id",
      "api_key"  : "replace with API Client Key"
    }
  </script>
</dropin-commenting>

Feedback snippet

<dropin-feedback>
  <script type="application/json">
    {
      "id"       : "site-%globals_site_assetid%",
      "user_url" : "./?a=replace with connector asset-id",
      "api_key"  : "replace with API Client Key"
    }
  </script>
</dropin-feedback>

Polls snippet

<dropin-polls>
  <script type="application/json">
    {
      "id"       : "give this a unique hardcoded name based on where you put it in the page",
      "user_url" : "./?a=replace with connector asset-id",
      "api_key"  : "replace with API Client Key"
    }
  </script>
</dropin-polls>

Customising the app settings

Configuring styles and languages

Each app loads with default styling and in a default language (english), the following example shows the extra settings for each app that can be manually customised.

Change style values to match your branding, and change the language value for the language that you would like the app interface strings to be printed in.

<!-- Example of commenting app embed code with custom settings for styles and language  -->
<dropin-commenting>
  <script type="application/json">
    {
      "id"       : "example",
      "user_url" : "./?a=example",
      "api_key"  : "example",
      "language" : "en",
      "styles"   : {
        "accentColour"           : "#28A0C7",
        "fontFamily"             : "arial",
        "fontSize"               : "1rem",
        "textColour"             : "#191919",
        "editorColour"           : "#f5f5f5",
        "accentTextColour"       : "#ffffff",
        "borderColour"           : "#d1d1d1",
        "buttonBackgroundColour" : "#ffffff"
      }
    }
  </script>
</dropin-commenting>

Positioning the Feedback icon

To position the feedback app, you will need to wrap the embed code with a container element and use inline styles or the main style sheet to position it on the page. The following example shows the feedback app positioned bottom right of the page using a DIV container with inline styles.

<!-- Example feedback snippet with inline styles applied to a div container -->
<div style="position: fixed; bottom: 20px; right: 20px;">
    <dropin-feedback>
      <script type="application/json">
        {
          "id"       : "site-example",
          "user_url" : "./?a=example",
          "api_key"  : "example"
        }
      </script>
    </dropin-feedback>
</div>

Previewing the app

Once the Drop-in-apps Connector Asset and embed code have been added and configured correctly, the app should be available for previewing and use with your site.

To preview the app:

  1. In the Asset Tree, right click on the page that you expect the drop-in app to appear on.
  2. From the menu, select Preview > In New Window.

A preview of the page will load in a new window and the drop-in app will appear on the page.


Send Feedback

Noticed an error?
Want to suggest an improvement?

Let Us Know

The Latest

Let Us Know What You Think

Let us know if you spot any errors or if you have any ideas on how we can improve the Matrix Community Website.

Contact Squiz for Demo

Let us show you the true power of Squiz Matrix by giving you a personalised demonstration.