SolutionsJS Web Integration (Deprecated)

Notice: Invoca Tags is the supported way for setting up web integration (which internally uses the InvocaJS library, formerly known as SolutionsJS). View the Invoca Tags support article for installation instructions.

Installation Instructions (Deprecated)

Install this generalized code just above the closing </body> tag of your website.

<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
  Invoca.PNAPI.integration({
    networkId: YOUR_NETWORK_ID,
    numberSelector: ".YOUR_CLASS_SELECTOR"
  });
</script>
<!-- End Invoca Integration -->

Update networkId and numberSelector to match your Invoca Network and current web page settings.

Note:

You may find your networkId pre-populated in sample code available in the Invoca platform:

Choose Tools gear and select Web Integration.

Requirements

  1. Network is PNAPI enabled.

  2. RingPools are type: “Custom”.

  3. Invoca Web Integration code installed on page.

  4. Phone numbers on webpage tagged with a shared numberSelector class (Accepts multiple slectors).

  5. An Invoca Campaign ID to associate with each number on the page (Or a Campaign ID Override).

Identifying a Campaign

There are three methods to identify an Invoca Campaign on your web page, which follow an order of precedence.

1. campaignIdOverrideParam: Specify a query string parameter’s name, the value of which will be used as the Invoca Campaign ID for all phone numbers in a given session.

2. destinationAsId: When true, the phone number’s digits (special characters stripped) from the numberSelector will be used as the Campaign ID.

3. data-invoca-campaign-id: When no override is passed, a user may assign individual Invoca Campaign IDs to a specific phone number’s HTML element using the data-invoca-campaign-id attribute.

4. defaultCampaignId: With no override, a defaultCampaignId can be passed to the Invoca.PNAPI.integration settings and will fill in the gaps wherever no data-invoca-campaign-id is found. If there are no data attributes or overrides, this value will apply to all phone numbers on the page.

Additionally, the defaultCampaignId can be assigned dynamically with JavaScript based upon the page’s environment and variables.

Client Side Parameters

Note: Any parameter value can be populated with a JavaScript variable.

Required parameters:

networkId

String

Invoca Network ID

Required: One of the following

numberSelector

String

CSS selector for phone number HTML elements Accepts one or many like so “.invocaNumber, .phoneNumber”

numberToReplace

String or Hash

Default: null

Specify which number(s) to replace. Can accept one or many like so: “888-999-1010, 777-888-9999”. Optionally accepts a hash with the number as a key name, and campaignId as it’s value like so:

{ “888-999-1010”: ‘campaignIdHere’ }

Optional parameters:

autoRun

Bool

Default true

determines whether Invoca’s web integration runs when the page loads.

If you have a single page application and would like to control when Invoca’s web integration runs, set autoRun to false and call Invoca.PNAPI.run() whenever you are ready.

Note: autoRun does not have to be false in order to call Inovca.PNAPI.run().

destinationAsId

Bool

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.

campaignIdOverrideParam

String

Default: null

Query string name used to identify Campaign ID

poolParams

Hash

Default: {}

Set of JavaScript parameters to be captured where the key name should be RingPool parameter name. These values are updated every subsequent visit.

updatePoolParams

Bool

Default: true

When false, the integration code will not update poolParams on subsequent page visits.

requiredParams

Hash

Default: null

A hash of key value pairs that represent query string names and values. For example: {name: value} The integration will run if any of these are met.

When a requiredParam’s value is *, any passed value will considered true.

cookieNames

Array

Default: null

List of cookie names to automatically capture as RingPool Parameters

telLinkOnly

Bool

Default: false

Used for a “Call Now” button. When true, will only update the tel: link on any numberSelector that is found.

cookieDays

Int

Default: 1

Number of days for cache TTL.

onComplete

Function

Default: null

Arguments: mapping

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.

For example: functionName not functionName().

onCompleteOverride

Function

Default: null

Arguments: batchId, mapping

Name of a function to call when Invoca has finished running. 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.

For example: functionName not functionName().

debugMode

Boolean

Default: false

When true, will display debug logs in the developer console.

Examples

campaignIdOverrideParam

To use a query string parameter as the Invoca Campaign ID for all phone numbers found on page, specify the parameter name in this option. To use the value of ?utm_source as the Campaign ID, follow this example:

