> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invoca.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/s/article/tag-wizard-custom-code).

<Note>
  **Note**

  Any method name preceded with an underscore is subject to change and shouldn't be used.
</Note>

## 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.

```js theme={null}
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.

<Note>
  **Note**

  `autoRun` doesn't need to be `false` to call `Invoca.PNAPI.run()`.
</Note>

### 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.

```js theme={null}
options.autoSwap = true;
return options;
```

### campaignIdOverrideParam (String, default: null)

The query string name used to identify a Campaign ID.

```js theme={null}
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.

```js theme={null}
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.

```js theme={null}
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.

```js theme={null}
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.

```js theme={null}
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.

<Note>
  **Note**

  Requires an Invoca campaign with an explicit ID set for each number.
</Note>

```js theme={null}
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`.

```js theme={null}
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`:

```js theme={null}
// Instead of:
googleAnalytics: true

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

**Combining multiple integrations:**

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

**Setting integrations one at a time:**

```js theme={null}
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`:

```js theme={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`).

```js theme={null}
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:

```js theme={null}
{"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:

```js theme={null}
"888-999-1010, 777-888-9999"
["888-999-1010", "777-888-9999"]
```

**Merging with existing UI data (UI takes precedence):**

```js theme={null}
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:**

```js theme={null}
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()`.

```js theme={null}
// 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](/s/article/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`.

```js theme={null}
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:

```js theme={null}
{
  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).

```js theme={null}
// 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.

```js theme={null}
// 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](/s/article/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.

```js theme={null}
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.

```js theme={null}
// 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](/s/article/tag-wizard-custom-code)