Developers Guide

Tracking Events

Track Events through NotifyVisitors using Events API.

Suggest Edits

1. Must Read

Before moving onto Tracking Events, it will be most helpful to get a better grasp of System & Custom events and their respective attributes. It will help you to understand the workings of Tracking Events much better. Click here to view Custom Event Templates to get a good understanding.

NotifyVisitors immediately begins tracking once you integrate the SDK. These are referred to as System Events, and they start tracking common user interactions with your app and also your campaigns. Click here to view the System Events that we automatically track for you. You can create your Custom Events that will track your user interactions, important to your business growth. You can further break down each Custom Event into more Event Attributes as:

  • Quantity
  • Price
  • Category

Granular data like this will enable you to engage more users through personalized and contextual campaigns through Omni-channels or all channels of engagement.

📘

Important

What you see as “Platform” in the Custom Events of your NotifyVisitors dashboard is the sdk_id and signifies SDK type.
sdk_id 1 = Web
sdk_id 2 = Android
sdk_id 3 = iOS

2. Tracking Custom Events for iOS

Events API records all the actions that the users perform. It also records any property associated with them. These are used for:

  • Analytics
  • User segmentation
  • To trigger engagements or other actions

All API events are part of the Notifyvisitors Analytics object of iOS SDK. To get an instance of Notifyvisitors Analytics object, find the code below:

notifyvisitors.trackEvents("eventName", attributes: eventAttributes, lifetimeValue: "Ltv", scope: scope)

[notifyvisitors trackEvents: @"eventName" Attributes: attributesDictionary lifetimeValue: @"Ltv" Scope: scope];
PARAMETER USAGE
Event_Name (String) Name of events like sale, register.
  • It is a string value.
  • Use only Alpha Numerics.
  • You can use white spaces or special characters.
  • You can use underscore ‘_’
eventAttributes (NSMutableDictionary) These attributes are associated with the User's Event. Attribute values are passed in the form of NSMutableDictionary:
  • Strings
  • Booleans
  • Numbers
  • Date Attribute values are written using NSString date format
Attribute Name should contain only:
  • Alpha-numerics
  • No spaces
  • Only underscore _
  • Name within " "
  • No special characters. Attribute ends with ;
LifetimeValue (String) For awarding a score point to the user like- “10” or “100”
Scope (Integer) The scope of the event defines whether the event should be tracked every time it occurs, per session, or once in a lifetime. This parameter is used to minimize the duplication of data in analytics. It is an integer whose values are as follows:
  1. Track every time the API is called.
  2. Track once per session.
  3. Track once in a lifetime.
Note: If you give a scope value greater than or equal to 7, that means the event will repeat after the number of days equals the scope value (i.e., if you give a scope value = 10, then that event will repeat after every 10 days).

3. Example for Tracking Event

notifyvisitors.trackEvents("subscribed", attributes: attributesDict, lifetimeValue: "100", scope: 1)

[notifyvisitors trackEvents: @"subscribed" Attributes: attributesDict lifetimeValue: @"100" Scope: 1];

4. Tracking Event Attributes

You can specify a Custom Event Attribute by using NSMutableDictionary. Attach the NSMutableDictionary to the custom event that you would like to track, as specified below

var attributesDictionary: [String : String] = [:]

attributesDictionary["name"] = "John"
attributesDictionary["email"] = "[email protected]" 

let finalAttributesDict = NSMutableDictionary(dictionary: attributesDictionary)

notifyvisitors.trackEvents("subscribed", attributes: finalAttributesDict, lifetimeValue: "100", scope: 1)

NSMutableDictionary *attributesDict = [[NSMutableDictionary alloc] init];


[attributesDict setObject:@"John" forKey:@"name"];
[attributesDict setObject:@"[email protected]" forKey:@"email"];

[notifyvisitors trackEvents: @"subscribed" Attributes: attributesDict lifetimeValue: @"100" Scope: 1];

5. How to Track Complex Event Attributes

  • You can pass complex event attributes with Notifyvisitors as NSMutableDictionary data type.
  • You cannot create segments using complex events attributes.
  • You can use this data for personalizing your campaigns in the following manner:
let detailsProduct1 = ["Size": "L"]
let product1: [String : Any] = ["SKU Code": "UHUH799", "Product Name": "Armani Jeans", "Price": NSNumber(value: 300.49), "Details": detailsProduct1]

