---

Example: contextual segments API

Shows how to call ctxSegments() to classify a page URL and inspect the classifications the DCN returns for it: taxonomy categories (e.g. against the IAB Content Taxonomy) and/or free-form keywords, depending on which classifiers the DCN has enabled.

// Classify the URL of the current page (defaults to window.location.href):
optable.instance.ctxSegments();

// Or classify an explicit URL:
optable.instance.ctxSegments("https://optable.co/");

The response is a ContextualSegmentsResponse:

{
  classifications: {
    categories: [{ id, name, score, taxonomy }],
    keywords: [{ keyword, prominence }],
  },
}

The classifications object groups results by classification method, and the DCN includes only the methods it has enabled. Two methods exist today:

categories: taxonomy classifications

Field	Description
id	Category id within its taxonomy (e.g. an IAB category id).
name	Human-readable category name.
score	Relevance score from 0 to 1.
taxonomy	Id of the taxonomy the category belongs to (e.g. iab_ct_3_1).

keywords: free-form terms extracted from the page

Field	Description
keyword	The extracted keyword text.
prominence	Per-page ordinal rank (1 = most prominent), not a score, so prominences are not comparable across pages.

Alternatively, configure the SDK with initContextual set to a callback. The SDK will automatically call ctxSegments() for the URL of the current page on initialization, and invoke the callback with the response as soon as it's available — no second call required:

optable.instance = new optable.SDK({
  host: "ca.edge.optable.co",
  site: "web-sdk-demo",
  node: "optable",
  cookies: false,
  initContextual: function (response) {
    // Use the response, or read it later via optable.instance.ctxTargetingKeyValues().
    console.log("contextual segments:", response);
  },
});

Note: the URL requested must have been classified by the DCN. For the demo DCN used by this page, the URL https://optable.co/ should have been classified, so you can try that.

Result

Raw response

GAM targeting key-values

Derived from the cached ctxSegments() response via optable.instance.ctxTargetingKeyValues(), this object can be passed straight to Google Ad Manager via googletag.pubads().setTargeting(key, values):

var loadGAM = function (tdata = {}) {
  window.googletag = window.googletag || { cmd: [] };
  googletag.cmd.push(function () {
    for (const [key, values] of Object.entries(tdata)) {
      googletag.pubads().setTargeting(key, values);
    }
    googletag.pubads().refresh();
  });
};

ctxTargetingKeyValues() reads the response cached on the SDK instance, so the instance should be initialized with the initContextual: true option. That way the contextual segments are fetched during initialization, and the cache is likely to be populated by the time loadGAM() runs:

loadGAM(optable.instance.ctxTargetingKeyValues());

By default the returned map has one key per taxonomy the DCN classified into (keyed by the raw taxonomy value) plus the page's keywords under ctx_kw. For example, ctxTargetingKeyValues() might return:

{
  "iab_ct_3_1": ["53", "91", "58", "115", "90", "52"],
  "ctx_kw": ["advertising", "programmatic", "ad tech"]
}

If you want loadGAM() to run as soon as the contextual segments arrive — without making a second ctxSegments() call — pass a callback to initContextual. The SDK fires the contextual request automatically during initialization and invokes the callback with the response, populating the cache before ctxTargetingKeyValues() reads from it:

optable.instance = new optable.SDK({
  host: "ca.edge.optable.co",
  site: "web-sdk-demo",
  node: "optable",
  cookies: false,
  initContextual: function (response) {
    loadGAM(optable.instance.ctxTargetingKeyValues());
  },
});

If you are not using initContextual at all, fetch the segments explicitly and pass the result to loadGAM() once ctxSegments() resolves (falling back to an untargeted load on error):

optable.cmd.push(function () {
  optable.instance
    .ctxSegments()
    .then(loadGAM)
    .catch((err) => {
      loadGAM();
    });
});

By default each taxonomy is emitted under its own value as the GAM key. Pass a map to ctxTargetingKeyValues() to rename keys and allow-list which taxonomies are emitted — only taxonomies present in the map are included:

// Emit only the "iab_ct_3_1" taxonomy, under the GAM key "ctx_iab":
loadGAM(optable.instance.ctxTargetingKeyValues({ iab_ct_3_1: "ctx_iab" }));

Keyword classifications are also emitted, by default under the GAM key ctx_kw. The values are the page's keywords ordered by prominence (most prominent first), capped to the top 10, and sanitized to GAM's value rules (lowercased, reserved characters stripped, truncated to 40 characters). Pass keywordKey to rename the key or maxKeywords to change the cap, or set keywordKey to an empty string to opt out of keyword key-values entirely:

// Rename the keyword key and emit only the top 5 keywords:
loadGAM(optable.instance.ctxTargetingKeyValues({ iab_ct_3_1: "ctx_iab" }, { keywordKey: "kw", maxKeywords: 5 }));

// Opt out of keyword key-values:
loadGAM(optable.instance.ctxTargetingKeyValues(undefined, { keywordKey: "" }));

Home | Contact | Terms | LinkedIn | Twitter