User profile and behaviour tracking

Tagging relevant information regarding your user profiles and their behaviours is crucial to send personalized and valuable messages.

Although the Accengage SDK collects by default certain useful information (such as install date, last open date, number of visits, device model...), it also offers a number of advanced tagging and tracking features for app developers, that will allow you to target notifications, trigger messages at the right time, customize the user experience and analyze your campaign and application performance.

It is important that you check with the product or marketing team what type of actions they would like to perform, so that you can determine which information needs to be tagged. Most of the time they will provide you with a "tagging plan" which lists all of these.

However, a strategy could be to first implement a minimal version of Accengage in order to speed up the process and learn faster, then implement the tagging plan at a later stage for more relevant messages.

In the following section, we will look at the various options that you can enjoy to collect and use the right information:

enrich user profile, thanks to custom device information (or User Attributes), which are very useful for targeting and message personalization
tag user location, for geolocation targeting
tag user behaviours, thanks to events which offer many benefits (targeting, triggering and measurement), as well as views
register users to static lists, in order to manage preferences

Enrich user profile

Custom device informations

In order to send well-targeted and personalized messages, Accengage lets you enrich your user profiles with additional relevant information, called custom device informations.

These are very important for campaign targeting, as well as message personalization.

For instance, if you tag and update the first name of a user, you will be able to personalize a message with Hello ${firstname}.

Traditional usage of custom device information for instance include first name, account ID (to match with external systems), total number of purchases, last purchased product, last purchase date, favorite product...

Custom device informations can be numeric values (set values, or incremental), strings, dates, booleans...

Uniqueness of values

Unlike events, the values of these custom device informations are unique per user. This means the user's associated fields are single-value type fields and each update will erase currently stored values except when it's an incrementation or a decrementation in case of numeric values.

By implementing the library in your app, you will automatically gather certain information about your app users : their device model, iOS version, language, country, time zone, app version, install date, the number of visits and more...

The Accengage library lets you also collect additional custom device information, which can be attached to the user profile through custom database fields.

If the information you would like to track is inside a WebView, please see the Advanced section

Database scheme warning

Make sure that your custom_field is already created in the database (Targeting > Database scheme > Add a field). Otherwise, the data will be ignored ! Check our user guide to have an overview of the database associated to your app and how to create a new field.

To enrich the user profile, and once the database scheme has been updated, you can add additional custom data (or user attributes) using the updateDeviceInformation:withCompletionHandler: method.

First, create the device information set :

Objective-C:

ACCDeviceInformationSet *deviceInfoSet = [[ACCDeviceInformationSet alloc] init];

Swift:

var deviceInfoSet = ACCDeviceInformationSet.init()

Then, you can set, delete, increment or decrement the parameters in a following way:

Objective-C:

// set
[deviceInfoSet setDate:[NSDate date] forKey:@"date"];
[deviceInfoSet setNumber:@100 forKey:@"number"];
[deviceInfoSet setString:@"tagString" forKey:@"string"];
[deviceInfoSet setBoolean:true forKey:@"bool"];

// delete
[deviceInfoSet deleteValueForKey: @"key"];

// increment an existing numerical value
[deviceInfoSet incrementValueBy:@1 forKey:@"numerical_value"];

// decrement an existing numerical value
[deviceInfoSet decrementValueBy:@1 forKey:@"numerical_value"];

Swift:

// set
deviceInfoSet.setDate(NSDate() as Date, forKey: "date")
deviceInfoSet.setNumber(100, forKey: "number")
deviceInfoSet.setString("tagString", forKey: "string")
deviceInfoSet.setBoolean(true, forKey: "bool")

// delete
deviceInfoSet.deleteValue(forKey: "key")

// increment
deviceInfoSet.incrementValue(by: 1, forKey: "numerical_value")

// decrement
deviceInfoSet.decrementValue(by: 1, forKey: "numerical_value")

Finally, call the appropriate SDK method to update your information set:

Objective-C:

[[Accengage profile] updateDeviceInformation:deviceInfoSet withCompletionHandler:^(NSError * _Nullable error) {
    if (error) {
       // handle the error
    }
 }];

Swift:

