This document provides an overview of non-standard Permutive integrations, how they are enabled and responsibilities throughout the configuration. As Permutive grows, the list of supported native integrations will also grow. However, many non-standard integration requests are relatively easy to set up and may only require a small code change to work. 

There are two common integration types:

• Data Collection

• Activation

Data Collection

We have the ability to track events and their properties within Permutive.

Note: These data collection methods are not actually considered integrations. Rather, they are the standard usage of Permutive.

If you are looking to collect such data, this collection can be achieved in three ways. 

1. Adding additional fields into the Pageview event. You will be responsible for adding the required fields into the Pageview collection call. This is generally used for, but not limited to, data points, such as article, author or category. This data should be made available by your CMS or within your data layer. The data should be available before page-load, to ensure it doesn’t slow Permutive’s real-time targeting

2. Capturing data asynchronously. Permutive has the ability to set up custom events where the information can be captured in three different ways:

• Directly on the Edge (client side) by calling the track function [preferred method] 

• Via APIs calls, for server-side event collection

• Off-site data collection for specific events can be achieved by pixels. A guide can be found here. Note: pixels typically rely on third-party cookies

Custom events are generally used to capture information from user-actions, such as surveys, videos, logins or other asynchronous events with useful data.

You can also batch upload data server-side via our second-party data framework. This is particularly useful for sending large volumes of declared data, such as age and gender information, from your CRM or data warehouse.

Note: Because the methods described above are not considered integrations, Permutive doesn’t actually integrate with these other providers (i.e. survey provider). Rather, Permutive supports the ability to capture any data object through the means listed above. This means we are agnostic to any provider you are working with. As long as you have the ability to share this data with Permutive, you will be able to leverage this data for building cohorts.

Ownership

The customer is responsible for sharing the required data with Permutive. The SA helps finalize the required data structure in collaboration with the customer, as well as assists with the third-party solutions, as needed. The customer will take responsibility for sending the data to Permutive through one of the options listed above. Lastly, the customer will take ownership of keeping Permutive informed on necessary updates or modifications of data structure to align with any changes of the third-party solution.

Activations

Activations are the ability to send Permutive cohorts to another solution, such as SSPs, DSPs, Video Players, Ad Servers etc. This encompasses any platform where the customer has the ability to “activate” (target) a user through cohorts.

Note: This type of integration will be considered  a custom setup until it’s natively supported by the Permutive platform.

A common use-case is to activate Permutive cohorts via key-value pairs through an activation partner. Permutive’s edge technology allows you to attach user cohort memberships to ad- or bid-requests directly on the page.

Because the output data, cohorts, exists on-page, a publisher can explore the ability to deploy a custom integration (supported by SA) with any other on-page platform partner. The steps below describe how this can be done.

Note: While this is a custom setup, not covered by the publisher's services agreement, it is typically stable and quick to implement.

Data Flow

All user cohorts are stored in local storage within the browser. Any on-page platform partner that has access to the publisher's local storage can read these values. However, the cohort IDs have no explicit meaning without the publisher's mapping file. Thus, a publisher can choose to support the partner by (1) showing them where to find the cohort IDs and (2) providing them with a mapping file containing cohort ID and cohort name.

Step 1: KVP Resolution by the Platform Partner

All cohort IDs can be found in local storage, currently accessible under the _psegs variable. The cohort memberships for an individual can also be retrieved directly from the SDK. A guide on this can be found here.

Those values are made accessible to the platform partner in one of three ways:

1. Platform partner implements code to automate cohort ID resolution from within their own solution

2. Publisher implements code to provide the cohort IDs to the partner's solution
3. If publisher uses Prebid, SSP platform partners can contact Permutive to become a bidder that is supported by our Prebid RTD Module

Step 2: Providing Mappings of Cohort IDs to Platform Partner

Each cohort ID is a 5-digit code, unique per publisher. Only the publisher has access to the translation of the cohort ID to its definition (i.e. a meaningful cohort name).

Within the Permutive UI, the publisher has the ability to export a mapping of the cohort ID to its definition. For example, ID 12345 may map to your "Sports Enthusiast" cohort.

The publisher has access to a .csv file that they can export and choose to share with a platform partner.

The publisher can also share a read-only API endpoint with the platform partner that can be used to retrieve the cohort mapping. Your SA will be able to help you get access to this API endpoint.

Customer driven integration as a POC

Up until the point where Permutive provides a native integration with the platform partner that guarantees continued support, we assume each integration is considered POC, “Proof of Concept.” This means that Permutive can not guarantee, nor is responsible, for the integration. If the integration stops working due to an update, modification or change outside of our control, it is the publisher's responsibility to alert the Permutive team and to implement required updates. While Permutive is not able to take liability for such integrations as described above, Permutive will try to provide timely support to re-enable such integrations.