Webservices related to Goals

ACTITO 'Goals' enable you to identify people who visit your website and to retrieve information about their behavior on your site: page visits and order confirmations.

When a profile reaches a goal, ACTITO will record an interaction between the goal and this profile. In addition to being used in statistics, goals can be used to target profiles, to add them to a segment or to trigger communications.

Creating a goal is not possible through API. It has to be done via the ACTITO interface. Moreover, an operation must be done on your website, on any page targeted by the goal. For additional information on this subject, we invite you to read the chapter dedicated to 'Goals'.

However, webservices related to goals enable you to:

  • Retrieve the list of existing goals

  • Retrieve the definition of a specific goal

  • Retrieve the ActId of a profile

  • Creating a transaction goal interaction

images/download/attachments/615292671/image2019-5-8_15-11-34.png

Getting information about existing goals

Retrieving the list of existing goals for an entity

It is possible to retrieve the list of existing goals for an entity, with their characteristics. This allows you to obtain the state of your goals without using the ACTITO interface.

To do so, you will need to use the operation GET/entity/{e}/goals

The only mandatory parameter is the name or the id of the entity to which the goals belongs. In addition, you can specify query parameters to filter your results:

  • Type filter: you can choose to only retrieve transaction goals or web page visit goals

  • Status filter: you can choose to only retrieve active, inactive or in definition goals

images/download/attachments/615292671/image2019-4-29_9-58-27.png

You will obtain the list of existing goals for the entity, with details pertaining to the following elements:

  • The goal technical id: this is an auto-generated number

  • The goal name: this is the display name that you chose at the goal creation. It can be modified in the ACTITO interface

  • The id of the profile table targeted by the goal

  • The id of the entity to which the goal belongs

  • The goal type: whether it is a transaction goal or a web page visit goal

  • The goal status: whether the goal is active, inactive or still in definition

  • The goal creation moment and its latest update moment

Example of a request and its response: GET/entity/{e}/goals.docx

GET/entity/{e}/goals
Curl call
 
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/goals?status=ACTIVE"
 
Response body
{
"items": [
{
"id": "9",
"name": "DocGoalTransac",
"profileTableId": 45,
"entityId": 1,
"type": "TRANSACTION",
"status": "ACTIVE",
"createdAt": "06-03-2019 09:40:14",
"updatedAt": "06-03-2019 09:40:14"
},
{
"id": "8",
"name": "DocGoalVisit",
"profileTableId": 45,
"entityId": 1,
"type": "WEBSITE_VISIT",
"status": "ACTIVE",
"createdAt": "06-03-2019 09:39:41",
"updatedAt": "29-04-2019 09:42:50"
},
{
"id": "5",
"name": "Visit homepage webshop",
"profileTableId": 17,
"entityId": 1,
"type": "WEBSITE_VISIT",
"status": "ACTIVE",
"createdAt": "20-06-2018 13:30:19",
"updatedAt": "20-06-2018 13:30:19"
}
]
}

Retrieving the definition of a goal

You can retrieve the characteristics of a specific goal through the operation GET/entity/{e}/goals/{g}

You will need to provide the following parameters:

  • The name or the id of the entity to which the goal belongs

  • The auto-generated id or the display name of the goal

images/download/attachments/615292671/image2019-4-29_10-30-43.png You will obtain a response with the same elements and the same structure as the previous operation.

Recording goals through an external system

The main way of recording a goal is thanks to the interaction between the script inserted on your web pages and the cookie generated when a profile clicks on a link found in an ACTITO e-mail for which goal tracking is activated.

This would entail that only profile who already received and clicked in an ACTITO e-mail can reach goals. Thanks to the high connectivity that can be achieved through the ACTITO, you can nevertheless record goal interactions for a profile who reached a goal via an external system.

Two possibilities are available :

  • Generating the cookie yourself by retrieving the ActId of a profile

  • Creating a transaction goal interaction through API

Retrieving the ActId of a profile

The concept of ActId refers to the unique id which is used to link a given profile to a goal. It is stored on a cookie dropped on the browser of the user. Its interaction with the script inserted on your web pages is necessary for goals to function properly.

This cookie is usually set through the means of an ACTITO e-mail. However, in order to offer connectivity between ACTITO and the various partner platforms or systems specific to your business, you can create this cookie yourself and drop it through any mean relevant to your activity (for example, after connecting to a customer area). This alternative will notably allow you to record goals for profiles who never clicked in an ACTITO e-mail.

To create this cookie, you will need to retrieve the ActiId of each profile. This is possible through the operation GET/entity/{e}/goal/table/{t}/profile{p}

images/download/attachments/615292671/image2019-4-26_17-19-24.png

The following parameters are required for this operation:

  • e = the entity in which the table belongs

  • t = the name of the profile table

  • p = the ID of the profile (profileId) or a key attribute (for instance, the e-mail address). In the second case, you need to use format 'keyAttribute=value' (for example, emailAddress=mailtest@actito.com).

Example of a request and its response:

GET/entity/{e}/goal/table/{t}/profile/{p}
Curl call
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/goal/table/demodoc/profile/1147696"
 
 
Response body
{
"actId": "ebwp0YMB8s0j3CMkbjKAdZJ1bR7khe25PUBhQPbUPoCmZHJC_8wqozAtO_t2OrII"
}

The response to this request is the ActId of the selected profile.

Creating a transaction goal interaction

It is possible to create a transaction goal interaction for a given profile through the operation POST/entity/{e}/goals/{g}/profile/{p}/transaction

This allows you to record a transaction goal whatever might be the source that led to this transaction.

images/download/attachments/615292671/image2019-5-7_11-54-34.png

To create a transaction goal interaction, you will need to provided the following parameters:

  • The entity to which the goal belongs

  • The goal: you can either use the name of the goal you chose when creating or editing the goal, or its auto-generated technical id

  • The profile who reached the goal: you will need to provide its "profileId"

  • "transactionGoalInteraction": this is a JSON code containing the additional parameters specific to a transaction goal. Just as for the script that can inserted on your website, these parameters are:

    • amountCent: The transaction amount, in cents. In the ACTITO interface, this amount will be converted into €.

    • businessId: The key ID of the transaction.

    • comment: A comment associated with the transaction. You can choose what you want this field to display.

    • source: The source of the transaction. When creating the interaction through API, you can parameter this field to state the origin of the transaction.

Example of a request and its response: (Download this example)

POST/entity/{e}/goals/{g}/profile/{p}/transaction
Curl call
 
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"amountInCents\": 13502,
\"businessId\": \"Order 55\",
\"comment\": \"Product 1\",
\"source\": \"website\"
}" "https://development.actito.be/ActitoWebServices/ws/v4/entity/actito/goals/DemoDocTransac/profile/28704/transaction"
 
Response body
{
"id": 3629370
}

The response to this request will be the interaction id.