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.

Configuration:

  • String XXX-XXX-XXX-XXX-XXX should be replaced with app ID (e.g. efcd98a5-335b-48b0-ab17-bf43f1c542be).
  • String ppms.example.com should be replaced with your PPMS domain name (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]||{};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://ppms.example.com/audiences/static/widget/audience-manager.api.min.js","ppms","am","api");

    ppms.am.api("create", "XXX-XXX-XXX-XXX-XXX", "ppms.example.com");
</script>

This code initializes the API interface in the following ways:

  1. Creates a <script> tag that asynchronously loads the Audience Manager API library.
  2. Initializes the global ppms.am.api command queue that schedules commands to be run when the API library is loaded.
  3. Schedules create command on ppms.am.api to initialize the API object with a basic PPMS 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 PPMS 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>>) –

    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> Contains custom attributes about the user (e.g. first name, last name, email).

    Example:

    {
        "analytics": {
            "browser_name": "chrome",
            "country": "us"
        },
        "attributes": {
            "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|object)> Object containing attributes to update:

  • key (string) - attribute name

  • value (string|number|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.

    • 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 or number 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.

Example:

{
    "favourite_color": "black",
    "drink": "Martini",
    "code_number": 7,
    "kill_count": {
        "action": "add",
        "value": 3,
    }
}
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"