What are KV Pairs?

KV Pairs is a feature of Audience Insights that enables a publisher to configure a list of data points for which it wishes to collect data about its users. Each data point (key) must be configured in Settings Admin before the Audience Insights APIs will accept data for them. Configuration items for a KV pair include its time to live (TTL) in the Audience Insights database, input validation of the value(s) that will be accepted, and whether the value will be piped through an IFX Integration prior to being stored in Audience Insights.

Suggested uses for KV Pairs include tracking individual newsletters that the user may have signed up for, survey responses and other items that may enable personalized experiences for the individual user while consuming content.

Note

Audience Insights also has a variation of KV Pairs referred to as IAB pairs. Here a list of common keys and input validations have already been defined by the Interactive Advertising Bureau. Please consider using IAB pairs before defining common keys using KV Pairs.

APIs For Working With KV Pairs

The KV Pair feature has two sets of APIs: 1) Public APIs that can be called by readers who are signed in; and 2) Developer APIs that can be called by the publisher’s servers to store values for individual users. These are the available APIs:

Public APIs

HTTP Method	Path	Description
GET	/identity/public/v2/extprofile/kv/:key	Get the value of a single key for a signed-in user
GET	/identity/public/v2/extprofile/kv	Get all key-value pairs for a signed-in user
POST	/identity/public/v2/extprofile/kv	Store a key-value pair in the account of the signed-in user

Developer APIs

HTTP Method	Path	Description
DELETE	/identity/api/v2/extprofile/kv/i/:id/:key	Delete a key-value pair for the indicated user account
GET	/identity/api/v2/extprofile/kv/i/:id/:key	Get the value of a key for the indicated user account
GET	/identity/api/v2/extprofile/kv/i/:id	Get all key-value pairs for the indicated user account
POST	/identity/api/v2/extprofile/kv/i/:id	Store a key-value pair in the indicated user account

Note

The detailed descriptions of all the APIs are available here

KV Pairs and IFX

IFX is Arc XP’s platform for a publisher to upload its own custom code to for the purpose of extending the platform. When configuring a KV Pair, using Settings Admin, it is possible to indicate that, rather than storing the value, the submission of a new KV Pair (using the public API) should result in an IFX integration being invoked.

Note

The name of the IFX integration is commerce:kvp_event

As an example, if the KV Pair indicates that the user is signed up for a newsletter, then the publisher’s logic, in the IFX integration, can call out to the publisher’s email service provider(ESP) to manage the registration. Upon positive confirmation from the ESP the IFX integration can use the Audience Insights developer API to store the response in the user’s account.

Arc XP Audience Insights KV Pairs SDK Methods

Before utilizing these methods, see Audience Insights: Getting Started for more information on setting up the SDK.

Our SDK methods serve as wrappers, making it easier for developers to interact with our APIs. The following table lists the SDK methods and the corresponding APIs they wrap.

SDK Method	API
submitValue(key, value)	POST /identity/public/v2/extprofile/kv
listKVPairs()	GET /identity/public/v2/extprofile/kv
getKeyValue(key)	GET /identity/public/v2/extprofile/kv/{key}