JavaScript API¶

This API provides access to information about users such as ID of audience they are part of and their attributes. It also allows you to update their attributes.

Loading snippet¶

Add the following snippet on your page to start using this API. It should be added just before the first API usage.

Changed in version 10.0: Loading snippet changed to allow multiple initializations. Now separate scripts can initiate and use this API without interference.

Configuration:

String XXX-XXX-XXX-XXX-XXX should be replaced with app ID (e.g. efcd98a5-335b-48b0-ab17-bf43f1c542be).

String https://your-instance-name.piwik.pro/ should be replaced with your PPAS instance address. (please note that it’s used in 2 places in the snippet).

Code:

<script>
    (function(a,d,g,h,b,c,e){a[b]=a[b]||{};a[b][c]=a[b][c]||{};if(!a[b][c][e]){a[b][c][e]=function(){(a[b][c][e].q=a[b][c][e].q||[]).push(arguments)};var f=d.createElement(g);d=d.getElementsByTagName(g)[0];f.async=1;f.src=h;d.parentNode.insertBefore(f,d)}})
    (window,document,"script","https://your-instance-name.piwik.pro/audiences/static/widget/audience-manager.api.min.js","ppms","am","api");

    ppms.am.api("create", "XXX-XXX-XXX-XXX-XXX", "your-instance-name.piwik.pro");
</script>

This code initializes the API interface in the following ways:

Creates a <script> tag that asynchronously loads the Audience Manager API library.

Initializes the global ppms.am.api command queue that schedules commands to be run when the API library is loaded.

Schedules create command on ppms.am.api to initialize the API object with a basic PPAS configuration.

You can use the API command queue (ppms.am.api) immediately after step 3.

Command queue¶

Executing the snippet creates the following global function:

ppms.am.api(command, ...args)¶

Audience Manager API command queue.

Arguments:	command (string) – Command name. args – Command arguments. The number of arguments and their function depend on command.
Returns:	Commands are expected to be run asynchronously and return no value.
Return type:	undefined

Commands¶

All commands work in context of the current user. Additionally they require communication with a PPAS server and are asynchronous. Callback functions are used to provide response value or information about errors.

Get list of audiences user belongs to¶

Fetches a list of audience IDs the user belongs to.

Code:

ppms.am.api("getAudiences", onFulfilled, onRejected);

onFulfilled(audience_list)¶

The fulfilment handler callback (called with result).

Arguments:	audience_list (Array<string>) – Required Array of audience IDs the user belongs to. Example: ["e8c6e873-955c-4771-9fd5-92c94577e9d9", "756e5920-422f-4d13-b73a-917f696ca288"]

onRejected(error_code)¶

The rejection handler callback (called with error code).

Arguments:	error_code (string) – Required Error code. Example: "server_error"

Check user membership in the audience¶

Checks if the user belongs to the audience.

Code:

ppms.am.api("checkAudience", audience_id, onFulfilled, onRejected);

audience_id

Required string ID of the checked audience.

Example:

"52073260-5861-4a56-be5e-6628794722ee"

onFulfilled(in_audience)

The fulfilment handler callback (called with result).

Arguments:	in_audience (boolean) – Required True when user is part of the audience, false otherwise. Example: true

onRejected(error_code)

The rejection handler callback (called with error code).

Arguments:	error_code (string) – Required Error code. Example: "server_error"

Get user attributes¶

Fetches the user profile attributes. The user have to be identified by analytics ID.

Note

In order to secure the PII data, no attribute is returned by default. You need to put each attribute you want to access on attribute whitelist before it is returned by this command. In order to do that, go to Audience Manager > Attributes tab and enable attribute for the public API access. It is your responsibility to make sure no user PII data will be available via API.

Code:

ppms.am.api("getAttributes", onFulfilled, onRejected);

onFulfilled(attributes)

The fulfilment handler callback (called with result).

Arguments:

