Opt-in & preferences management
Check out the "Quick start" before going into this case!
Introduction
When you manage a website that hosts a personal space to let visitors create their account, it's important to make the synchronization between your website and ACTITO smooth and quick as possible.
Overall when dealing with subscription/opt-in management, you must observe GDPR requirements regardless of your technical architecture. This essentially means having information synchronized continuously between your website and ACTITO.
Let's consider a practical case:
- All along the day, new users create their account on your website.
- After having validated his account creation, the created user is to receive a confirmation e-mail with a link to a preferences center landing page (that's a standard feature of ACTITO). He can, on this page, choose between many e-mail subscriptions to define which communications he will receive from your brand.
- You wish your system to be notified of the new user subscriptions choices and of any further modifications from this preferences center to keep your system up-to-date.
Step by Step
- Set up a webhook for profile subscriptions
- Trigger a transactional confirmation e-mail
- Receive and process the subscriptions webhook events
- Set up a profile table with desired attributes and subscriptions
- Set up your preferences center landing page with relevant profile subscriptions enrichment rules related to this table
- Set up a transaction e-mail with a link to this landing page
For those prerequisites, contact your marketeer or check our online documentation. After having those elements created in ACTITO, you'll have to obtain their technical names, so as to use them in the APIs calls described below.
Step 1. Set up a webhook for profile subscriptions
You must first prepare ACTITO to start listening to subscriptions/unsubscriptions events in the desired profile table.
This can be done by creating a new UPDATED_SUBSCRIPTIONS profile table event webhook.
Stating that your profile table is Accounts (with technical id 10) within the entity MyEntity, and that you wish ACTITO to push the events toward https://yourdomain.com/actito-subscriptions, call the following route to create this webhook :
POST /webhooks/v4/entity/MyEntity/webhookSubscription
The body of your request should be:
{
"on": "PROFILE_TABLE",
"onElementId": "10",
"eventType": "UPDATED_SUBSCRIPTIONS",
"targetUrl": "https://yourdomain.com/actito-subscriptions",
"isActive": false
}
You'll then receive a 200 OK http response with a JSON body containing the technical id of the created webhook:
{
"webhookSubscriptionId": 123456
}
Once your endpoint is available and reachable online, you can activate the webhook.
ACTITO will then start to listen to subscriptions/unsubscriptions events on your Accounts profile table and to post them to your endpoint.
As security is an important matter, you can ensure that the calls that reach this endpoint come from ACTITO by defining a shared secret header.
You will in consequence be able to validate any incoming post headers to verify the presence of this shared header.
Here is the call to set the header and to activate the formerly created webhook:
PUT /webhooks/v4/entity/MyEntity/webhookSubscription/123456
{
"headers": {
"X-Origin": "webhook-actito-subscriptions-d4d58fl$DDvnjgf!"
},
"isActive": true
}
You are now ready to receive subscriptions/unsubscriptions from ACTITO!
NB : this step is a pre-condition, it has to be done only once and has not to be automated.
For a comprehensive knowledge of ACTITO Webhooks usage, take a look at the Webhooks section of this portal.
Step 2. Trigger a transactional confirmation e-mail
You can now start triggering confirmation e-mails each time a user creates an account on your website.
Stating that your transactional e-mail campaign is named ConfirmationEmail, triggering it can be done by calling the following route of the TRANSACTIONAL SENDINGS API:
POST /transactional-sendings/v4/entity/MyEntity/transactionalmail/ConfirmationEmail/contact
This route will first match an existing profile or create it if not found, before sending the e-mail to the found/created profile.
For that purpose you should provided a JSON request body like the following when calling this route:
{
"profile": {
"attributes": [
{
"name": "emailAddress",
"value": "john.smith@actito.com"
},
{
"name": "lastName",
"value": "Smith"
},
{
"name": "firstName",
"value": "John"
},
{
"name": "customerId",
"value": 111444777
}
],
"dataCollection": {
"source": "AGDPRSource",
"way": "AGDPRWay",
"date": "10/09/2019 22:00:00"
}
},
"parameters": [
{
"key": "accountType",
"values": [
"NEWSUBSCRIBER"
]
},
{
"key": "websiteLanguage",
"values": [
"EN"
]
}
]
}
The e-mail will then be sent to john.smith@actito.com and the user will then be able to click on its preferences center link that guides to the form which will allow him to define his subscription choices.
Once submitted, ACTITO profile enrichment process will update the corresponding profile with the subscriptions from the preferences center form.
And this enrichment will trigger the events that the activated webhook is waiting for!
Step 3. Receive and process the subscriptions webhook events
Now users are subscribing on your account creation form, you start to receive calls from ACTITO Webhooks to your endpoint.
Those webhook calls will be http POST calls, including the headers your defined, with a JSON request body that contains the concerned events data. In our case, stating that the user has subscribed to the subscriptions Newsletter and Promotions, the body should look like:
{
"id": "d7ab32ee-e36d-4feb-8a14-bf55df768722",
"data": {
"profileId": 125,
"businessKey": "john.smith@actito.com",
"Newsletter": true,
"Promotions": true,
"dataCollectionMoment": "2019-09-20 10:00:00",
"dataCollectionSource": "PreferencesCenter",
"dataCollectionWay": "Form",
"_links": {
"profile": {
"href": "/v4/entity/MyEntity/table/Accounts/profile/125"
}
}
},
"_links": {
"webhook": {
"href": "/v4/entity/MyEntity/webhookSubscription/123456"
}
}
}
In that sample, you can see that the data object contains all the information of the updated profile: id and business key, concerned subscriptions and GDPR data collection information.
That's all you need to maintain an up-to-date information state in your own system!
A similar case should be to push the new user account via the Profile creation route of our PROFILES API, and to set up an ACTITO Scenario that reacts to profile creations to trigger the confirmation e-mail. In that case, the preferences center set up and the webhook definition described in this page are still available. You can therefore migrate from one e-mail triggering mode to the other without having to change your webhook setup and endpoint development!