Accengage.profile().updateDeviceInformation(deviceInfoSet, withCompletionHandler: { error in
    if error != nil {
        // handle the error
    }
})

User geolocation

You can benefit from your user's location data to target them using their past location.

The location data are updated when the user opens the application.

Do not confuse

This user geolocation targeting is not to be confused with real-time geofencing which allows for campaign triggering based on real-time geolocation. See Geofence part.

To update the user's current location, call the following method with a CLLocation object :

Objective-C:

[BMA4SLocationServices updateLocation:location];

Swift:

BMA4SLocationServices.update(location)

Static lists subscriptions

With Accengage, you can use two types of segments : Dynamic segments and Static lists.

A Dynamic Segment is a segment which is defined by one or more criteria. Therefore, it may change as the values in the database are collected, imported, deleted and modified.

A Static List is a set of mobile users whose volume is static at a given time.

Unlike a Dynamic Segment whose volume can evolve according to the criteria defined in the interface, a Static List is a set of mobile users whose volume is static at a given time, in order, for example, to be used during a specific campaign or as an exclusion of a dynamic segment. Once created, a Static List can be populated through the SDK.

The library provides several methods to manage the subscription to static lists.

Required external id

First, make sure that you've created your static list with an externalid. The externalid is required to populate your list through the SDK. To find out more, check out our guide.

In order to subscribe a user to a Static List, create an ACCList object :

Objective-C:

ACCList *list = [ACCList listWithId:@"list_external_id"];

Swift:

let list = ACCList(id: "list_external_id")

You can also set a subscription expiration date. Once your subscription expires, the user will be removed from the Static List automatically.

Objective-C:

ACCList *list = [ACCList listWithId:@"list_external_id" expirationDate:date_object];

Swift:

let list = ACCList(id: "list_external_id", expirationDate:date_object)

Add the user to a list or a set of lists:

Objective-C:

[Accengage subscribeToLists:@[list]];

Swift:

Accengage.subscribe(to: [list])

Subscription Tag

Subscription tag is a new API used to mark user interest for a particular topic.

A subscription tag is defined by a Category and an ID. The category represents a group or a repertory of tag and the ID is just the name of the tag.

The subscription tag can have up to 5 custom parameters. These parameters can be use to personalize your message and/or set an expiration for your tag.

You can set an expiration date for your tag by adding a custom parameter whose key is “exp” and the value is a timestamp. The timestamp must be sent as an Integer.

Device tag information

You can set as many tags as you want per device.

Objective-C:

ACCDeviceTag *tag = [[ACCDeviceTag alloc] initWithCategory:@”Quinté” identifier:@”1234556”];
[tag setString:@"John Doe" forKey:@"jockey name"];
[tag setNumber:1565358190 forKey:@"exp"];
[[Accengage profile] setDeviceTag:tag];

Swift:

let tag = ACCDeviceTag.init(category: "Quinté", identifier: "123456")
tag?.setString("John Doe", forKey: "jockey name")
tag?.setNumber(1565358190, forKey: "exp")
Accengage.profile().setDeviceTag(tag!)

Custom parameter types

Custom parameters that you intent to use for personalization purpose must be NSString, NSNumber, NSDate or BOOL type. If you set an expiration date, please set it as an Integer

Key uniqueness

Each custom parameter key has to be unique.

As mentioned with the name of the method, setDeviceTag is an update of the Subscription Tag, it will then override the previous information.

You can unsubscribe a user from a tag:

Objective-C:

[[Accengage profile] deleteDeviceTag:tag];

Swift:

Accengage.profile().delete(tag!)

Tag usage information

Please note that this feature is only available through Accengage's API. For more information please contact our Support Team at http://ticket.accengage.com

Behaviour tracking

Events tracking

Events are very useful to track user behaviours. One user may have multiple events, and all event occurrences are reported to the Accengage servers.

They can be used for :

In-App message or local push real-time triggering
Application or campaign performance measuring
Message targeting (subject to your app being integrated in the new platform)

You will need to ask Accengage teams to activate events, and then you will be autonomous to create them in the Accengage dashboard (in Settings > Settings > Add an event), so as to select them as triggers or targeting options.

