---
title: "Reference"
description: "Quikly provides a small javascript code snippet that you can place on your website to feature an activation."
---

import StagingScriptTag from '../../../components/snippets/stagingScriptTags.md'
import ProductionScriptTag from '../../../components/snippets/productionScriptTags.md'

# 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
<StagingScriptTag />

## Production Script Tag
<ProductionScriptTag />

# 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:

```javascript
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:

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

Legacy integrations only accepted one component at at a time:

```javascript
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` | A CSS selector for the element that will contain this component (e.g. `'#quikly-embed'`). |
| `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.
```javascript
qData('ui', {
  ids: ['ABC']
  placements: [{ component: 'feature', root: '#quikly-embed', position: 'drawer' }]
});
```

### Default
Render a Quikly anchored to the bottom of the page.
```javascript
qData('ui', { page: 'default', root: 'quikly-embed', ids: ['example'] });
```

### Hype
Display a full screen Hype activation.
```javascript
qData('ui', { page: 'hype', root: 'quikly-embed', ids: ['example'] });
```

### Drop
Display a small tile featuring a specific Drop.
```javascript
qData('ui', { page: 'drop', root: 'quikly-embed', ids: ['example'] });
```

### Instructions
Display a banner with instructions on what actions are necessary to receive an incentive.
```javascript
qData('ui', { page: 'instructions', root: 'quikly-embed' } )
```

### Redemption
Display a banner with redemption details, typically at the top of your shopping cart page.
```javascript
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).
```javascript
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.
```javascript
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.
```javascript
qData("signup", { email: "name@example.com", requestType: "beaconAPI" });
```


You can also listen for a custom event:
```javascript
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" });
```