How to integrate ACTITO API into Kentico Xperience 13 Core MVC website?
Introduction
Integrate ACTITO API into Kentico Xperience 13 Core MVC website seamlessly. Explore the benefits, step-by-step instructions, and best practices in this comprehensive guide. Enhance marketing efforts and customer experiences. Let's unlock the potential of ACTITO API within Kentico!
ACTITO is a marketing automation platform that helps businesses optimize customer engagement through personalized campaigns, data management, and analytics.
Prerequisites
- ACTITO Subscription
- ACTITO API User access
Step 1: Create API User
To begin the integration process, an API user must be created by the admin user. Once created, you will be provided with an API KEY, which will be in the format: qhdfbvdh747R49FRHrthqhdfbvdh74 (sample ID).
Step 2: To generate a token, implement the code using the provided API.
To generate a token, you need to utilize the API available at https://api1.actito.com/auth/token. Make sure to use your API Key for authentication. The generated token will remain valid for 15 minutes, after which you'll need to generate a new one.
/// <summary>
/// GetAccessTokenAsync
/// </summary>
/// <returns></returns>
public static async Task<string?> GetAccessTokenAsync()
{
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Add("Authorization", “<User API Code>”);
try
{
var response = await client.GetAsync(“https://api1.actito.com/auth/token”);
response.EnsureSuccessStatusCode();
var data = await response.Content.ReadAsStringAsync();
return data;
}
catch (HttpRequestException ex)
{
Service.Resolve<IEventLogService>().LogException(nameof(ActitoHelper), nameof(ActitoHelper), ex);
return string.Empty;
}
}
}
Documentation Reference URL - https://developers.actito.com/docs/integration-framework/apis/authentication/api-key/
Step 3: Implement code for call create or Update profile API
3.1 Before implementing the API call, it is necessary to create the required classes for the API body.
public class ActitoModel
{
/// <summary>
/// name
/// </summary>
public string? name { get; set; }
/// <summary>
/// value
/// </summary>
public string? value { get; set; }
}
public class DataCollectionInformation
{
/// <summary>
/// date
/// </summary>
public string? date { get; set; }
/// <summary>
/// source
/// </summary>
public string? source { get; set; }
/// <summary>
/// way
/// </summary>
public string? way { get; set; }
}
public class Subscription
{
/// <summary>
/// name
/// </summary>
public string? name { get; set; }
/// <summary>
/// subscribe
/// </summary>
public string? subscribe { get; set; }
}
public class RootObject
{
/// <summary>
/// attributes
/// </summary>
public List<ActitoModel>? attributes { get; set; }
/// <summary>
/// dataCollectionInformation
/// </summary>
public DataCollectionInformation? dataCollectionInformation { get; set; }
/// <summary>
/// subscriptions
/// </summary>
public List<Subscription>? subscriptions { get; set; }
}
public class ResponseData
{
/// <summary>
/// profileId
/// </summary>
public string? profileId { get; set; }
}
3.2. To perform the API call for "create or update a profile," utilize the URL: https://api.actito.com/v4/entity/{e}/table/{t}/profile. In this URL, {e} represents the name of the entity associated with the license where the database is located, and {t} denotes the name of the profile table from the ACTITO Dashboard.
public static async Task<string> PostACTITODataAsync(string email, string firstName, string language, string persona, bool isCustomPersona = false)
{
var accessTokendata = await GetAccessTokenAsync();
DateTime currentDate = DateTime.Now;
string formattedDate = currentDate.ToString("dd/MM/yyyy");
string CurrentDate = formattedDate.Replace("-", "/");
var tokenObject = JObject.Parse(accessTokendata!);
// Extract the access token
var accessToken = (string)tokenObject["accessToken"]!;
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
try
{
var data = new RootObject
{
attributes = new List<ActitoModel>
{
new ActitoModel
{
name = "emailAddress",
value = email
}
},
dataCollectionInformation = new DataCollectionInformation
{
date = CurrentDate,
source = "TEST",
way = "api profile 1"
},
subscriptions = new List<Subscription>
{
new Subscription
{
name = "Newsletter",
subscribe = "true"
}
}
};
var dataJson = JsonConvert.SerializeObject(data);
var content = new StringContent(dataJson, Encoding.UTF8, "application/json");
var response = await client.PostAsync(actitoCreateProfileAPI, content);
response.EnsureSuccessStatusCode();
if (response.IsSuccessStatusCode)
{
return response.StatusCode.ToString();
}
else
{
return "Request failed with status code: " + response.StatusCode;
}
}
catch (HttpRequestException ex)
{
Service.Resolve<IEventLogService>().LogException(nameof(ActitoHelper), nameof(ActitoHelper), ex);
return string.Empty!;
}
}
}
The API body can include various types of information such as attributes (e.g., email, name, last name), data collection information (optional), subscriptions (to determine marketing communication eligibility), and segmentations (optional). Please ensure that the attributes you use in the API body are correctly created in the ACTITO database, with accurate technical names. It is important to note that the EmailAddress attribute is mandatory since it serves as the unique ID for the table.
In Step 4, the API needs to be called in the front end of the website. The form on the page includes an Email Address field for subscribing to the newsletter.
<input type="text" class="form-control txtSubscribeEmail" placeholder="Your Email">
<button type="button" class="btn btn-primary" onclick='ACTITOSubscriptionForm($(this)")' data-url="@Url.Action("ActitoSubscriptionForm", "SubscriptionFormWidget")" >
<span class="d-none d-md-flex">@form.ButtonText</span>
<i class="fa-solid fa-arrow-right d-md-none"></i>
</button>
<span id="successMsg" class="success-msg" style="display:none;">Success</span>
Controller: SubscriptionFormWidgetController.cs
public class SubscriptionFormWidgetController : Controller
{
// ACTITO Method
[HttpPost]
[Route("SubscriptionFormWidget/ActitoSubscriptionForm")]
public string ActitoSubscriptionForm(string emailAddress)
{
string actitoStatus = string.Empty;
bool isCustomPersona = false;
try
{
actitoStatus = ActitoHelper.PostACTITODataAsync(emailAddress).Result;
return actitoStatus;
}
catch (Exception ex)
{
Service.Resolve<IEventLogService>().LogException(nameof(SubscriptionFormWidgetController), nameof(Index), ex);
return actitoStatus;
}
}
}
function 'ACTITOSubscriptionForm (elem, emailId) {
let ActITOStatus = "";
let url = "/SubscriptionFormWidget/ActitoSubscriptionForm";
let persona = ($(elem).attr("data-Persona") != undefined && $(elem).attr("data-Persona") != null && $(elem).attr("data-Persona") != "") ? $(elem).attr("data-Persona") : "";
let pathName = window.location.pathname;
if (emailId != undefined && emailId != null && emailId.trim() != "") {
$.ajax({
type: "POST",
url: url,
data: { emailAddress: emailId, persona: persona, pathName: pathName },
async: false,
dataType: 'text',
success: function (data) {
ActITOStatus = data;
},
error: function () {
ActITOStatus = "failed";
}
});
}
return ActITOStatus;
}