Events are composed of a type (a numeric value which categorizes the type of event - see below), and parameters, which brings more information and can be targeted on (provided you are on the new platform).

The library offers specific and useful methods to track standard events such as "add to cart", "purchases" or "leads". You can also track custom events for other user behaviours.

Currencies norm usage

The specified currency for cart and purchase tracking must be compliant with the current link ISO-4217 standard. If not, the tracking will be ignored.

Add to cart

"Add to cart" events are useful to track and tag the fact that certain items were added to a basket. This is typically useful if you would like to set up "abandoned cart" campaigns, for which you will need to tag "add to cart" events, as well as "purchases".

The library provides a simple method to track items added to a cart. The type of all cart events is 30 but you don't need to specify it.

For example, an iPhone 7 added to a new cart, can be tracked a following way :

Objective-C:

// Create an item object :
ACCCartItem *item = [ACCCartItem itemWithId:@"MN972ZD/A"
                                 name:@"iPhone 7 256GB Black"
                                 brand:@"Apple"
                                 category:@"iPhone"
                                 price:989.
                                 quantity:1];

// Then track it
[Accengage trackCart:@"cart_id" currency:@"EUR" item:item];

Swift:

// Create an item object :
var item = ACCCartItem.init(id: "MN972ZD/A",
                           name: "iPhone 7 256GB Black",
                           brand: "Apple",
                           category: "iPhone",
                           price: 989,
                           quantity: 1)

// Then track it
Accengage.trackCart("cart_id", currency: "EUR", item: item)

If the user adds a new item to the same cart, you should use the same cart_id. For example, if he also adds an iPhone 7 Case to the same cart as the iPhone 7, track it with:

Objective-C:

// First create an item object
ACCCartItem *item = [ACCCartItem itemWithId:@"MMY12ZM/A"
                                 name:@"iPhone 7 Leather Case - Storm Gray"
                                 brand:@"Apple"
                                 category:@"iPhone Case"
                                 price:55.
                                 quantity:1];

// Then track it
[Accengage trackCart:@"same_cart_id" currency:@"EUR" item:item];

Swift:

// First create an item object
let item = ACCCartItem.init(id: "MMY12ZM/A",
                            name: "iPhone 7 Leather Case - Storm Gray",
                            brand: "Apple",
                            category: "iPhone Case",
                            price: 55,
                            quantity: 1)

// Then track it
Accengage.trackCart("same_cart_id", currency: "EUR", item: item)

Purchases

"Purchase" events are very useful to tag your user's purchases within your app, to trigger or target messages based on them, but also to measure the revenues generated overall within your app, and thanks to your notification campaigns. Indeed, Accengage provides a statistic dashboard which measures this information (Statistics > advanced statistics).

The library provides a simple method to track purchases. The type of all purchase events is 50, but you don't need to specify it. It is recommended to specify all the purchased items. For example, the purchase of the previous cart, can be tracked with :

Objective-C:

ACCCartItem *item = [ACCCartItem itemWithId:@"MN972ZD/A"
                                 name:@"iPhone 7 256GB Black"
                                 brand:@"Apple"
                                 category:@"iPhone"
                                 price:989.
                                 quantity:1];

ACCCartItem *item = [ACCCartItem itemWithId:@"MMY12ZM/A"
                                 name:@"iPhone 7 Leather Case - Storm Gray"
                                 brand:@"Apple"
                                 category:@"iPhone Case"
                                 price:55.
                                 quantity:1];

[Accengage trackPurchase:@"purchase_id" currency:@"EUR" items:@[item, item2] amount:nil];

Swift:

let item = ACCCartItem.init(id: "MN972ZD/A",
                            name: "iPhone 7 256GB Black",
                            brand: "Apple",
                            category: "iPhone",
                            price: 989,
                            quantity: 1)

let item2 = ACCCartItem.init(id: "MMY12ZM/A",
                             name: "iPhone 7 Leather Case - Storm Gray",
                             brand: "Apple",
                             category: "iPhone Case",
                             price: 55,
                             quantity: 1)

Accengage.trackPurchase("purchase_id", currency: "EUR", items: [item, item2], amount: nil)

Lead

"Lead" events are useful to track behaviours such as sign-up, registrations etc. The Accengage advanced statistic dashboard will also measure these leads.

