Blackboard Logo

Integrate Ally as a Service into your own user interface

The UI API is a specification for HTML attributes that can be used to introduce consistent patterns of Ally functionality.

Set-up

The latest UI API is readily available from your regionial Ally deployment:

<script src="https://prod-eu-central-1.ally.ac/integration/api/ally.ui.js"></script>

Configuration

Before any interaction logic can be applied, the UI API needs to be initialized.

// Wait until the Ally UI API has bootstrapped itself, this is usually a matter of milliseconds after loading
ally.ready(function () {
  // Configure the Ally UI API and store it on the `ui` instance variable on the window.
  window.ui = ally.ui({
    client: {
      // An authentication function that returns a suitable JWT token.
      // The function will be invoked each time the UI API needs to make an authenticated call to the Ally API.
      // When Ally needs to interact with a piece of content, the content hash id will be passed in. You can use
      // this to provide a token that is scoped to just that resource ID and/or apply your own rate limit.
      // When API calls are made that aren't specific to a content hash (e.g. determining custom help content),
      // no argument will be provided and a generic token can be returned.
      auth: (hashId) => Promise.resolve({ bearer: "eyJhbGciO..." }),

      // The base URL of your regional Ally API
      baseUrl: "https://prod-eu-central-1.ally.ac",

      // Your numerical Ally client identifier
      clientId: 42,
    },

    // The locale controls the internationalization and localization of the dialog
    locale: "en-US",

    // The Ally UI API currently requires this to be set to AaaS
    platformName: "AaaS",
  });
});

Once the UI object has been created, you can then use it to bind click handlers into your own DOM. You should run this function once the elements that you want to trigger Ally functionality are available in the DOM.

// Optional element to scan, defaults to the `body` element.
const el = document.getElementById("links");

// Check all the elements under #links and bind the necessary event listeners.
window.ui.update(el);

There is also an option to let the Ally UI API monitor the DOM and invoke the update method every x milliseconds. This is intended for when you have a dynamic web application where the DOM is actively changed as the user interacts with the page. e.g. single page applications, pop-out menus, etc..

// Scan the entire DOM
window.ui.autoUpdate({
  // Represents the millisecond interval at which to automatically update the DOM. If a number `> 0` is specified,
  // the DOM will be checked at this frequency. Otherwise, the DOM will be checked only once.
  // Optional.
  domWatch: 500,

  // The element whose subtree to scan for relevant data attributes.
  // Optional, defaults to the `body` element
  el: document.getElementById("links"),
});

Data attributes

The Ally UI API works by placing HTML data-* attributes in the DOM. The following generic attributes can be considered:

Alternative formats

When you want to offer alternative formats to your users, it’s recommended to rely on Ally’s UI API as it is able to communicate all the intermediate states before a format can be downloaded. The Alternative Formats modal can be launched from any web application and does not come with any Blackboard Branding.

A screenshot of the alternative formats modal

Example

The following example contains two links. The first link is a download link your application might already make available to your users. This element should be annotated with the relevant Ally information (aaas-content-hash and download-url) and a content-id so that it can be referred to by the second link which will trigger the alternative formats modal.

<a
  href="/download/12312123"
  data-ally-content-id="myAllyContentId1"
  data-ally-aaas-content-hash="QWxseSstK09uZStQYWdlcistK0hpZ2hlcitFZCstK0dlbmVyYWwucGRmOjM0QURFNDE2NzNDRUJBNUIyRjc2MDI3N0IxOEYwNTdERDY1MDczQzg6YXBwbGljYXRpb24vcGRm"
  data-ally-download-url="https://ally-public.s3-us-west-2.amazonaws.com/demo/High+Quality+Alternative+Formats/Ally+-+One+Pager+-+Higher+Ed+-+General.pdf"
>
  Original file
</a>
<a
  href="#"
  title="Alternative formats"
  data-ally-content-ref="myAllyContentId1"
  data-ally-invoke="alternativeformats"
  data-ally-show="alternativeformats"
  data-ally-show-display="inline"
  data-ally-tooltip
>
  <img
    src="/assets/img/ally-logo.svg"
    alt="Alternative Formats"
    width="25"
    height="20"
  />
</a>