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 onppms.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 visitor. 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 visitor belongs to.
Code:
ppms.am.api("getAudiences", onFulfilled, onRejected);
-
onFulfilled
(audience_list)¶ The fulfilment handler callback (called with result).
Arguments:
-
onRejected
(error_code)¶ The rejection handler callback (called with error code).
Arguments: - error_code (string) –
Required Error code.
Example:
"server_error"
- error_code (string) –
Check user membership in the audience¶
Checks if the visitor 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:
-
onRejected
(error_code) The rejection handler callback (called with error code).
Arguments: - error_code (string) –
Required Error code.
Example:
"server_error"
- error_code (string) –
Get user attributes¶
Fetches the visitor profile attributes. The visitor 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 visitor 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 visitor attributes divided by source.
- analytics -
Object<string,string>
Contains analytics attributes about the visitor (e.g. browser name, browser version, country). - attributes -
Object<string,(string|number|Array<string>)>
Contains custom attributes about the visitor (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" } }
- analytics -
- attributes (Object<string,Object<string,(string|number|Array<string>)>>) –
-
onRejected
(error_code) The rejection handler callback (called with error code).
Arguments: - error_code (string) –
Required Error code.
Example:
"server_error"
- error_code (string) –
Update user attributes¶
Creates or updates visitor 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 namevalue (
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 newtext
attribute.number
- overwrite the attribute value with the new value. If the attribute was not used before - creates newnumeric
attribute.Array<string>
- overwrite the attribute value with the new set of values. If the attribute was not used before - creates newtext
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 followingModificationAction
action
values:"set"
- overwrite attribute value using theModificationAction
value
. Works identically to the shorter versions usingstring
,number
orArray<string>
types."add"
- add theModificationAction
value
(or1
, if not specified) to the attribute value.Note
- Works only on
numeric
attributes. ModificationAction
value
can be anynumber
(including negative and fractional numbers).- If the attribute was not used before - creates new
numeric
attribute and sets its value to0
before performing action.
- Works only on
"list-add"
- add theModificationAction
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 theModificationAction
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 visitor 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 visitor 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 visitor 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"
- error_code (string) –
-