Skip to content

Latest commit

 

History

History
146 lines (99 loc) · 8.67 KB

OpenLynkSpec.md

File metadata and controls

146 lines (99 loc) · 8.67 KB
Raw

Openlynk Technical Specification

This document aims to complement the Openlynk reference document. They should eventually either merged into one document, or enforce a technical vs agreement theme.

This is the first draft of the spec, using a terse bullet-list format instead of prose to get the main ideas on paper. Also, Studyo is referred explicitely in certain cases.

Feedback

This spec is not set in stone yet and feedback is more than welcome. Comments and suggestions can be submitted and discussed via Github Issues, and edits can be suggested via pull requests.

Pasted URLs with auto-format

  • All resources defined in Openlynk end up as URLs with a representation embedded in the host.
  • i.e. Studyo tasks can have links to external resources (URLs).
  • These links are presented in a nicely formatted button, which can either be an icon and title extracted from the resource or an embedded view of the resource.
  • The icon/title or embedded view are determined from these sources, in order of precedence:
    1. Openlynk meta tags
    2. oEmbed provider response
    3. Open Graph metadata
    4. Twitter Summary Card
    5. Agreed-upon icon and generic title
    6. The title and favicon of the HTML page
    7. Icon and title determined by Studyo for external services that are not part of this agreement

Openlynk meta tags

Required

These meta tags must be present in the head of the external resource's HTML page:

  • openlynk:title: The title of the resource as it should appear in the Studyo Task's button. Depending on the type of resource, it can be the title of the document/activity (e.g. What are atoms?) or a call to action (e.g. Answer the quizz).
  • openlynk:url: The canonical URL of the external resource.
  • openlynk:bwIconUrl: An image URL which represent the branding of the external resource provider in black and white. Must have a square aspect ratio. Will typically be displayed inside a black circle which could be fairly small (as small as 10x10 points).
  • openlynk:colorIconUrl: An image URL which represent the branding of the external resource provider in color. Must have a square aspect ratio. Will typically be displayed at a size of 24x24 points.

Optional

These meta tags may be present in the head of the external resource's HTML page:

  • openlynk:thumbnailUrl: An image URL which represents the external resource. Should have a square aspect ratio, but this is not mandatory. If a thumbnail is provided, it will be used instead of the colorIconUrl in the Studyo Task's button.
  • openlynk:iOSUrlScheme: The iOS url scheme that can be used to open the resource in the host's native iOS app, if installed on the device. If the openlynk:url is a Universal Link, the url scheme is not required.

oEmbed

If a resource provider does not include Openlynk meta tags, the host will try an oEmbed request if oEmbed discovery links are found in the resource page.

The thumbnail_url and title oEmbed response values will be used for the Studyo Task's button icon and title.

If type is video or rich, Studyo may choose to display the embed html code inside the task, instead of the usual "icon and title" presentation.

Open Graph

If previous options are not available, the host will look for Open Graph metadata on the resource page.

The og:image and og:title values will be used for the Studyo Task's button icon and title.

Twitter Summary Card

If previous options are not available, the host will look for Twitter Summary Card definition on the resource page.

The twitter:image and twitter:title values will be used for the Studyo Task's button icon and title.

Agreed-upon icon and generic title

If no metadata of any sort is found on the resource page, either because the provider does not implement them or because the link requires authenticated access and returns an error page when fetched without proper authentication, the icons (bw and color) provided by the provider will be used in the host, with a generic call to action title (e.g. Open in Netmath). The icon and title will be determined based on the domain of the resource URL (e.g. *.netmath.com means the host should use the Netmath icon and title).

Fallback

If a link points to a domain that is not part of this agreement, therefore has no predefined icon and title, the host may opt to use the provider's icon and name on a case-by-case basis. If not, it will fall back to using the <title> and favicon of the page, which can be one of:

  • The value of the <link rel="icon"> tag in the <head> of the page.
  • The value of the <link rel="apple-touch-icon"> tag in the <head> of the page.
  • The image located at the /favicon location on the resource host.

Openlynk Resource Picker

  • As mentioned above: it's all about URLs.
  • So simply pasting a URL is enough to create a branded button inside a Studyo task.
  • But to simplify the process of adding a URL to a task, the provider can implement a picker UI.
  • When a provider implements a picker, it will show up in Studyo's list of supported providers (e.g. Attach a ChallengeU activity).
  • The UI of the picker is implemented by the provider using HTML, CSS and JavaScript.
  • Studyo will display the picker in a popup/modal window.
  • Studyo will navigate to an agreed-upon URL for the picker (e.g. http://netmath.com/services/openlynk/picker).
  • If the provider requires authentication and there is no active browser session, a login UI should be displayed first.
  • The provider should implement a UI flow that is appropriate for its type of content (multi-level hierarchical navigation, topic selection, etc).
  • Once a resource is selected by the user, the picker must return the URL and some metadata to the host using the mechanisms documented below.

Returning the selected URL form the picker

There are various ways a picker can return the selected URL to the host: postMessage or url.

postMessage

  • The picker will be invoked with the callbackType=postMessage query string.
  • Once the user has selected a resource, the picker must call the window.postMessage JavaScript function to send the select resource to the host:
var message = {
    type: "StudyoPicker_PickedResource", // Required, verbatim
    resource: {
        url: "http://netmath.com/123",
        title: "Arithmetic",
        colorIconUrl: "http://netmath.com/colorIcon.png",
        bwIconUrl: "http://netmath.com/bwIcon.png",
        thumbnailUrl: null // Optional
    }
};

window.opener.postMessage(message, "*"); // TODO: Do not use a wildcard target origin
  • The host will take care of closing the picker popup, so the picker must not call window.close() itself.
  • Each key in the resource object correspond to an Openlynk meta tag. Please refer to the Openlynk meta tags documentation above for a detailed description.

url

  • The picker will be invoked with the callbackType=url&callbackUrl=x query string.
  • Once the user has selected a resource, the picker must navigate to the provided callbackUrl, providing the resource via the query string:
var resource = {
    url: "http://netmath.com/123",
    title: "Arithmetic",
    colorIconUrl: "http://netmath.com/colorIcon.png",
    bwIconUrl: "http://netmath.com/bwIcon.png",
    thumbnailUrl: null // Optional
};

window.location.assign(callbackUrl + "?" + $.param(resource));

Native iOS picker via url scheme or universal links

  • If the provider only has a native iOS app (no webapp), the agreed-upon link to the picker must be a url scheme that opens the native app to display the picker.
    • In that case, callbackType will always be url and the callbackUrl will be a url scheme handled by the host.
  • If the provider has both a native iOS app and a webapp, the agreed-upon link should be a Universal Link.
    • In that case, when the host is runnning on iOS and the native host app is installed on the iOS device, the native picker will be displayed.
    • If the host app is not installed, the web picker will be displayed.

Host pickers

To be defined later

Back-end implementations

To be defined later