INSTALLATION

The recommended way to install is via NPM and using a NPM-compatible bundler solution, like browserify. Then you can do:

npm install --save glimr-sdk

You can also embed the JS file directly using our CDN. A link to the latest minified version can be found here:

https://github.com/KatalysatorAB/GlimrSDK-JS

The SDK exposes a global instance named Glimr. If you are using browserify or any similar bundling solutions, what you need to do is simply:

var Glimr = require("glimr-sdk");

Tags

Google Tag Manager

Parsing/Stringifying/Serializing/De-serializing


 

RETREIVING AUDIENCES

void Glimr.getTags( string clientId, function(array, object) callback )

Fetch all tags associated with the current browser client. The callback should accept 1 array and 1 object parameter. Depending on the version of the Glimr API used, the object parameter might be empty.

Glimr.getTags("YOUR_CLIENT_ID", function(tags, tagMappings) {
  console.log("Tags for client:", tags);
  console.log("... :", tagMappings);
});

ic_report_problem_2x.png

Note

If you call setTagCacheTimeInSeconds the tags will be cached for that duration, and not make a network request until after the time. Otherwise getTags-call is cached for the duration of the page load and will be emptied on page load. Calling it multiple times will only result in one call to the Glimr servers.


.setTagCacheTimeInSeconds

  • number Glimr.setTagCacheTimeInSeconds( number desiredSecondsToCache )
  • number Glimr.getTagCacheTimeInSeconds( )

The tags from Glimr.getTags can be cached for a duration of up to 5 minutes. The tags don't change too often so it's a good idea to limit network traffic on the client.

Glimr.setTagCacheTimeInSeconds(300);

// Max cache time is 5 minutes because otherwise you risk losing tags
// Passing anything > 300 will become 300
Glimr.setTagCacheTimeInSeconds(600);
console.log(Glimr.getTagCacheTimeInSeconds());
// ... 300

.getCachedURLTags

array Glimr.getCachedURLTags( string clientId )

Glimr crawls your web property and knows which URL indicates a set of tags, based on filters you setup in the dashboard. The Glimr SDK can download and cache this database in an efficiant manner, and you can use it to get tags without having to make a network request. To fetch the tags associated with the current browser URL you call Glimr.getCachedURLTags which does a fast synchronous lookup.

var tags = Glimr.getCachedURLTags("YOUR_CLIENT_ID");
console.log("Cached tags", tags);

Note: This method used to be called .getCachedTags. For backwards compatibility it will exist until the next major release.

.getCachedBehaviorTags

array Glimr.getCachedBehaviorTags( string clientId ): Array | boolean

If Glimr.setTagCacheTimeInSeconds has been called this method can be used to peek into the cache without calling Glimr.getTags. If the cache is still valid, an array will be returned, otherwise false.

Note: This returns a different class of tags than Glimr.getCachedURLTags. Behavior tags are based on the user and not the current web URL.

var tags = Glimr.getCachedBehaviorTags("YOUR_CLIENT_ID");
console.log("Cached tags", tags);

.getCachedBehaviorTagsAndUpdateInBackground

array Glimr.getCachedBehaviorTagsAndUpdateInBackground( string clientId, options: { onUpdate: (tags: Array) => void}): Array<string>

For some implementors tags need to be used in a synchronous manner, but still need to be updated when possible. Also invalidated tags should still be used. This method works for that use case.

Glimr.setTagCacheTimeInSeconds(300);
var tags = Glimr.getCachedBehaviorTagsAndUpdateInBackground("YOUR_CLIENT_ID");

An optional options object can be passed in with an onUpdate callback that is passed as a callback to the Glimr.getTags call

Glimr.setTagCacheTimeInSeconds(300);

var oldTags = Glimr.getCachedBehaviorTagsAndUpdateInBackground("YOUR_CLIENT_ID", {
  onUpdate: function(newTags) {
    console.log("tags are updated. New tags", newTags);
  }
});

 

CACHED URL TAGS

Glimr crawls your web property and knows which URL indicates a set of tags, based on filters you setup in the dashboard. The Glimr SDK can download and cache this database in an efficiant manner, and you can use it to get tags without having to make a network request. To fetch the tags associated with the current browser URL you call Glimr.getCachedURLTags which does a fast synchronous lookup.


ic_report_problem_2x.png

This is only for tags that can be predetermined for a host

Glimr.getTags and Glimr.getCachedURLTags return different type of tags. Glimr.getTags will always return the sum of both calls, whereas Glimr.getCachedURLTags will tags only relating to the URL (not user behavior).


The flow is:

  1. User opens page, Glimr.getTags is called
  2. User navigates to another page
  3. Calling Glimr.getCachedURLTags will return tags that could be prematurely determined for the current URL

Fetches all tags associated with the current browser client.