let detailsProduct2 = ["Size": "L"]
let product2: [String : Any] = ["SKU Code": "FBHG746", "Product Name": "Hugo Boss Jacket", "Price": NSNumber(value: 507.99), "Details": detailsProduct2]

let deliveryAddress = ["City": "San Francisco","ZIP": "94121"]

let attributesDictionary: [String : Any] = ["Products": [product1, product2], "Delivery Address": deliveryAddress, "Coupons Applied": ["BOGO17"]]

let finalAttributesDict = NSMutableDictionary(dictionary: attributesDictionary)

notifyvisitors.trackEvents("purchased", attributes: finalAttributesDict, lifetimeValue: "100", scope: 1)

NSDictionary *detailsProduct1 = @{@"Size":@"L"};
NSDictionary *product1 = @{@"SKU Code":@"UHUH799", @"Product Name":@"Armani Jeans", @"Price": @300.49, @"Details": detailsProduct1};

NSDictionary *detailsProduct2 = @{@"Size":@"L"};
NSDictionary *product2 = @{@"SKU Code":@"FBHG746", @"Product Name":@"Hugo Boss Jacket", @"Price":@507.99, @"Details":detailsProduct2};

NSDictionary *deliveryAddress = @{@"City":@"San Francisco", @"ZIP":@"94121"};

NSDictionary *attributesDictionary = @{@"Products": @[product1, product2], @"Delivery Address": deliveryAddress, @"Coupons Applied": @[@"BOGO17"]};

[notifyvisitors trackEvents:@"purchased" Attributes: [attributesDictionary mutableCopy] lifetimeValue:@"100" Scope:1];

6. Tracking Event Callback

You can get event result’s callback in the app using notifyvisitorsDelegate Goto the ViewController in which you are triggering events add notifyvisitorsDelegate as shown below.

class ViewController: notifyvisitorsDelegate 

#import "notifyvisitors.h"
@interface ViewController : UIViewController <notifyvisitorsDelegate>

Now set the delegate in the viewdidLoad() method of your ViewController file.

override func viewDidLoad() {
super.viewDidLoad()

notifyvisitors.sharedInstance()?.delegate = self
}

- (void)viewDidLoad {
    [super viewDidLoad];

    [notifyvisitors sharedInstance].delegate = self;
}

Add the following delegate method into the ViewController file to receive the callbacks of events performed.

func notifyvisitorsEventsResponseCallback(_ callback: [AnyHashable : Any]?) {
        print("event callback response = \(callback ?? [:])")
    }

-(void)notifyvisitorsEventsResponseCallback:(NSDictionary *)callback {
NSLog(@"event callback response = %@", callback);
}

This callback response will give you either a success or failure response based on the conversion validation rule as per your event and dashboard setting, some of the sample responses given below for your reference.

Event Success Response

{
  "status" : "success",
  "callbackType" : "event",
  "eventName" : "purchased",
  "attributes" : {
      "SKU Code": "UHUH799",
      "Product Name": "Armani Jeans",
      "Size": "L"
  },
  "type" : 0,
  "message" : "Tracking Conversion successful for subscribed event or this Event Already Performed"
}

Event Failure Response

{
  "status" : "fail",
  "eventName" : "subscribed",
  "type" : 10,
  "callbackType" : "event",
  "message" : "LIFE-CYCLE Events is INACTIVE or Your Account is not Upgraded. Kindly activate lifecycle event from Notifyvisitors Account or Upgrade your account if required"
}

7. Guidelines

  • Names and Custom Event Attribute names will be case sensitive and must be under 50 characters in length.
  • Keep the String attribute values under 1000 characters in length.
  • Custom Event Attributes are of data types like:
  1. NSString
  2. You can use Boolean as it's wrapped type is NSNumber
  3. NSNumber
  4. NSDate
  5. NSArray
  • Event Attributes for a Custom Event cannot exceed 25 times per data type.
  • You cannot create segments for an Event Attribute value that is NSArray or NSDictionary. However, you can use it in personalized campaigns.
  • The first data point declared gets synced with NotifyVisitors. It will define the data type for the event attribute.
  • The data type must be consistent with the value that you store against the attribute. Do not change the data type at a later stage because it will no longer flow to your NotifyVisitors dashboard.

📘

Note

Feel free to contact us at [email protected] if you need further help. We're only an email away!

Updated about 1 month ago

What’s Next