The library also provides a simple method to track leads. You might want to track particular special event and action like an authentification. The type of a lead is 10, but once again you don't need to specify it.

For example, a sign-up event, can be tracked with :

Objective-C:

[Accengage trackLead:@"authentification" value:@"sign-up"];

Swift:

Accengage.trackLead("authentification", value: "sign-up")

The total amount is optional when the purchased items are detailed. In this case, the server will calculate it for you. But, if the items set is nil or empty you must specify the total purchase amount.

Uniqueness of values

The purchase_id must be unique. Otherwise, the tracking will be ignored by the server.

Custom events

Apart from the special events seen above, you can tag and track any other event that will be useful for message triggering or targeting, thanks to custom events, such as "clicked on a certain button", "made a search, "invited a friend"...

For all of these custom events, use thetrackEvent: method.

Events types up to 1000 are reserved for the library internal usage. You can use custom event types starting from 1001, and you must specify them.

Maximum parameter length

Please note that the length of your concatenated parameters is restricted to 1024 characters: if you exceed this limitation, the SDK will truncate the value.

Create a CustomEventParams object

Objective-C:

//Instantiate a CustomEventParams object
ACCCustomEventParams *customEventParams = [[ACCCustomEventParams alloc] init];

Swift:

 //Instantiate a CustomEventParams object
var customEventParams = ACCCustomEventParams()

Add parameters to CustomEventParams object

Four types of parameters are supported : NSString, NSNumber, BOOL and NSDate.

Objective-C:

//Add a NSString to our previously created CustomEventParams object
[customEventParams setString:@"myString" forKey:@"myKey"];

//Add a NSNumber
[customEventParams setNumber:[NSNumber numberWithInteger:4] forKey:@"mySecondKey"];

//Add a BOOL
[customEventParams setBoolean:YES forKey:@"myThirdKey"];

//Add a NSDate
[customEventParams setDate:[NSDate date] forKey:@"myFourthKey"];

Swift:

//Add a NSString to our previously created CustomEventParams object
customEventParams.set("myString", forKey: "myKey")

//Add a NSNumber
customEventParams.setNumber(4, forKey: "mySecondKey")

//Add a BOOL
customEventParams.setBoolean(true, forKey: "myThirdKey")

//Add a NSDate
customEventParams.setDate(Date(), forKey: "myFourthKey")

Track the event

Finally you can track the event you just created by using the Accengage's class trackEvent method :

Objective-C:

//First parameter is the type of the event. Custom events type should be greater than or equal to 1001. The second parameter is the CustomEventParams object we previously created.
[Accengage trackEvent:1001 withCustomParameters:customEventParams];

Swift:

//First parameter is the type of the event. Custom events type should be greater than or equal to 1001. The second parameter is the CustomEventParams object we previously created.
Accengage.trackEvent(1001, withCustomParameters: customEventParams)

Event definition

Each event needs to be defined in the Accengage User Interface. Go to Settings > Advanced Settings, and add a new event of type Custom with the code used in trackEvent method. The label is only used for a display purpose.

Views

In order to offer the best user experience, and let you trigger In-App messages at the most relevant time, on the right view (or avoid displaying them on certain views), the Accengage library allows you to track screens or views within your app.

Unlike events, view tracking is not reported to our servers.

Don't forget to configure your views in the Accengage dashboard (Settings > Settings > Add a view) to display an understandable label for your product or marketing teams, and so that they can select them.

Tracking recommendation

We recommend exhaustively tracking every visible view in your app.

The library offers an easy way to track a screen display and dismiss, you just need to import the Accengage.h and set the accengageAlias in the viewDidLoad: method:

Objective-C:

import <Accengage/Accengage.h>

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.accengageAlias = @"controller_id";
    // Do any additional setup after loading the view, typically from a nib.
}

@end

Swift:

import Accengage

class ViewController {
    func viewDidLoad() {
        super.viewDidLoad()
        accengageAlias = "controller_id"
        // Do any additional setup after loading the view, typically from a nib.
    }
}

But if you prefer to track screens manually, you'll need to call the method trackScreenDisplay: in the viewDidAppear: method of your controller and the trackScreenDismiss: in viewDidDisappear:.