var cachedURLTags = Glimr.getCachedURLTags("YOUR_CLIENT_ID");
if (cachedURLTags) {
    console.log("cachedURLTags", cachedURLTags);
} else {
    Glimr.getTags("YOUR_CLIENT_ID", function(tags) {
        console.log("tags", tags);
        console.log("URL cache is now", Glimr.getCachedURLTags("YOUR_CLIENT_ID"));
    });
}

 

GOOGLE TAG MANAGER

Google Tag Manager is supported out of the box. All you need to do is create a custom HTML tag with the following snippet.

<script src="https://storage.googleapis.com/glimr-static/glimrsdk-js/3/glimr.min.js"></script>
<script>
Glimr.getTagsAndPushToDataLayer("YOUR_CLIENT_ID");
</script>

ic_report_problem_2x.png

NOTE

Be sure to replace YOUR_CLIENT_ID with the web pixel ID from the Glimr Dashboard.


QZP9kRTL6bYQNQHxBaIw_event.png
kF5tWoUeTfSTqana4eIj_variable.png

To use the variable in a custom HTML-tag you use the {{}}-notation to fetch variables.

<script>
var glimrTags = {{glimrTags}};
alert("Glimr tags: " + glimrTags.join(", "));
</script>

 

SENDING TAGS TO AN ADSERVER

Your glimr tags will live very happily in your ad server. To get there, they need to be encoded in a compliant manner. This library provides some tools to make that easy.

The biggest hurdle is how to encode your tags. Since they might come back as an array of strings, or a dictionary of arrays, we have tools to encode both into HTTP spec compliant query strings.

.objectToQuery


string Glimr.objectToQuery( object value )

Take an object/dictionary and convert to a query string. It will not modify array keys (postfix them with []), that is up to the implementer to make sure the keys are postfix'd.

.arrayToQuery


string Glimr.arrayToQuery( array value, string key )

Take an array and convert to a query string. The second argument is a string of which will become key for the values.

It will not modify keys like other frameworks might (i.e postfix them with []), that is up to the implementer to make sure the keys are postfix'd.

var tags = ["a", "bcd", "ef"];

var queryString = Glimr.arrayToQuery(tags, "my_key");

// my_key=a&my_key=bcd&my_key=ef

.queryToObject


object Glimr.queryToObject( string )

Parse a query string into an object. Since multiple entries are supported per key, it always creates an array key. For example:

var queryString = "foo=bar&foo=baz&hello=world";

var object = Glimr.queryToObject("foo=bar&foo=baz&hello=world");

/*
{
  foo: ["bar", "baz"],
  hello: ["world"] // note that hello is also an array
}
*/

.escapeStringForQuery


string Glimr.escapeStringForQuery( string value )

This is more of a helper that might be useful for very custom stuff. It's what Glimr.objectToQuery and Glimr.arrayToQuery use to encode the values.


ic_report_problem_2x.png

Don't call this manually

... Unless you really need it. Escaping and unescaping is done behind the scenes by arrayToQuery/objectToQuery


Usage is easy:

var escapedString = Glimr.escapeStringForQuery("hello world");

// hello%20world

.unescapeStringForQuery


string Glimr.unescapeStringForQuery( string value )

Does the opposite of Glimr.escapeStringForQuery:

var string = Glimr.unescapeStringForQuery("hello%20world");

// hello world

 

ENRICHMENT

You can enrich your own data in Glimr by passing in values for aggregation by the Glimr cloud. Currently only user position is supported. All values defined need to be flushed back to our servers. This is done with a call to Glimr.getTags.

.storePosition


Glimr.storePosition( position: { longitude: number | string, latitude: number | string } ): void

This signals the position of the user. The passed in object must have numeric longitude and latitude members. They can either be numbers or strings that can be parsed with parseFloat.


ic_info_black_24dp_2x.png

NOTE

Stored values are not stored until flushed by a call to Glimr.getTags. See the example below to learn how to use it.


Example


Here is an example using navigator.geolocation to ask for local news and weather.

function getPosition() {
  navigator.geolocation.getCurrentPosition(function(position) {
    // Store position
    Glimr.storePosition({
      latitude: position.coords.latitude,
      longitude: position.coords.longitude
    });

    // Flush position with request to server
    Glimr.getTags("YOURID", function(tags) {
      // use new possibly more accurate tags
      console.log("Tags are now", tags);
    });
  });
}
function getPosition() {
  navigator.geolocation.getCurrentPosition(function(position) {
    // Store position
    Glimr.storePosition({
      latitude: position.coords.latitude,
      longitude: position.coords.longitude
    });

    // Flush position with request to server
    Glimr.getTags("YOURID", function(tags) {
      // use new possibly more accurate tags
      console.log("Tags are now", tags);
    });
  });
}