Tag Wizard: Custom Code Settings

A complete reference for every setting available in the Tag Wizard’s Custom Code block, for use alongside Tag Wizard: Custom Code.

This is a reference for every setting available in the Tag Wizard’s Custom Code block, for use alongside Tag Wizard: Custom Code.

NoteAny method name preceded with an underscore is subject to change and shouldn’t be used.

Quick reference

Setting	Type	Default
`autoRun`	Boolean	`true`
`autoSwap`	Boolean	`false`
`campaignIdOverrideParam`	String	`null`
`cacheWasReset`	Boolean	Read-only; `false` in the Custom Code block
`cookieDays`	Integer	`1` (library) / your Attribution Window field value (Custom Code block)
`cookieNames`	Array	`null`
`defaultCampaignId`	String	`null`
`destinationAsId`	Boolean	`false`
`destinationSettings`	Object	`null`
`defaultDestinationName`	String	`undefined` (requires a campaign ID to be set)
`doNotSwap`	Array	`{}`
`integrations`	Object	`{}`
`maxWaitFor`	Integer	`1000ms` (library) / your Wait Time field value (Custom Code block)
`numberSelector`	String	`null`
`numberToReplace`	String, Array, or Object	`null` (library) / `{}` (Custom Code block)
`onComplete`	Function	`null`
`onCompleteOverride`	Function	`null`
`onPhoneNumberFound`	Function	`null`
`poolParams`	Object	`{}`
`requiredParams`	Object	`null` (library) / `{}` (Custom Code block)
`waitForData`	Array	`[]` (library) / your enabled custom data fields (Custom Code block)

Setting details

autoRun (Boolean, default: true)

Set to false if you don’t want InvocaJS to run on page load — useful if you have a specific load event, or use a Single Page App framework like React or Angular where InvocaJS should run after rendering completes.

options.autoRun = false;
return options;

Then trigger Invoca.PNAPI.run() when your page or application is ready — typically via an event listener or library render callback. For example, if a “Contact Us” widget with a number loads dynamically, trigger Invoca.PNAPI.run() once that widget appears.

NoteautoRun doesn’t need to be false to call Invoca.PNAPI.run().

autoSwap (Boolean, default: false)

Set to true to have InvocaJS automatically detect and replace all numbers on the page — useful if you have a large or unknown list of numbers. If true, numberSelector and numberToReplace aren’t needed.

options.autoSwap = true;
return options;

campaignIdOverrideParam (String, default: null)

The query string name used to identify a Campaign ID.

options.campaignIdOverrideParam = "invsrc";
return options;

cacheWasReset (Boolean, read-only)

Indicates whether the attribution cache has been reset, based on the UI’s reset-attribution option. Read-only, available in the Custom Code block.

if (options.cacheWasReset){
  // special logic when a new attribution window starts, e.g. create a custom cookie
}
return options;

cookieDays (Integer)

Number of days for the cache’s time-to-live.

function getAttributionWindowFromSource(){
  // logic to return a variable attribution window
  return 5;
}

cookieNames (Array, default: null)

A list of cookie names (as strings) to automatically capture as RingPool Parameters.

options.cookieNames = ["session", "k_id"];
return options;

defaultCampaignId (String, default: null)

The campaign ID to use for any number on the page without a specific campaign set via the UI or numberToReplace. Case-sensitive — "inv123" and "INV123" are different values.

options.defaultCampaignId = "sales";
return options;

destinationAsId (Boolean, default: false)

Strips special characters and uses the detected destination phone number’s digits as the campaign ID.

NoteRequires an Invoca campaign with an explicit ID set for each number.

options.destinationAsId = true;
return options;

destinationSettings (Object, default: null)

Configures Destination-related behavior:

paramName: the Custom Data Field where Invoca sets the phone number that was replaced.
matchTollFreeNumbers: auto-generates a Destination to match an unknown toll-free number.
matchLocalNumbers: auto-generates a Destination to match an unknown local number.

defaultDestinationName (String, default: undefined)

Specifies a Destination name within a campaign to apply to all detected numbers on the page. Requires a campaign ID to be set.

doNotSwap (Array, default: )

A list of numbers to exclude from tracking via autoSwap or numberToReplace.

options.doNotSwap = ["###-###-####"]
return options

integrations (Object, default: )

Enables integrations supported directly by InvocaJS. Some require account-specific parameters; others just need the integration name set to true. Supported integrations:

Integration	Default paramName	Required options
`googleAnalytics`	`g_cid`	`true`
`optimizely`	`goal_url`	`{goalName: "goal_name", goalId: "goal_id", goalValue: "goal_value"}`
`adobeAnalytics`	`mcid`	`{username: "user name here"}`
`adobeAnalyticsLegacy`	`s_vi`	`true`
`hubspot`	`hubspotutk`	`true`

