Digioh Extensions

Digioh Owned Identification for Iterable connects Digioh on-site campaigns with Iterable user data so you can recognize known visitors and use their Iterable profile information to control when specific on-site experiences appear.

Once enabled, Digioh can automatically:

• Identify visitors who already exist in Iterable

• Sync a visitor’s identity to Iterable after a Digioh form submission

• Identify users clicking through from Iterable emails

• Distinguish between known and unknown visitors

• Use Iterable profile fields and list membership in Digioh display rules

• Personalize on-site messaging using Iterable data

This allows you to deliver more relevant on-site experiences, such as suppressing email capture pop-ups for existing subscribers or showing tailored messaging to specific Iterable audiences, without requiring additional forms or custom development.

What does this extension do?

• Flexible general-purpose event tracking from site to Iterable, e.g., conversion tracking and marketing attribution
• Anonymous User Tracking (AUT) is closely related to event tracking. It queues up events until the user is known, then sends everything to Iterable, which is essentially a “profile merge”. The other half of AUT is cross-device identification, based on Digioh form input, URL query string, or extraction from the Iterable SDK
• Targeting Digioh Campaigns based on Iterable user profile data (fields, list membership, in-app messages)
• Personalizing Digioh Campaign content based on Iterable user profile fields
• Digioh Campaign-Form auto-fill
• Tracking site pageviews to Iterable with a wide range of analytics data, including marketing attribution and geo-location data
• Tracking campaign interaction events to Iterable with form and analytics data, e.g. to trigger campaigns based on campaign conversion
• Cross-device identification and profile merging
• Cart abandonment, browse abandonment, and customized user experience based on cart/product interactions

All of the above works when a visitor is known, which raises the question:

When is a visitor “known”?

A visitor is known if either of these happens:

• Digioh collected their email earlier on that device
• They arrived at your site via email with proper configuration for it (see below)
• You set up a JS var to identify users (also see below for guidance).

Configuring Iterable’s Owned Identification in your Digioh account

Step 1: Connect Digioh to Iterable

To use the extension, you will need at least one authenticated Iterable Integration configured in your Digioh account.

1. In Iterable, generate a Server-Side API Key
2. In Digioh, go to Integrations
3. Click Add Integration
4. Search for Iterable and select it
5. Click Add New Connection
6. Name your Connection, enter your Iterable API Key and select your Project Type
7. Select yes or no for Restrict Profile Data
   IMPORTANT SECURITY NOTE: By default, this extension potentially exposes the Iterable User Profile Fields in the browser. If your user profiles contain PII or otherwise sensitive data, you must configure the integration to “Restrict Profile Data” and select only the non-sensitive fields that you wish to use for targeting. We recommend excluding all fields by default and manually adding the fields you do want to include to be used for targeting, for example:
8. Select yes or no for Enforce SHA256 Encryption. Enabling this setting protects personally identifiable information (PII) during transmission. Users will only gain access to your Iterable resources by including the correct SHA256 hash value. This is recommended if you are sending a link in your Iterable Emails (using Iterable’s Handlebars Templating system to generate the hash).

At this point, you can save the integration. After saving, copy the five-digit Integration ID from the Integrations page. You will need this in step 3 below.

Step 2: Install the Owned Identity for Iterable Extension

This extension enables Iterable-owned identification inside Digioh.

1. In Digioh, hover over your profile icon in the top right
2. Select Extensions
3. Go to Platform Interoperation
4. Install Owned Identity for Iterable (TPAU)
5. Click Publish to your Site

Step 3: Add Account Metadata

This step links the extension to your Iterable integration.

1. Hover over your profile icon in the top right
2. Select Account Metadata
3. Add the following key-value pair
   1. Key
      Tpau_proxy_integration_id
   2. Value
      Your Iterable Integration ID from Step 1
4. Click Save
5. Go back to the campaigns page and select More > Publish Account

Along with configuring a default integration for the entire account,  you can also configure site-specific integration IDs that use their own Iterable integration using the Key tpau_proxy_integration_id:domain_url. This is useful if you are running multiple sites out of a single Digioh instance and/or have a sandbox site that you want to point to your Iterable sandbox:

If you’re having trouble getting Owned Identification to work properly on your staging site, you can double-check the Host Name to use in the Account Metadata by entering DIGIOH_API.getHostName() in the browser console while on your staging site.