Objective-C:

#import <Accengage/Accengage.h>

@interface ViewController ()

@end


@implementation ViewController

- (void)viewDidLoad {

    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.
}

- (void)viewDidAppear:(BOOL)animated {

    [super viewDidAppear:animated];
    [Accengage trackScreenDisplay:@"controller_id"];
}

- (void)viewDidDisappear:(BOOL)animated {

    [super viewDidDisappear:animated];
    [Accengage trackScreenDismiss:@"controller_id"];
}

@end

Swift:

import Accengage

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
    }

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        Accengage.trackScreenDisplay("controller_id")
    }

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        Accengage.trackScreenDismiss("controller_id")
    }
}

States

States allow you to trigger In-App messages or scheduled alarms.

To use this feature, you need to declare the states on Accengage dashboard (Settings > States) and then use them as a trigger.

To set a state :

Objective-C:

[Accengage setState:stateValue forKey:stateName];

Swift:

Accengage.setState(stateValue, forKey: stateName)

To delete a state :

Objective-C:

[Accengage setState:nil forKey:stateName];

Swift:

Accengage.setState(nil, forKey: stateName)

Embedded web content tracking

If your application is hybrid and embeds webviews, you will probably want to tag certain information contained in your webviews.

In that case, the regular methods of Update Device Information, or Events cannot be used, but tagging these information is possible if you follow the below instructions.

Web content tracking

In order to activate web content tracking, please contact your Accengage Project Manager for the exact procedure.

WKWebView

Simply replace the WKWebView component with the ACCWKWebView. But if you prefer avoiding the use of a subclass, you could implement the tracking manually.

Inject the Accengage WKUserScript to your WKUserContentController:

Objective-C:

WKUserContentController *contentController = [WKUserContentController new];
NSString *script = [Accengage trackingScriptForWebView:ACCWKWebViewFramework];
if (script) {
    WKUserScript *userScript = [[WKUserScript alloc] initWithSource:script
                                                  injectionTime:WKUserScriptInjectionTimeAtDocumentEnd
                                               forMainFrameOnly:YES];
    [contentController addUserScript:userScript];
}

Swift:

let contentController = WKUserContentController()
if let script = Accengage.trackingScript(forWebView: .ACCWKWebViewFramework) {
    let userScript = WKUserScript(source: script, injectionTime: .atDocumentStart, forMainFrameOnly: true)
    contentController.addUserScript(userScript)
}

Add the handler for the Accengage messages:

Objective-C:

if (script) {
    //...
    for (NSString *name in [Accengage scriptMessagesNames]) {
        [contentController addScriptMessageHandler:self name:name];
    }
}

Swift:

if let script = Accengage.trackingScript(forWebView: .ACCWKWebViewFramework) {
    //...
    for name in Accengage.scriptMessagesNames() {
        contentController.add(self, name:name)
    }
}

Initialize your WKWebView:

Objective-C:

WKWebViewConfiguration *configuration = [WKWebViewConfiguration new];
configuration.userContentController = contentController;
self.webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:configuration];

Swift:

let configuration = WKWebViewConfiguration()
configuration.userContentController = contentController
self.webView = WKWebView(frame: self.view.bounds, configuration: configuration)

Handle the Accengage messages:

Objective-C:

- (void)userContentController:(WKUserContentController *)userContentController
      didReceiveScriptMessage:(WKScriptMessage *)message {
    if ([Accengage didReceiveScriptMessageWithName:message.name body:message.body]) {
        return;
    }
}

Swift:

func userContentController(userContentController: WKUserContentController, didReceiveScriptMessage message: WKScriptMessage!) {
    if Accengage.didReceiveScriptMessage(withName: message.name, body: message.body) {
        return
    }
}

Once you've integrated the right component, you can now tag your web content.

To do so, follow this documentation.

Don't forget, as for regular custom user data or events, to declare them inside the Accengage dashboard.

Table of contents

User profile and behaviour tracking
Enrich user profile
Custom device informations
User geolocation
Static lists subscriptions
Subscription Tag
Behaviour tracking
Events tracking
Views
States
Embedded web content tracking