attributes (Object<string,Object<string,(string|number|Array<string>)>>) –
Required Object containing user attributes divided by source.
- analytics - Object<string,string> Contains analytics attributes about the user (e.g. browser name, browser version, country).
- attributes - Object<string,(string|number|Array<string>)> Contains custom attributes about the user (e.g. first name, last name, email).
Example:
```
{
    "analytics": {
        "browser_name": "chrome",
        "country": "us"
    },
    "attributes": {
        "favourite_brands": ["Alfa Romeo", "Aston Martin"],
        "age": 32,
        "first_name": "James",
        "last_name": "Bond"
    }
}
```

onRejected(error_code)

The rejection handler callback (called with error code).

Arguments:	error_code (string) – Required Error code. Example: "server_error"

Update user attributes¶

Creates or updates user custom attributes.

Note

Any attribute can be updated this way whether it is on the attribute whitelist or not.

Code:

ppms.am.api("updateAttributes", attributes, options);

attributes

Required Object<string,(string|number|Array<string>|object)> Object containing attributes to update:

key (string) - attribute name

value (string|number|Array<string>|object) - Value of the attribute. System will process it differently depending on its type:

string - overwrite the attribute value with the new value. If the attribute was not used before - creates new text attribute.

number - overwrite the attribute value with the new value. If the attribute was not used before - creates new numeric attribute.

Array<string> - overwrite the attribute value with the new set of values. If the attribute was not used before - creates new text attribute with a list of values.

object - ModificationAction using following format: {action: string, value: (string|number)}. It allows to manipulate attribute value using one of the following ModificationAction action values:

"set" - overwrite attribute value using the ModificationAction value. Works identically to the shorter versions using string, number or Array<string> types.

"add" - add the ModificationAction value (or 1, if not specified) to the attribute value.

Note

Works only on numeric attributes.

ModificationAction value can be any number (including negative and fractional numbers).

If the attribute was not used before - creates new numeric attribute and sets its value to 0 before performing action.

"list-add" - add the ModificationAction value to the list of attribute values or extend single value attribute to a list of values. New value will be a list containing previous value(s) in addition to the added value.

Note

Only string values are allowed on the list or can be extended to a list.

List values are unique. Adding value that already was on the list will not modify the list.

"list-remove" - remove the ModificationAction value from the list of attribute values or delete single value attribute. New value will be a list containing previous value(s) without the removed value.

Note

Only string values are allowed on the list.

Example:

{
    "favourite_color": "black",
    "drink": "Martini",
    "code_number": 7,
    "aliases": ["Peter", "Conrad", "Patrick", "Bill"],
    "kill_count": {
        "action": "add",
        "value": 3,
    },
    "favourite_brands": {
        "action": "list-add",
        "value": "Land Rover",
    },
    "current_missions": {
        "action": "list-remove",
        "value": "Casino Royale",
    },
}

options

Optional object Object that can specify additional user identifiers and callback functions.

Example:

{
    "user_id": user_id,
    "device_id": device_id,
    "email": email,
    "onFulfilled": onFulfilled,
    "onRejected": onRejected
}

user_id¶

Optional string If the application lets user sign in - it is possible to pass a unique permanent user ID using this parameter. This will let the Audience Manager better identify users across devices (laptop, phone) and sessions.

Example:

"jbond"

device_id¶

Optional string If the application has access to device ID - it is possible to pass this value using this parameter. This will let the Audience Manager better identify users across sessions.

Example:

"1234567890ABCDEF"

email¶

Optional string If the application identifies user via his email - it is possible to pass this value using this parameter. This will let the Audience Manager better identify users across devices (laptop, phone) and sessions.

Example:

"j.bond@mi6.gov.uk"

onFulfilled(): Optional The fulfilment handler callback (called with result).

onRejected(error_code)

Optional The rejection handler callback (called with error code).

Arguments:	error_code (string) – Required Error code. Example: "server_error"