And that’s it! Once this is complete, Owned Identification for Iterable becomes active on your site.

Step 4: Maximize your identity tracking (optional)

Once your extension is installed and connected, we recommend making sure your Iterable project is properly configured to track users on site to maximize visibility:

Linking Iterable User Identity to Digioh

Digioh will retain and use the email identity of users where a Digioh campaign collected their email, but you can and should expand this to include existing Iterable users too, especially if you have existing mechanisms to create users in Iterable, e.g., native email signup forms or a login process.

If you have configured the Iterable JavaScript SDK and are using the Link Tracking Domain feature, Digioh will grab the email or userId from that if available, and this should work by default.

Otherwise, you can set up identify-on-email-click up manually by updating your Iterable email campaign templates so that most or all links to your site include either of these identities on the URL query string, using handlebar syntax:

• ?email={{email}}
• ?userId={{userId}}

We recommend using userId if possible (if you have a userId Iterable project), since that is more secure.

This way, any clicks on an email will identify that user to Digioh and activate targeting capabilities. You don’t have to instrument all of your emails in this way, but we recommend that you do so for links in your most commonly clicked emails to maximize the “penetration” of identity sync within your user base. For example, if you have a double opt-in email signup process and/or a welcome email, definitely add the email parameter to those.

Using JS Vars

If you have a website with a login, and through it you can easily access an email or userId, we highly recommend (and support) using that to identify users. This is what you need:

• A JS Var that allows Digioh to access it (it can be either email or userID)
  • You can test if this works by calling it in the console: “DIGIOH_API.myVar.xyz“
•  Add it in the account metadata with the key tpau_userid_source_var

After that, Digioh will automatically access that and ID users!

 

Using Iterable’s Owned Identification to personalize your visitors’ experience

Targeting Known status and list membership

After you have installed the Extension and configured Account Metadata, Iterable targeting rules are available in Campaign Display Rules.

Digioh supports targeting (and anti-targeting) of campaign displays to known Iterable User’s Profile Fields (attributes) and/or list membership:

Known vs. Unknown Visitors

An Iterable user is “known” to Digioh if they have been identified with any of the methods explained above.

• Known visitors are people Digioh can already match to an Iterable profile.
  Use this to suppress email capture pop-ups or show “welcome back” and loyalty messaging.
• Unknown visitors are people Digioh hasn’t identified yet.
  Use this to show welcome sign-ups, first-time offers, or newsletter promotions.

List Subscription Status

You can target visitors based on any static list by selecting the list from the dropdown.

Available lists are pulled automatically from your Iterable instance. Dynamic lists (aka Segments) are not supported at this time since the Iterable API does not support lookup of Dynamic List membership on a per-user basis.

Targeting User Profile Fields (Advanced)

This extension works by retrieving and caching Iterable user profile fields in real-time, and making the data available in a JavaScript object DIGIOH_API.itrbl that you can reference in Campaign display rules.

In general, reference user profile fields by name like this:

DIGIOH_API.itrbl.attributeName

Note: Digioh can create “Custom Display Rules” for you based on your needs to make targeting easier for non-technical users, just ask Support.

Anti-Targeting Iterable Data

When anti-targeting user profile fields, note that the JS Var display rule does not equal will be true for unknown users, so if you want to anti-target known users that do not have favoriteColor = green you should also check if they are known:

Without the first display rule here, the campaign would display to all unknown users, which is probably not what you want. If you do want to target unknown users, you can use JS Var DIGIOH_API.itrbl.unknown Equals true. Equals is very important, because if you use the default “contains” comparison, it will assume a string and Boolean true does not “contain” anything.

Personalization

You can personalize the context of your campaigns by using merge tags that replace with Iterable user field data. To do this, install the separate Universal Merge Tags extension. With this extension, you can use the merge tag [ITERABLE_FIELD|fieldName|defaultValue].

defaultValue is optional, but recommended. It is used when the user is unknown or does not have the named field in their Iterable profile, or the named field is blank.

When using Iterable merge tags, we recommend that you condition the campaign based on DIGIOH_API.itrbl.known = true. While default merge tag values will work for unknown users, usually you want to personalize only the experience of known users.

Tracking Events to Iterable

This extension can be configured to track page views and campaign events to Iterable using metadata at any of the account, campaign, or campaign-page level. The commands are:

