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...

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

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.

  1. First, create the device information set :

Objective-C:

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

Swift:

var deviceInfoSet = ACCDeviceInformationSet.init()
  1. 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")
  1. 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.

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.

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.

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!)

You can unsubscribe a user from a tag:

Objective-C:

[[Accengage profile] deleteDeviceTag:tag];

Swift:

Accengage.profile().delete(tag!)

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.

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.

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.

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)

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.

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.

First, follow one of those next steps depending on the component you're using: UIWebView or WKWebView.

UIWebView

If you're using the UIWebView component, just replace it with the A4SWebView.

WKWebView

If you're using the WKWebView component, you can simply replace it with the ACCWKWebView. But if you prefer avoiding the use of a subclass, you could implement the tracking manually.

  1. 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)
    }
  2. 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)
        }
    }
  3. 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)
  4. 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.