Configuration Reference¶

This document covers the format and schema for the configuration of a token inside the SDK.

Overall Schema¶

The overall schema at a high level is made up of two parts:

the plugins you want to have automatically installed
the trigger and tag configuration for your token

{
    plugins ["plugin names", "to", "install"],
    tagConfig: {
        tags: [
            "type": "TagType",
            "content": {/*tag configuration*/},
            "installationType": "ONCE | MANY | PER"
        ],
        triggers: {
            "rs": [
                {
                    fov: failOnValue,
                    tid: tagId,
                    en: eventType,
                    rg: [rulegroup_index]
                }
            ],
            "rg": [
                [rule_index]
            ],
            "r: [
                {
                    k: key,
                    o: operation,
                    v: value
                }
            ]
        }
    }
}

Tag Configuration¶

Tag configuration has three parts:

Tag Type
Tag Content
Tag Installation Type

We'll cover each of these below.

Tag Type¶

The tag type determines what implementation we apply for the tag, and what the tag content shoudl consist of.

The different tag types are: - "PLUGIN" - call a plugin method with some parameters - "VIS" - trigger watching element(s) for visibility rules - "EVENT" - fire an event to the SDK - "HTML" - render HTML to the DOM in an optional location

Tag Content¶

Each type has its own content configuration; the table below shows the fields and details for each tag type:

Tag Type	Description	Contents
`"PLUGIN"`	`pluginName`: string `methodName`: string `arguments`: array of arguments	Calls the plugin and method provided with the arguments provided. Arguments can be JQ queries against the datalayer.
`"VIS"`	`selectorType`: string (`"ID"` or `"CSS"`) `selector`: string (the ID or CSS selector) `trackDuration`: boolean `trackDomChange`: boolean `frequency`: string (same as Tag Installation Type) `ratio`: number (0 - 100) `screenDuration`: number (milliseconds) `triggerId`: string	Watches for the elements that match the selector until they meet the configured criteria.
`"EVENT"`	`eventType`: string `eventProperties`: key-values to include with the event	Fires an event with the specified type and properties. Both the type and properties can be JQ queries against the datalayer.
`"HTML"`	`location`: string, optional `html`: string	Renders an HTML string as content at the specified location (CSS selector). If not provided, the location is appending a child to `document.body`. The HTML can include JQ queries against the datalayer using double curly brackets: e.g. `{{$.jq.query}}` syntax.

Tag Installation Type¶

Tags have 3 types if installations, in the context of a pageview:

"ONCE": fire this tag once per pageview
"PER": for tags that can have multiple elements or targets (e.g. "VIS"), this will fire the tag once per each element or target
"MANY": fire this tag each time its triggered

Triggers¶

Triggers are made up of three things:

The Tag they will fire when their ruleset evaluates to "true"
The ruleset they evaluate against datalayer changes
The eventType they're looking to evalulate against, as an optimization/filter

Rulesets¶

Rulesets are made of Rulegroups, and Rulegroups are made up of Rules. Any logical statement can be made up of a combination of ands and ors.

These logical statements come in two varieties:

Matching EVERY Rulegroup: Rulegroups are combined with and and Rules are combined with or
Matching ANY Rulegroup: Rulegroups are combined with or and Rules are combined with and

Therefore, here's how the structure maps to the configuration:

Rulesets have an fov variable, which is false for EVERY and true for ANY. They also have a list of Rulegroups they apply the fov to.
Rulegroups have a list of Rules they evaluate. Like Rulesets, they apply the opposite fov as Rulesets -- simply put they use rulegroup.fov = !ruleset.fov.
Rules are made up of a key (k) -- usually a JQ query; a value (v) -- usually an explicit value to test against the JQ query's result; and an operation (o), which can be any of the following:

Rule Operations:

Operation Type	Description
`"rx"`	matches regex
`"nrx"`	does not match regex
`"ex"`	checks existance
`"nex"`	checks for nonexistance
`"eq"`	equality
`"neq"`	inequality
`"ct"`	contains
`"nct"`	does not contain
`"sw"`	starts with
`"nsw"`	does not start with
`"ew"`	ends with
`"new"`	does not end with
`"nle"`	not less than or equals
`"gt"`	greater than
`"nge"`	not greater than or equals
`"lt"`	less than
`"nlt"`	not thess than
`"ge"`	greater than or equals
`"ngt"`	not greater than
`"le"`	less than or equals

Example Ruleset¶

For example, let's say we want to target pages viewed on a page that has a URL path that includes inventory, and include the querystring parameter search.

To do so, we'd start with the ruleset:

{
    rs: [
        {
            en: "Page Viewed", // target the pageview event type
            fov: true, // we want to match both rulegroups
            tid: TagID,
            rulegroups: [0, 1] // we have two rulegroups
        }
    ]
}

Then the rulegroups:

{
    rg: [
        [0], // first rulegroup to match first rule
        [1] // second rulegroup to match second rule
    ]
}

Then the rules:

{
    r: [
        {
            k: "$.state.page.url.path", // get the url path
            o: "ct", // that contains
            v: "inventory" // this value
        },
        {
            k: "$.state.page.url.query.search", // get the querystring `search`
            o: "ex", // verify it exists
            v: null // not needed for `ex` and `nex` operations, so we set it to null
        }
    ]
}

Let's check out some URLs then:

The URL https://mydealer.com/inventory.html?search=civic would evaluate to "true"
The URL https://mydealer.com/inventory.html?model=civic would evaluate to "false"

Now you should have a good idea on how to configure the SDK.

You don't have to do this manually!

If you configure your tags and triggers via the Orbee Platform UI, you don't need to configure the SDK manually -- your installation will automatically be configured for you!

Last update: 2023-04-19