This website uses cookies. By clicking Accept, you consent to the use of cookies. Click Here to learn more about how we use cookies.
Accept
Reject
Help
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Show  only  | Search instead for 
Did you mean: 
4398members
1425posts
This is a verified product documentation article. For case-based resolutions articles, please reference the Knowledge Base section of Invoca Community.

Invoca Tag Wizard - Custom Code Settings

stevestormoen
Employee
Employee

‎08-27-2018 11:00 AM - edited ‎08-03-2022 12:58 PM

Note 
Any method preceded with an underscore is subject to change and should not be used.


Available Settings

autoRun Boolean Default: true

Set to false if you do not want the InvocaJS code to run on page load. This can be useful if you have a specific load event or are using a Single Page App framework like React or Angular where InvocaJS should execute after that rendering occurs.

Custom code example:
options.autoRun = false;
return options;

Then trigger the Invoca.PNAPI.run() function when your page or application is ready. This is typically done via some event listener or library render callback in your JavaScript. For example, you might have a 'Contact Us' widget that contains the number, but the content is loaded dynamically, so once that widget is shown you would trigger Invoca.PNAPI.run().

Note: autoRun does not have to be false in order to call Invoca.PNAPI.run().
 
autoSwap Boolean Default: false

Set to true if you want the Invoca JS to automatically detect and replace all numbers on page. This can be useful if you have a large list of phone numbers to manage, or don't know all of the numbers listed across your site. If true, numberSelector and numberToReplace are not needed.

Custom code example:
options.autoSwap = true;
return options;
 
campaignIdOverrideParam String Default: null

Query string name used to identify Campaign ID.

Custom code example:
options.campaignIdOverrideParam = "invsrc";
return options;
 
cacheWasReset Boolean Library default: n/a
Custom code block default: false

Indicates whether the cache has been reset or not. This is a boolean value based on the UI option for resetting attribution. cacheWasReset is available in the custom code block of the Tag Wizard, and is read-only.

Custom code example:
if (options.cacheWasReset){
  //do some special logic when new attribution window is started, such as create a custom cookie.
}
...
return options;
 
cookieDays Integer Library default: 1
Custom code block default: <value from 'attribution window' form field>

Number of days for cache TTL.

Custom code example:
function getAttributionWindowFromSource(){
  //some logic to return variable attribution windows
  return 5;
}
 
cookieNames Array Default: null

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

Custom code example:
options.cookieNames = ["session", "k_id"];
return options;
 
defaultCampaignId String Default: null

The campaign ID to use for all numbers on the page that do not have a specific campaign set via the Tag Wizard UI or via the numberToReplace object. The value is case sensitive and must match exactly, e.g. "inv123" is different than "INV123".

Custom code example:
options.defaultCampaignId = "sales";
return options;
 
destinationAsId Boolean Default: false

Strips out any special characters and uses found destination phone number’s digits as campaign ID.

Warning! Requires Invoca campaign with explicit ID for each number.

Custom code example:
options.destinationAsId = true;
return options;
 
destinationSettings Object Default: null

You can set many destination related settings within this object.
paramName: Name of the Custom Data Field in which Invoca will set the phone number that was replaced.

matchTollFreeNumbers: When an unknown toll free number is detected, we'll auto-generate a Destination to match it.

matchLocalNumbers: When an unknown local number is detected, we'll auto-generate a Destination to match it.
defaultDestinationName String Default: undefined
Required: A campaign ID is set

Specifies a Destination name within a campaign that will be applied to all detected numbers on the page.
doNotSwap Array Default: {}

doNotSwap accepts an array of numbers that you don't want to track with autoSwap or numberToReplace. You can set this option like so:

options.doNotSwap = ["###-###-####"]
return options
integrations Object Default: {}

Integrations supported directly by InvocaJS can be enabled by using the specific integration names below. Some integrations have required params that are customer specific that must be included, while others will work simply by setting the integration name to true in the integrations object.

Important: the default fallback value for these integrations is "not_found". This value will be applied to the Marketing Data parameter used for the integration when we are unable to find it on the page. See configuration options for the fallback value down below.

Supported Integrations:
Integration Name 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

The options of each integration object is the same as the waitForData configuration object, but where the "on" function is defined internally and paramName is defaulted based on the above table. That means paramName, fallbackValue, and timeout can be specified per integration if desired. The default timeout for integrations if not specified is 1 second (1000 milliseconds).

To override default options, pass a config object instead of true.

For example, instead of:
googleAnalytics: true

you could pass:
googleAnalytics: { fallbackValue: "n/a", timeout: 500 }

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

Example of setting one integration at a time (perhaps the custom code is broken into various helper methods):
options.integrations.googleAnalytics = true;
...
options.integrations.optimizely = {goalName: "call", goalId: "xxxx", goalValue: "1"};
return options;

Fallback Value
By default all of the integrations have a default fallback value of "not_found". You will see this value in reporting when the integration's parameter is not found on the page. If you would prefer a blank value be reported when the parameter cannot be found, we recommend setting the fallback value to null.

To change the fallback value, include it in the configuration object for the integration:

options.integrations = {
  googleAnalytics: { fallbackValue: null },
  adobeAnalytics: { username: "username", fallbackValue: null },
  hubspot: { fallbackValue: "n/a" }
}
 
maxWaitFor Integer Library default: 1000
Custom code block default: <value from 'Wait Time' form field>

Max milliseconds to wait before starting the Invoca number request. This only applies if there are integrations or waitForData options set, or custom data sources that read from a dataLayer or cookie, where no data has been returned yet.

The number request will be made as soon as all data is found or the max wait time is reached.
 
