Docs
Go to Conductrics.com →
  1. Using Conductrics Markup

Standalone Usage

Using Conductrics Markup without our Local JavaScript API

This page provides explains how to use the Conductrics Markup approach in your pages, using our standalone library called Comma.

📘

Read the Overview First

We recommend reading the overview of Conductrics Markup first.

Quick Start

  1. Include the comma.js library in the page.

  2. Add a "fallback snippet" to the page.

  3. Add the appropriate markup to the page. You can get sample markup for your agent from the Conductrics Admin, as explained in the main Conductrics Markup page in these docs.

  4. Use a code snippet like the following to initialize Comma. Only the api URL is required. See "Options" below for more options you can provide.

// Initialize Conductrics Markup support
var ctrx = new Conductrics.Comma({
	api: 'https://api-v3.conductrics.com/a-123456/v3/agent-api/dt-xyzxyz?apikey=api-1234567890'
}).process()

When the page is loaded, the Comma library will "scan" the page for any variation content. If found, it will contact Conductrics at the URL provided to get variation selections for the visitor, and show/hide the relevant variation content.

If Conductrics can't be contacted for any reason, or if the user has disabled JavaScript or is using an unsupported browser, the first variation is displayed as a "fallback".

A randomly-assigned identifier will be placed in localStorage, which Conductrics uses to remember which variation was selected for the visitor.

Options

General Settings

  • api - Required for standalone usage. The URL at which to communicate with Conductrics. You can get this from the Conductrics Admin for your account. The URL will look something like https://api-v3.conductrics.com/a-123456/v3/agent-api/dt-xyzxyz?apikey=api-1234567890

  • localStorage - Optional. You can use this to specify the key name that will be used to store a unique identifier in localStorage. The default is cp-id.

  • log - Set to true to enable some logging during processing. Default is false (no logging). You can also enable logging by adding an item to localStorage called c-conductrics-debug with value true.

AJAX Options

These options are relevant only if executor is set to ajax (see above).

  • apiUrl - Required if using ajax. The URL at which to communicate with Conductrics. You can get this from the Conductrics Admin for your account. The URL will look something like https://api-v3.conductrics.com/a-123456/v3/agent-api/dt-xyzxyz?apikey=api-1234567890

  • ajaxTimeout - The longest the library should wait for a response from Conductrics. If a response is not received during this time (because of slow network, device offline, etc), the default (first) variation will be displayed. The default is 3000, for 3 seconds.

  • session - An identifier used to identify the visitor's "session". If not provided, an identifier will be generated randomly and set as a cookie (unless the cookies option is disabled, see below) for future page loads / visits.

Cookie Options

These options apply only if you are using the ajax executor, and have not provided your own session identifier via the session option (see above).

  • cookies. Whether to store a generated session identifier as a browser cookie whenever the session option is not provided. The default is true. The remainder of the cookie-related options below pertain only when true.

  • cookieDomain - The domain used when setting the cookie. This affects whether the same ID will be shared amongst your "subdomains". The default is undefined, which means that the cookie will be set for the current page's exact domain only. So, visitors that came to www.yourcompany.com and shop.yourcompany.com would get tracked separately, which is probably not what you want in such a case. To share amongst these "subdomains", specify the main domain with a leading dot, so cookieDomain:".yourcompany.com" or similar.

  • cookieMaxAge - How long the browser should retain the cookie, in seconds. The default is to retain for one year (31536000 seconds).

  • cookiePath - The path portion of the cookie. The default is / for all pages.

  • cookieName - The name of the cookie that gets set. The default is cp-id.

Markup Options

These options allow you to customize the HTML markup attributes that this library looks for in your pages. If you have added the markup support to your pages via the Conductrics Admin, you can set these properties there, so these properties are mainly of interest only if you are adding the markup support library yourself (as opposed to via a standard Conductrics script distribution).

  • variationClass - The CSS class name used to pre-hide variations during initial page load. This class is then removed from the appropriate DOM elements when a variation is selected, thus revealing (un-hiding) the visuals for the selected variation. The default is c-variation, but you can change this to some other CSS class name if you prefer.

  • doneClass - The CSS class name that the markup processor will add to the page <body> when it completes its initial work - that is, when it is done showing/hiding elements, etc. The default is c-markup-done.

  • fallbackClass - The CSS class name that the markup processor will check before starting its initial work of showing/hiding elements, etc. The default is c-markup-fallback. If the page <body> has this attribute, the markup process takes this as a signal to abort its processing without making changes.

  • agentAttribute - The attribute that you'll use in your page's HTML markup to identify portions of the page as variation content. The default is data-agent.

  • goalAttribute - The attribute that you'll use to identify elements of the page as goal triggers. The default is data-goal. The content of the attribute should contain the goal code, with an optional numeric reward value (separate the goal code from the numeric value with a space), so something like data-goal="goal-1" or data-goal="goal-1 29.99".

  • goalOnAttribute - The attribute that you'll use to specify which event should be listened for to trigger the goal. The default is data-goal-on. The content of the attribute should be a browser event name, so something like data-goal-on="mouseover". If the attribute is not present, click will be assumed as a default.

If you need more control, you can also adjust the following:

  • agentParser - For custom scenarios where the agent/variation codes aren't straightforwardly available in a single HTML attribute, you can provide a function that is responsible for "parsing" out the agent code and variation code from an element's attributes or child elements, etc. Your function should accept a DOM element and should return an object like {a:"my-agent", v:"variation"}. By default, an internal implementation is used that reads the value of the agentAttribute attribute and "parses" that value as a space-delimited string to get the agent and variation codes, so data-agent="my-agent A" is parsed as {a:"my-agent", v:"A"}.

  • goalParser - Similarly, you can provide a custom "parser" function for extracting the goal code, explicit numeric value (if any), and event that should be listened for. Your function should accept a DOM element and should return an object like {g: "my-goal", e: "click", v: 29.99} or whatever is appropriate (the v may be omitted when there is no conceptual numeric reward to provide). By default, an internal implementation is used that reads the goal code (and optional reward) via goalAttribute, and the event from goalOnAttribute.

Updated 8 months ago