URL

http://www.example-page.com?utm_source=google

CODE

<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
  Invoca.PNAPI.integration({
    networkId: YOUR_NETWORK_ID,
    numberSelector: ".YOUR_CLASS_SELECTOR",
    campaignIdOverrideParam: 'utm_source'
  });
</script>
<!-- End Invoca Integration -->

RESULT

The caller is assigned and delivered to the “google” campaign in Invoca for any phone number found on the page with data-invoca-campaign-id’s and the defaultCampaignId being overriden.

data-invoca-campaign-id

To assign multiple numbers on a page to different Invoca Campaign IDs, simply add this attribute to each phone number element.

URL

http://www.example-page.com?utm_source=google

CODE

<div id="main">
  Call customer service at: <span class='number' data-invoca-campaign-id='customer-service'>855-555-5555</span>
  Call sales at: <span class='number' data-invoca-campaign-id='sales'>855-555-4444</span>
</div>

<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
  Invoca.PNAPI.integration({
    networkId: YOUR_NETWORK_ID,
    numberSelector: ".number"
  });
</script>
<!-- End Invoca Integration -->

RESULT

When customer service is called, the call will be assigned and delivered to the ‘customer-service’ campaign in Invoca. When sales is called, it will be assigned and delivered to the ‘sales’ campaign in Invoca.

defaultCampaignId

When no campaignIdOverride or data-invoca-campaign-id are found, the default campaign ID will be assigned to the call.

CODE

<div id="main">
  Call customer service at: <span class='number' data-invoca-campaign-id='customer-service'>855-555-5555</span>
  Call sales at: <span class='number'>855-555-4444</span>
  Interested in a demo? Call now! <span class='number'>855-555-4444</span>
</div>

<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
  Invoca.PNAPI.integration({
    networkId: YOUR_NETWORK_ID,
    numberSelector: ".number",
    defaultCampaignId: "sales"
  });
</script>
<!-- End Invoca Integration -->

RESULT

When customer service is called, the call will be assigned and delivered to the ‘customer-service’ campaign in Invoca. When sales is called, it will be assigned to the defaultCampaignId of ‘sales’. When a visitor is interested in a demo, the call will be assigned to the defaultCampaignId of ‘sales’.

poolParams

Allows variables from JavaScript to be associated with a call.

CODE

<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">

  var invocaParams = {
    currentPage: window.location.href
  };

  Invoca.PNAPI.integration({
    networkId: YOUR_NETWORK_ID,
    numberSelector: ".YOUR_NUMBER_SELECTOR",
    poolParams: invocaParams
  });

</script>
<!-- End Invoca Integration -->

RESULT

When a call is placed, the RingPool parameter with name “currentPage” will show the URL of the page the user called from.

For example, it may look like: http://www.example-page.com/contact-us

requiredParams

Conditionally runs Invoca’s web integration.

URL #1

http://www.example-page.com?gclid=1a2b3c4d5e

URL #2

http://www.example-page.com?ref=test

CODE

<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">

  Invoca.PNAPI.integration({
    networkId: YOUR_NETWORK_ID,
    numberSelector: ".YOUR_NUMBER_SELECTOR",
    requiredParams: {gclid: "*"}
  });

</script>
<!-- End Invoca Integration -->

RESULT

When URL #1 is visited, the Invoca web integration will run. When URL #2 is visited, the Invoca web integration will not run.

Invoca.PNAPI.run()

React

componentDidMount() {
  Invoca.PNAPI.run();
}

AngularJS

$scope.$on('$viewContentLoaded', Invoca.PNAPI.run);

Migrating from an older version

If you are migrating from SolutionsJS 1.2 or below, please refer to the following guide.

1. Update your namespaces - Change Solutions.PNAPI.integration to Invoca.PNAPI.integration - Change any Toolkit functions, like Solutions.PNAPI.readUrl to Invoca.Tools.readUrl

2. Update your data attributes - Change data-invoca to data-invoca-campaign-id

  1. Update your integration scripts from this:

<script type="text/javascript" src="//pnapi0.invoca.net/0/pnapi_integration.js"></script>
<script type="text/javascript" src="//cdn.invoca.solutions/js/solutions-1.2.min.js">

to just this:

<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>