Using Our SDK

The OptiPub SDK exposes a global "optipub()" function that is available on any page where it is installed. This function allows for you to perform some basic commands that will report back to your installation of OptiPub.

All of the commands follow the same basic structure:

optipub('action', 'command');
optipub('action', 'command', 'parameter');

📘

Advanced Usage

All of the OptiPub SDK commands return a Promise. See the Advanced Usage section for more information.

Available Commands

The "Email" Command

optipub('record', 'email', '[email protected]');

You are encouraged to use the "email" command any time that you are able to identify an email address for the user that is accessing your website. While users are visiting your website, we assign them a temporary identifier. When an email gets recorded, the tracking system updates their identifier and makes the appropriate association with the old identifiers.

The "Sale" Command

optipub('record', 'sale', 299.99)

OptiPub allows you to record revenue from your email marketing campaigns through the "sale" command.

In order to use revenue tracking through OptiPub, you need to make sure this command reports all of the sales as they occur.

This command requires that a user have a "message_id" and "link_id" be set before being considered a valid sale.

📘

Fraud Protection

In order to be as accurate as possible, OptiPub records the following information about a sale: "link_id," "message_id," "revenue," and "tracking_identifier."

If all of these values are identical between two reported sales, OptiPub discards the new information. This prevents a single user from firing multiple sale events with the same information.

❗️

Fractions

The sale command is designed to be used for monetary transactions. Fractions of a penny will be rounded to the nearest penny.

❗️

Multiple Transactions

It is not impossible for a user to make more than one purchase after following a single link. The user will have only a single "message_id" and "link_id" for the session. In order to ensure that additional valid sales are recorded, it is recommended to pass a different revenue "amount" in the third parameter of the command for each transaction a user might encounter.

Consent

By default, the SDK starts tracking as soon as it loads on the page. If your website asks visitors for permission before setting cookies, you can hold tracking back until they accept.

Waiting for Consent

Set the "requireConsent" setting before the tracking tag. The SDK reads this setting the moment it loads, so placing it after the tag may allow the pixel to fire before your banner is answered.

<script>
  window.optipubSettings = { requireConsent: true };
</script>

<!--- Optipub Tracking Tag --->
<script>
  // Your OptiPub tracking tag.
</script>

While the SDK waits, it still reads the OptiPub tracking codes from the page URL, so a visitor who accepts your banner is still credited to the message and link that brought them to your website. No pixel is requested and no OptiPub cookie is set until consent is granted.

Consent Commands

// The visitor accepted your consent banner.
optipub('consent', 'grant');

// The visitor withdrew their consent.
optipub('consent', 'revoke');

optipub('consent', 'status').then((status) => {
  console.log(status);
});

These commands are queued like every other SDK command, so you can call them immediately after the tracking tag without waiting for the SDK to finish loading.

📘

Remembering the Decision

The SDK does not store the visitor's choice between page loads. Your consent banner owns that decision, so it needs to call the "grant" command on every page where consent has already been given.

❗️

Browser Privacy Signals

"Do Not Track" and "Global Privacy Control" always take priority. If a visitor broadcasts either signal, the "status" command resolves with "denied" and granting consent will not start tracking.

📘

Commands While Waiting

Commands that depend on tracking, such as "email," "sale," and "hasSubscription," wait while consent is pending instead of failing. This matters most on a page that shows a consent banner alongside a checkout: a visitor can place an order before answering the banner, and the sale is still recorded if they go on to accept it. Nothing is sent to OptiPub while a command is waiting.

Waiting commands run as soon as the "grant" command is called, and they reject if the visitor denies consent instead. A visitor who never answers the banner leaves the command waiting until they navigate away, so the promise it returned never settles.

❗️

Handling Rejections

Commands reject with an "Error" when tracking is not permitted, so attach a rejection handler to anything you call directly. Commands you push onto the queue before the SDK loads have no caller to handle them, so the SDK discards their rejections rather than reporting them to the browser console.

Advanced Usage

All of the OptiPub SDK Commands return a Promise after the SDK has finished loading on the page. To verify that the SDK has been loaded, an "OptiPubSdkReady" CustomEvent is available on the "window" DOM interface.

This allows for you to add an event listener on the "OptiPubSdkReady" event in order to reliably return a Promise called synchronously during page load.

We recommend that you call the OptiPub SDK Commands asynchronously from the page load.

// Embedded script that fires on page load.
window.addEventListener('OptiPubSdkReady', () => {
  optipub('record', 'sale', 299.99).then(() => {
    // success
    console.log('Sale has been recorded. Redirect to another page.');
  }, () => {
    // error
    console.log('An error occured when recording the sale.');
  });
});

// Script that fires from an event after the page has loaded.

optipub('record', 'sale', 299.99).then(() => {
  // success
  console.log('Sale has been recorded. Redirect to another page.');
}, () => {
  // error
  console.log('An error occured when recording the sale.');
});

❗️

Polyfills Not Provided

The OptiPub SDK does not have any polyfills for Promises nor CustomEvents, both of which currently are not supported in Internet Explorer. If you would like to leverage this advanced functionality, and have greater browser support, you will need to provide your own polyfills.