The WorkTango Embedded Feed integration allows customers to display their company’s WorkTango activity feed on a page within their Intranet.

Prerequisites

  • An Intranet environment that allows you to add custom code. This excludes Google Sites and many other hosted Intranet-as-a-service environments.
  • An experienced developer resource
  • A secret embedded feed key that is only known to you and WorkTango, provided by WorkTango. Our Support team can have one generated for you upon request.

Setup

Before starting, make sure you are able to calculate a keyed-hash authentication message code (HMAC) using the secret embedded feed key every time the embedding page is displayed or refreshed. Static links on plain HTML pages will not work, nor will one-off HMAC tokens from online HMAC generators.

By following these steps, you are creating an expiring URL. It is important for the URL to expire so that it can’t be reused after a short period time by someone who does not have access to your secret key. Also, the HMAC prevents someone from updating any part of the URL without the secret key. This ensures that only the pages you add the code to are authorized to make requests for the feed on your behalf.

  1. Create the URL for the embeddable feed with the needed parameters. format: https://[SUBDOMAIN].youearnedit.com/embed/feed?date=[DATE_TIME]&expire=[SECONDS]
  2. Create the HMAC by hashing the URL above, using SHA-256 and your secret key. The resulting digest must be a hexadecimal digest.
  3. Append the HMAC to the original URL to get the final signed URL. https://[SUBDOMAIN].youearnedit.com/embed/feed?date=[DATE_TIME]&expire=[SECONDS]&token=[HMAC]

You can now use the signed URL to generate an iframe in your intranet.

The following are the required querystring parameters:

  • date: [DATE_TIME]: The date the HMAC token was generated in ISO 8601 UTC format. ex: 20010101T010101Z
  • expire: [SECONDS]: An integer value representing the number of seconds after [DATE_TIME] that this signed request will expire. It is recommended that the expiration window should be a couple of minutes to allow for some time drift between your Intranet server and the YouEarnedIt servers. A value between 60 - 180 seconds is ideal, but as low as possible without triggering HTTP 422 errors.
  • token: [HMAC]: The calculated hexadecimal message digest using SHA-256 and your [FEED_KEY].

Examples

HMAC generation uses libraries that are standard in all modern languages and platforms. Examples for your given platform and language are readily available online.

Basic Example

Given the following parameters:

  • SUBDOMAIN: testdomain
  • DATE_TIME: 20161221T000452Z
  • SECONDS: 60
  • FEED_KEY: 0123456789abcdef01230123456789abcdef0123

The complete iframe URL would be:

https://testdomain.youearnedit.com/embed/feed?date=20161221T000452Z&expire=60&token=9e982c52a9f4784fccbaf1f412c4e59c4eb8d4747e7a7497b357d628846edb6d

Ruby

Generating an embedded feed iframe URL using Ruby’s standard OpenSSL library:

require 'openssl'

subdomain = 'testdomain'
date_time = Time.now.utc.strftime('%Y%m%dT%H%M%SZ')
seconds = 1.minute
feed_key = '0123456789abcdef01230123456789abcdef0123'

feed_url = "https://#{subdomain}.youearnedit.com/embed/feed?date=#{date_time}&expire=#{seconds}"
token = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, feed_key, feed_url)
iframe_url = "#{feed_url}&token=#{token}"

JavaScript

Generating an embedded feed iframe URL using the CryptoJS library for JavaScript

var subdomain = "testdomain";
var dateTime = new Date().toISOString();
var seconds = 60;
var feedKey= "0123456789abcdef01230123456789abcdef0123";

// JavaScript's `toISOString` method returns a string that looks like `2001-01-01T01:01:01.001Z`, but
// the embedded feed controller currently expects the date to be formatted like `20010101T010101Z`
var formattedDateTime = dateTime.substr(0,4) + dateTime.substr(5,2) + dateTime.substr(8,5) +
                        dateTime.substr(14,2) + dateTime.substr(17,2) + 'Z';

var feedUrl = "https://" + subdomain + ".youearnedit.com/embed/feed?date=" + formattedDateTime +
              "&expire=" + seconds;
var token = CryptoJS.HmacSHA256(feedUrl, feedKey);
var iframeUrl = feedUrl + "&token=" + token;

Notes

  • If your secret embedded feed key should ever become compromised, please notify your YouEarnedit Customer Success Manager immediately so a new key can be generated for you.
  • All tokens should be sent as hexadecimal, not base64.
  • We currently only support embedded feeds on production YEI accounts. Sandbox accounts are not supported.
  • The date parameter must be in the format YYYYMMDDTHHIISSZ, e.g. 20010101T010101Z. Any other format will result in a bad parameter error.