Each integration’s options follow the same shape as waitForData (below), except the on function is defined internally and paramName defaults per the table above. paramName, fallbackValue, and timeout can be overridden per integration — the default timeout is 1000ms if unspecified. To override defaults, pass a config object instead of true:

// Instead of:
googleAnalytics: true

// You can pass:
googleAnalytics: { fallbackValue: "n/a", timeout: 500 }

Combining multiple integrations:

options.integrations = {
  googleAnalytics: true,
  optimizely: {goalName: "call", goalId: "xxxx", goalValue: "1", timeout: 2000}
}
return options;

Setting integrations one at a time:

options.integrations.googleAnalytics = true;
options.integrations.optimizely = {goalName: "call", goalId: "xxxx", goalValue: "1"};
return options;

Fallback value: every integration defaults to a fallback value of "not_found", shown in reporting when the integration’s parameter isn’t found on the page. To report a blank value instead, set the fallback value to null:

options.integrations = {
  googleAnalytics: { fallbackValue: null },
  adobeAnalytics: { username: "username", fallbackValue: null },
  hubspot: { fallbackValue: "n/a" }
}

maxWaitFor (Integer, default: 1000ms)

Maximum milliseconds to wait before starting the Invoca number request, when integrations, waitForData options, or custom data sources (data layer/cookie) haven’t returned data yet. The number request fires as soon as all data is found or this timeout is reached.

numberSelector (String, default: null)