numberSelector String Default: null

CSS selector for phone number HTML elements.
Accepts one phone number element (".phoneNumber") or many elements (".phoneNumber, #contact-us-number").

Custom code example:
options.numberSelector = ".phoneNumber";
return options;
 
numberToReplace String, Array or Object Library default: null
Custom code block default: {}

Specify which number(s) to replace and what campaign ID to use for each number. Accepts an object with the number as a key name, and campaign ID as its value:
{"888-999-1010": 'campaignIdHere'}

Advanced: can also be a comma separated string, or an array of strings but only if completely overriding the Tag Wizard UI and not merging with those phone number entries.

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

Custom code example:
//merge local object with existing data, to include numbers from UI
//this will have the UI take precedence over custom numbers
var customNumberToReplace = {
  "888-555-1234": myPrimaryCampaignId(),
  "888-555-6789": mySecondaryCampaignId()
};

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

Custom code example using array / string version:
options.numberToReplace = ["888-999-1010", "777-888-9999"];
options.defaultCampaignId = "sales";
return options;
 
onComplete Function Default: null

Arguments: mapping (array of objects - corresponding to each unique number to replace request that was on the page)

Name of a function to call when Invoca has finished running. This is called after Invoca has run the default number replacement code and swapped out any numbers that were found. If using an existing named function, be sure to provide a reference to the function, and not call the function. For example: use functionName not functionName().

Custom code example with existing function:
options.onComplete = myCustomEventCallback;
return options;

Custom code example with an inline, anonymous function:
options.onComplete = function(){
  $(".phone-number").fadeIn();
};
return options;

See the advanced use case to hide number flicker.
 
onCompleteOverride Function Default: null

Arguments:
batchId,
mapping (array of objects - corresponding to each unique number to replace request that was on the page)

Name of a function to call when Invoca has received a response from the server. If defined, Invoca will not replace any phone numbers. This function is responsible for updating phone numbers on the web page as the default number replacement code will not be run.

If using an existing named function, be sure to provide a reference to the function, and not call the function. For example: use functionName not functionName().

Custom code example with an inline function:
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 that is passed two arguments:
  • node - the DOM node being operated on that has been detected with a phone number in it
  • request - the request object that has been built for the phone number found
Request Object
A valid request object contains the following keys:
  • advertiser_campaign_id_from_network (required, must be unique)
  • request_id (required)
  • destination_name (optional)
  • params (optional) - 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 - If false, is returned then the number in the current node will not be swapped
  • request - If a valid request object is returned, the number in the node will be swapped and any information contained in the request object will be updated
  • If any other value is returned, or nothing is returned, the number in the node will be replaced and the information in the original request will be used
poolParams Object Default: {}

Set of key/value attribution parameters to be captured where the key name should be the Custom Data partner API name (or RingPool parameter name).

Custom code example:
//options.poolParams is guaranteed to be an Object passed in and may contain values already set up by the Wizard UI,
//so do not simply overwrite options.poolParams with a new object
options.poolParams.domain = window.location.hostname;
options.poolParams.referrer = document.referrer;
return options;

Example reading a cookie and passing in pool params:
options.poolParams.session_id = Invoca.Tools.readCookie('session');
return options;

Example merging a new set with the 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 Library default: null
Custom code block default: {}

An object of key-value pairs that represent query string names and values. The integration will run if any of these are met.
{utm_medium: "Search"}

When a requiredParam’s value is *, any passed value will considered true.
{utm_medium: "*"}

Custom code example:
//below example means utm_medium must have a value of "Search" OR any utm_source value
options.requiredParams = {utm_medium: "Search", utm_source: "*"};
return options;

See the advanced use case to require multiple params to be present.
 
waitForData Array Library default: []
Custom code block default: <array of enabled custom data fields>

Array of configuration objects allowing the collection of data that may not be available immediately on page load, such as a cookie set by other integrations, or a data layer variable.

Structure of each configuration object:
on  (function, required): Return the desired value, or null or undefined if that value is not available yet (so that the code will keep trying).
paramName  (string, required): The parameter name that will be sent to Invoca (the Custom Data partner API name or RingPool parameter name).
fallbackValue  (string, optional): A value to set if the timeout was reached with no data return from the 'on' function. If not specified, the default value will be "not_found".
timeout  (int, optional): Milliseconds to poll for data before giving up - the max timeout across all configuration objects is used. If timeout is not specified on any option, we will fall back to the maxWaitFor.

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 attempted to be captured in parallel, and Invoca will continue polling for the data until all callbacks return, or the timeout is reached (which is the highest of the timeout values provided)
  • If on is not a function or paramName is not found, we will warn in the console, but will continue running with any other waitForData configs.
Custom code example:
//it is important to append to the list and not overwrite the existing list in order to preserve capturing the custom data fields with their specified sources
options.waitForData.push(
  {on: getUserId, paramName: "user_id", fallbackValue: "empty", timeout: 500}
);
options.waitForData.push(
  {on: getOtherId, paramName: "other_id"}
);
return options;
 
Need more help?

Don't see what you are looking for? You can ask the Community or contact support.

Comments
pmarquez
Contributor Level 1
‎11-11-2022 09:19 AM

Suggestion:
Add information to autoSwap option explaining if, in an anchor tag, it is swapping phone numbers found in anchor text, href attribute, or both. (both, right?)  Also, what if an anchor tag has "#" placeholder in href but has a TFN in anchor text.  Will auto swap update the href if it is present with something other than "tel:####"? (this is what brought me here - I didn't find an answer so I'll have to do my own tests to see!)

Copyright © 2024 Khoros, LLC