• tpau_pageview_event: name of the event to send on every web page view, must be configured in Account Metadata
• tpau_track_pageview_json: JSON for the event payload, supporting all UMT merge tags, must be configured in Account Metadata. Example: {“page_path”:”[PAGE_PATH]”, “ip_address”:”[IP_ADDRESS]”}
• tpau_box_event: name of event to send on campaign-page view
• tpau_track_box_json: JSON for the event payload, supporting UMT merge tags. Example: {“box_id”:”[BOX_ID]”, “box_name”:”[BOX_NAME]”, “page_name”:”[BOX_PAGE]”}

Campaign-page tracking is based on the level of the metadata config. Campaign-Page-level will track for just that page, so it is ideal for conversion events. Campaign-level tracking will track on all pages for that campaign. Account-level will track on all pages of all campaigns. The Extension will track the most specific event, so if you have both campaign-page and campaign-level event config, only the campaign-page event will be tracked.

 

Skipping the Email Collection Page for Known Users

When using Iterable Owned Identification, you can automatically skip an email collection page if the visitor is already known to Digioh / Iterable.

This is useful for quizzes or surveys where returning users shouldn’t be asked for their email again.

How to Configure

1. Identify the page that collects email

   • The page must have a form enabled

   • The Email field must be enabled on that form

2. Add page-level metadata to the email collection page:

• • Key: when_exists
  • Value: page number you want it to skip to, for example, ep6 or thx

Note: This doesn’t auto-submit the form; it simply skips the specified page.

Interoperating with your own site JavaScript (Advanced)

From your own on-site JavaScript (or JavaScript in a Google Tag Manager tag), there are several functions you can call to interact with the extension for advanced use cases. All functions are defined in the window.DIGIOH_API object.

• DIGIOH_API.setIterableEmail(email): set or replace known user profile with email
• DIGIOH_API.setIterableUserId(userId): set or replace known user profile with userId
• DIGIOH_API.clearIterableData(): remove all known user info and become unknown
• DIGIOH_API.trackIterableEvent(eventName, payloadObj, options): tracks a custom event to Iterable, or queues it if the user is unknown. The options are an object with (optional) properties:
  • updateEventId: updates an existing event with this ID
  • createdAt: override the default date with this Unix epoch time (seconds since 1970)
• DIGIOH_API.createOrUpdateIterableEmail(email, {optional:”foobar”}): “upsert” a new email in Iterable, optionally setting user profile fields.

Important Note: Digioh is a dynamically loaded JavaScript, so it may not be available if you try to call it immediately on page view. The extension recognizes a special event queue (similar to dataLayer) that you can push event objects into, and they will be processed as soon as Digioh activates. Before calling the Digioh functions, check to see if they are defined, and if not, push events like this:

window.digiohEventQueue = window.digiohEventQueue || [];
window.digiohEventQueue.push({eventName:”preload_test_event”,eventPayload:{event_val : 1}});

Any events in window.digiohEventQueue will be processed as soon as Digioh activates.

Diagnostics: User identification

This extension is “silent”, but you can access a control panel and helpful diagnostic information when using ?boxqamode on the URL.

If either email or userId is shown (or both), then the user is “known”.

• Forget User: clear all data associated with the user and become “unknown”
• Show User Data: displays a notification containing all of the targetable data and data that can be used to personalize for the known user
• Identify User: become known as the user with the given email or userId

Pay attention to the notifications from the Iterable extension, especially red error messages. Errors are typically “fatal”, especially configuration errors, and must be corrected before the extension can function properly.

Technical Details

Digioh is a JavaScript component running in the browser that:

• Mediates the identification process
• Sends event data and/or known user profile updates to Iterable
• Caches known user Iterable data in sessionStorage for targeting and personalization of Digioh Campaigns

When a user is unknown, Digioh retains the queue of events and/or profile updates until the user becomes known, at which point it will process the queue to the Iterable database.

All read-write operations are via a Digioh server proxy, which a) protects the API key, and b) limits the data that can be read from Iterable and exposed in the browser (e.g, sensitive PII would not be readable).

Identification can happen via an email click, an explicit call to Digioh JS from your site-native JS or Google Tag Manager, or via user email input into a Digioh Campaign (not shown in diagram). In addition, if you already have the user email or userId in a cookie, localStorage, or JavaScript variable, the Digioh Implementation Team can customize our solution to automatically identify users from those sources.

Running into an issue or have a question? Reach out to our support team via support@digioh.com, and we’ll be happy to help!