A CSS selector for phone number HTML elements. Accepts one selector (.phoneNumber) or several (.phoneNumber, #contact-us-number).

options.numberSelector = ".phoneNumber";
return options;

numberToReplace (String, Array, or Object)

Specifies which number(s) to replace and which campaign ID to use for each. Accepts an object keyed by number, with campaign ID as the value:

{"888-999-1010": 'campaignIdHere'}

Can also be a comma-separated string or array of strings, but only if you’re completely overriding the Tag Wizard UI rather than merging with it:

"888-999-1010, 777-888-9999"
["888-999-1010", "777-888-9999"]

Merging with existing UI data (UI takes precedence):

var customNumberToReplace = {
  "888-555-1234": myPrimaryCampaignId(),
  "888-555-6789": mySecondaryCampaignId()
};

var mergedNumbers = Invoca.PNAPI.extend({}, customNumberToReplace, options.numberToReplace);
options.numberToReplace = mergedNumbers;
return options;

Using the array/string version:

options.numberToReplace = ["888-999-1010", "777-888-9999"];
options.defaultCampaignId = "sales";
return options;

onComplete (Function, default: null)

Called when Invoca finishes running, after default number replacement completes. Argument: mapping (array of objects for each unique number-replace request on the page). Pass a reference to a named function, not a function call — use functionName, not functionName().

// Using an existing named function:
options.onComplete = myCustomEventCallback;
return options;

// Using an inline anonymous function:
options.onComplete = function(){
  $(".phone-number").fadeIn();
};
return options;

See Tag Wizard: Custom Code for the number-flicker use case.

onCompleteOverride (Function, default: null)

Called when Invoca receives a response from the server. If defined, Invoca won’t replace any phone numbers — this function is responsible for updating them on the page instead. Arguments: batchId, mapping.

options.onCompleteOverride = function(batchId, mapping){
  if (mapping.length === 1){
    var numberResponse = mapping[0];
    console.log("Received exactly one response back. Status: " + numberResponse.status + ", formatted number: " + numberResponse.formattedNumber);
  } else {
    console.log("Received " + mapping.length + " responses back.");
  }
};
return options;

onPhoneNumberFound (Function, default: null)

Accepts a function called with two arguments:

node: the DOM node detected as containing a phone number.
request: the request object built for that phone number.

A valid request object includes:

advertiser_campaign_id_from_network (required, must be unique)
request_id (required)
destination_name (optional)
params (optional), which can include invoca_detected_destination

Example request object:

{
  request_id: "adv_rp",
  advertiser_campaign_id_from_network: "adv_rp",
  params: { custom: "value" }
}

Acceptable return values:

false: the number in the current node won’t be swapped.
A valid request object: the number swaps, using the information in that object.
Anything else, or nothing: the number swaps using the information in the original request.

poolParams (Object, default: )

Key/value attribution parameters to capture, where the key is the Custom Data partner API name (or RingPool parameter name).

// options.poolParams is already an Object — don't overwrite it directly
options.poolParams.domain = window.location.hostname;
options.poolParams.referrer = document.referrer;
return options;

// Reading a cookie:
options.poolParams.session_id = Invoca.Tools.readCookie('session');
return options;

// Merging a new set with existing params:
options.poolParams = Invoca.PNAPI.extend({}, options.poolParams, {
  domain: window.location.hostname,
  referrer: document.referrer,
  session_id: Invoca.Tools.readCookie('session')
});
return options;

requiredParams (Object)

Key-value pairs representing query string names and values. The integration runs if any are met. When a value is *, any passed value counts as true.

// Runs if utm_medium = "Search" OR any utm_source value is present
options.requiredParams = {utm_medium: "Search", utm_source: "*"};
return options;

See Tag Wizard: Custom Code for requiring multiple parameters together.

waitForData (Array)

Configuration objects for collecting data not immediately available on page load, such as a cookie set by another integration or a data layer variable. Each object’s structure:

on (function, required): returns the desired value, or null/undefined if not yet available (so Invoca keeps trying).
paramName (string, required): the parameter name sent to Invoca (Custom Data partner API name or RingPool parameter name).
fallbackValue (string, optional): value to use if the timeout is reached with no data. Defaults to "not_found".
timeout (integer, optional): milliseconds to poll before giving up — the highest timeout across all configs is used. Falls back to maxWaitFor if unspecified.

waitForData: [
  {on: getUserId, paramName: "user_id", fallbackValue: "n/a", timeout: 500},
  {on: getOtherId, paramName: "other_id"},
  {on: getOtherIdTwo, paramName: "other_id_2", fallbackValue: null}
]

All data is captured in parallel; Invoca polls until every callback returns or the timeout is reached. If on isn’t a function, or paramName is missing, Invoca logs a console warning but continues running with any other configs.

// Append to the existing list — don't overwrite it, so other custom data fields still capture correctly
options.waitForData.push(
  {on: getUserId, paramName: "user_id", fallbackValue: "empty", timeout: 500}
);
options.waitForData.push(
  {on: getOtherId, paramName: "other_id"}
);
return options;

Where to go next

Tag Wizard: Custom Code

Getting Started

Implementation & The Invoca Tag

Tag Wizard: Custom Code Settings

Quick reference

Setting details

autoRun (Boolean, default: true)

autoSwap (Boolean, default: false)

campaignIdOverrideParam (String, default: null)

cacheWasReset (Boolean, read-only)

cookieDays (Integer)

cookieNames (Array, default: null)

defaultCampaignId (String, default: null)

destinationAsId (Boolean, default: false)

destinationSettings (Object, default: null)

defaultDestinationName (String, default: undefined)

doNotSwap (Array, default: )

integrations (Object, default: )

maxWaitFor (Integer, default: 1000ms)

numberSelector (String, default: null)

numberToReplace (String, Array, or Object)

onComplete (Function, default: null)

onCompleteOverride (Function, default: null)

onPhoneNumberFound (Function, default: null)

poolParams (Object, default: )

requiredParams (Object)

waitForData (Array)

Where to go next

​Quick reference

​Setting details

​autoRun (Boolean, default: true)

​autoSwap (Boolean, default: false)

​campaignIdOverrideParam (String, default: null)

​cacheWasReset (Boolean, read-only)

​cookieDays (Integer)

​cookieNames (Array, default: null)

​defaultCampaignId (String, default: null)

​destinationAsId (Boolean, default: false)

​destinationSettings (Object, default: null)

​defaultDestinationName (String, default: undefined)

​doNotSwap (Array, default: )

​integrations (Object, default: )

​maxWaitFor (Integer, default: 1000ms)

​numberSelector (String, default: null)

​numberToReplace (String, Array, or Object)

​onComplete (Function, default: null)

​onCompleteOverride (Function, default: null)

​onPhoneNumberFound (Function, default: null)

​poolParams (Object, default: )

​requiredParams (Object)

​waitForData (Array)

​Where to go next

Quick reference

Setting details

autoRun (Boolean, default: true)

autoSwap (Boolean, default: false)

campaignIdOverrideParam (String, default: null)

cacheWasReset (Boolean, read-only)

cookieDays (Integer)

cookieNames (Array, default: null)

defaultCampaignId (String, default: null)

destinationAsId (Boolean, default: false)

destinationSettings (Object, default: null)

defaultDestinationName (String, default: undefined)

doNotSwap (Array, default: )

integrations (Object, default: )

maxWaitFor (Integer, default: 1000ms)

numberSelector (String, default: null)

numberToReplace (String, Array, or Object)

onComplete (Function, default: null)

onCompleteOverride (Function, default: null)

onPhoneNumberFound (Function, default: null)

poolParams (Object, default: )

requiredParams (Object)

waitForData (Array)

Where to go next