Reference

Loading the SDK

This script tag must be placed on any page you want to include Quikly functionality. You must include your unique brand key in the “config” command. Once this is in place, you can make additional qData commands to render specific content or track specific activity.

Staging Script Tag

<script>
(function (w, d) {
  w.qData || (w.qData = function() {
    (w.qDataLayer = w.qDataLayer || []).push(arguments);
  });
  s = d.createElement('script');
  s.src = 'https://pixel.quiklydemo.com/embed/js';
  s.async = true;
  f = d.scripts[0];
  f.parentNode.insertBefore(s, f);
})(window, document);
qData("config", "m/your-brand-key"); // your staging brand key
</script>

Production Script Tag

<script>
(function (w, d) {
  w.qData || (w.qData = function() {
    (w.qDataLayer = w.qDataLayer || []).push(arguments);
  });
  s = d.createElement('script');
  s.src = 'https://pixel.quikly.com/embed/js';
  s.async = true;
  f = d.scripts[0];
  f.parentNode.insertBefore(s, f);
})(window, document);
qData("config", "m/your-brand-key"); // your production brand key
</script>

Command Summary

After placing the script tag on your site, you control what is displayed or when activity is completed by passing commands to the qData function. These calls take the format:

qData(command, value);

where the command is one of 'config', 'ui', or a custom event name configured for your campaign.

The ui commands take an object as the second argument that defines the activation IDs and what components to display. Here we use the placements option to define each component separately:

qData('ui', {
  placements: [
    { component: 'feature', root: 'quikly-embed', position: 'inline' }
  ]
});

Legacy integrations only accepted one component at at a time:

qData('ui', { page: 'drop', ids: ['example'], root: 'my-container' });

Commands

These commands are passed in as the first parameter to the qData function.

Command	Description
config	Specify your brand key.
ui	Display an interface element.
[event key]	A custom event name used to track activity.

UI Commands

These keys can be specified in the value object as the second argument to the qData function.

Value Keys	Description
placements	An array of component definitions. When using placements, do not use the page or root keys.
ids	An array of strings specifying the campaigns you’d like to render.
email	The email address of the current user. Not required.
page	If rendering a legacy component, this specifies what component to display. Not compatible with placements.
root	If rendering a legacy component, the DOM ID of the element that will contain the rendered component. Do not use with placements.

Placement Configuration

Value Keys	Description
component	The name of the component, i.e. ‘feature’, ‘teaser’.
root	The DOM ID of the element that will contain this component.
position	How the component should be wrapped, i.e. ‘banner’, ‘drawer’, ‘fixedCenter’, ‘inline’, or ‘skyscraper’
open	Set default open state, used with drawer or fixedCenter positions.
template	Override the components template.
append	Boolean Append the component to the DOM root element rather than replacer its contents.
prepend	Boolean Prepend the component to the DOM root element rather than replacer its contents.

Common Configurations

Placements

Display any combination of elements on the page at the same time. Each element in the placements array should define the component, position (i.e. drawer, modal, banner), and it’s target element. For example, this will render the “feature” component in a drawer into the “quikly-embed” DOM element.

qData('ui', {
  ids: ['ABC']
  placements: [{ component: 'feature', root: 'quikly-embed', position: 'drawer' }]
});

Default

Render a Quikly anchored to the bottom of the page.

qData('ui', { page: 'default', root: 'quikly-embed', ids: ['example'] });

Hype

Display a full screen Hype activation.

qData('ui', { page: 'hype', root: 'quikly-embed', ids: ['example'] });

Drop

Display a small tile featuring a specific Drop.

qData('ui', { page: 'drop', root: 'quikly-embed', ids: ['example'] });

Instructions

Display a banner with instructions on what actions are necessary to receive an incentive.

qData('ui', { page: 'instructions', root: 'quikly-embed' } )

Redemption

Display a banner with redemption details, typically at the top of your shopping cart page.

qData('ui', { page: 'redemption', root: 'quikly-embed' });

Reward

Display an overlay with reward details. If a participant has already received an incentive, then the reward will display right away. Otherwise, this sets up the page to display the reward as soon as one is granted (i.e. via a Swap event, outlined below).

qData('ui', { page: 'reward' } )

Event Commands

Track arbitrary events, typically used to grant an incentive/reward/offer with Swap, or a heads-up within Hype. Quikly will provide you with the appropriate event name to use in the first parameter. The second parameter is optional but can be used as a payload to track alongside the event. This can be useful for reporting or audit purposes.

qData("signup", { email: "name@example.com" });

If you want to track the event on a link click or form submit, set the requestType to "beaconAPI" to allow the request to finish even if the page is unloaded upon navigation.

qData("signup", { email: "name@example.com", requestType: "beaconAPI" });

You can also listen for a custom event:

window.addEventListener('qDataComplete', function(event) {
  console.log('Event: ' + event.detail); // { code: "signup", args: { email: "name@example.com" } }
});
qData("signup", { email: "name@example.com", requestType: "beaconAPI" });