📘
Wait. Are you ready for this part?
In this article, we'll show you the methods that are available in the SDK and how you can use these methods to track events on your app. However, this cannot work until you already have the SDK in your project and you can use it in your app. If not, then we suggest that you do those things first and then come back here to track events in your app.
It's absolutely not complicated. We promise. And, like earlier, we'll wait. No pressure. ☺️

Our SDK, along with the API, provides features that you can use to track events on your app, such as:

User checks in on the app
Identify the user
User adds a product to the cart
User checks out the product
User buys a product

The SDK can:

Track events on the app based on its methods that you use in your code
Track events out-of-the-box

Events that you can track on your iOS app using the methods in the SDK

The list above represents some of the events that occur on your app that the SDK can track. Use the methods described below to track such events.

Custom events

Use the trackEventForEventName method to track custom events with custom attributes in your app.

Here's how to use it:

// Track custom event 
BlueShift.sharedInstance()?.trackEvent(forEventName: "your_custom_event_name", canBatchThisEvent: false)

// Track custom event with additional params
let dictionary = ["name": "Ross", "profession":"palaeontologist"]
BlueShift.sharedInstance()?.trackEvent(forEventName: "your_custom_event_name", andParameters: dictionary, canBatchThisEvent: false)

// Track custom event
[[BlueShift sharedInstance] trackEventForEventName:@"your_custom_event_name" canBatchThisEvent:YES];

// Track custom event with additional params
NSDictionary *params = @{
                            @"name":@"Ross Geller",
                            @"profession":@"paleontologist"
                        }
[[BlueShift sharedInstance] trackEventForEventName:@"your_custom_event_name" andParameters:params canBatchThisEvent:NO];

Identify a user

The identifyUser event is used to identify the end-user who signed into the app. The primary identifier used to identify a user is device_id which is passed to the Blueshift. The device_id is set during the SDK initialization, and it is automatically sent to Blueshift. In addition to sending the device_id, we recommend that you set the email and customer_id of the user to the BlueShiftUserInfo class as mentioned here. This ensures that we can still attribute the events to the user and generate recommendations for the user if the device_id resets due to the app uninstall.

Identify call is responsible to update the data for the user profile on the Blueshift server. Whenever any BlueshiftUserInfo data gets changed, we recommend you fire an identify call to reflect those changes on the Blueshift server.

Here's how to use it:

//Identify user using email id
BlueShiftUserInfo.sharedInstance()?.email = "User Email ID"
BlueShiftUserInfo.sharedInstance()?.save()
BlueShift.sharedInstance()?.identifyUser(withDetails:nil, canBatchThisEvent: false)

//Identify user with customer id
BlueShiftUserInfo.sharedInstance()?.retailerCustomerID = "User Customer ID"
BlueShiftUserInfo.sharedInstance()?.save()
BlueShift.sharedInstance()?.identifyUser(withDetails:nil, canBatchThisEvent: false)

//Identify user with device id
 BlueShift.sharedInstance()?.identifyUser(withDetails:nil, canBatchThisEvent: false)

//Identify user with custom details
let details = ["name": "Ross Geller", "profession":"palaeontologist", "phone_number":"+919999999999"]
BlueShift.sharedInstance()?.identifyUser(withDetails:details, canBatchThisEvent: false)

//Identify user using email id
[[BlueShiftUserInfo sharedInstance] setEmail:@"User Email ID"];
[[BlueShiftUserInfo sharedInstance] save];
[[BlueShift sharedInstance] identifyUserWithEmail:@"User Email ID" andDetails:nil canBatchThisEvent:NO];

//Identify user with customer id
[[BlueShiftUserInfo sharedInstance] setRetailerCustomerID: "User Customer ID"];
[[BlueShiftUserInfo sharedInstance] save];
[[BlueShift sharedInstance] identifyUserWithDetails:nil canBatchThisEvent:NO];

//Identify user with device id.
[[BlueShift sharedInstance] identifyUserWithDetails:nil canBatchThisEvent:NO];

//Identify user with custom details
NSDictionary *details = @{  @"name":@"Ross Geller",
                            @"profession":@"paleontologist", 
                            @"phone_number":@"+919999999999"}
[[BlueShift sharedInstance] identifyUserWithDetails:details canBatchThisEvent:NO];

Screen view

Use the trackScreenViewedForViewController method to send the pageload event that tracks the screen a user visits.

Here's how to use it:

//Track screen view
BlueShift.sharedInstance()?.trackScreenViewed(for: self, canBatchThisEvent: false)

//Track screen view with details
let details = ["launchDetails": "PushNotificationDeepLink"]
BlueShift.sharedInstance()?.trackScreenViewed(for: self, withParameters: details, canBatchThisEvent: false)

//Track screen view
[[BlueShift sharedInstance] trackScreenViewedForViewController:self canBatchThisEvent:NO];

//Track screen view with details
NSDictionary *details = @{  @"launchDetails":@"PushNotificationDeepLink" }
[[BlueShift sharedInstance] trackScreenViewedForViewController:self withParameters:parametersDictionary canBatchThisEvent:NO];

Product view

Use the trackProductViewedWithSKU method to track views of a particular product on your app. It can take common attributes like SKU and category_id. In addition, you can use the NSDictionary data type for additional parameters that your app should pass to the SDK.

Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackProductViewed(withSKU: "Product SKU", andCategoryID: CategoryID, canBatchThisEvent: false)

// Send event with additional params
BlueShift.sharedInstance()?.trackProductViewed(withSKU: "Product SKU", andCategoryID:1234 , withParameter: paramsDictionary, canBatchThisEvent: false)

// Send event without additional params
[[BlueShift sharedInstance] trackProductViewedWithSKU:@"Product SKU" andCategoryID:@"Category ID" canBatchThisEvent:NO];

// Send event with additional params
[[BlueShift sharedInstance] trackProductViewedWithSKU:@"Product SKU" andCategoryID:1234 withParameter:parametersDictionary canBatchThisEvent:NO];

Add to cart

Use the trackAddToCartWithSKU method to track the add_to_cart event. The app can call this event when either a user clicks the add_to_cart button, or when the add_to_cart API is called.

Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackAddToCart(withSKU: "Product SKU", andQuantity: 5, canBatchThisEvent: false)

// Send event with additional params
BlueShift.sharedInstance()?.trackAddToCart(withSKU: "Product SKU", andQuantity: 5, andParameters: paramsDictionary, canBatchThisEvent: false)

// Send event without additional params
[[BlueShift sharedInstance] trackAddToCartWithSKU:@"Product SKU" andQuantity:5 canBatchThisEvent:NO];

// Send event with additional params
[[BlueShift sharedInstance] trackAddToCartWithSKU:@"Product SKU" andQuantity:5 andParameters:parametersDictionary canBatchThisEvent:NO];

Cart checkout

Use the trackCheckOutCartWithProducts method to track a check out of a cart. The first argument to the method is the array of products in the cart, and this model is included in the SDK. You can create an instance and set the values in it using your product instance.

Here's how to use it:

let product1 = BlueShiftProduct()
product1.sku = "PRM123"
product1.price = 50
product1.quantity = 2

let product2 = BlueShiftProduct()
product2.sku = "PRM123"
product2.price = 50
product2.quantity = 2

let product3 = BlueShiftProduct()
product3.sku = "PRM123"
product3.price = 50
product3.quantity = 2

let products = [product1, product2, product3]

// Send event without additional params
BlueShift.sharedInstance()?.trackCheckOutCart(withProducts: products, andRevenue: revenue, andDiscount: discount, andCoupon: coupon, canBatchThisEvent: false)

// Send event with additional params
BlueShift.sharedInstance()?.trackCheckOutCart(withProducts: products, andRevenue: revenue, andDiscount: discount, andCoupon: coupon, andParameters: paramsDictionary, canBatchThisEvent: false)

BlueShiftProduct *product1 = [[BlueShiftProduct alloc] init];
[product1 setSku:@"PROM001"];
[product1 setPrice:100];
[product1 setQuantity:1];

BlueShiftProduct *product2 = [[BlueShiftProduct alloc] init];
[product2 setSku:@"SERSGQ002"];
[product2 setPrice:10];
[product2 setQuantity:2];

BlueShiftProduct *product3 = [[BlueShiftProduct alloc] init];
[product3 setSku:@"FERW006"];
[product3 setPrice:105];
[product3 setQuantity:1];

products = @[product1, product2, product3];

// Send event without additional params
[[BlueShift sharedInstance] trackCheckOutCartWithProducts:products andRevenue:revenue andDiscount:discount andCoupon:coupon canBatchThisEvent:NO];

// Send event with additional params
BlueShift.sharedInstance().trackCheckOutCart(withProducts: products, andRevenue: revenue, andDiscount: discount, andCoupon: coupon, andParameters: paramsDictionary, canBatchThisEvent: false)

Purchase

Use the trackProductsPurchased method to track a user's purchase of the products on your app.

Here's how to use it:

let product1 = BlueShiftProduct()
product1.sku = "PRM123"
product1.price = 50
product1.quantity = 2

let product2 = BlueShiftProduct()
product2.sku = "PRM123"
product2.price = 50
product2.quantity = 2

let product3 = BlueShiftProduct()
product3.sku = "PRM123"
product3.price = 50
product3.quantity = 2

let products = [product1, product2, product3]

// Send event without additional params
BlueShift.sharedInstance()?.trackProductsPurchased(products, withOrderID: orderID, andRevenue: revenue, andShippingCost: shippingCost, andDiscount: discount, andCoupon: coupon, canBatchThisEvent: false)

// Send event with additional params
BlueShift.sharedInstance()?.trackProductsPurchased(products, withOrderID: orderID, andRevenue: revenue, andShippingCost: shippingCost, andDiscount: discount, andCoupon: coupon, andParameters: paramsDictionary, canBatchThisEvent: false)

BlueShiftProduct *product1 = [[BlueShiftProduct alloc] init];
[product1 setSku:@"PROM001"];
[product1 setPrice:100];
[product1 setQuantity:1];

BlueShiftProduct *product2 = [[BlueShiftProduct alloc] init];
[product2 setSku:@"SERSGQ002"];
[product2 setPrice:10];
[product2 setQuantity:2];

BlueShiftProduct *product3 = [[BlueShiftProduct alloc] init];
[product3 setSku:@"FERW006"];
[product3 setPrice:105];
[product3 setQuantity:1];

products = @[product1, product2, product3];

// Send event without additional params
[[BlueShift sharedInstance] trackProductsPurchased:products withOrderID:orderID andRevenue:revenue andShippingCost:shippingCost andDiscount:discount andCoupon:coupon canBatchThisEvent:NO];

// Send event with additional params
[[BlueShift sharedInstance] trackProductsPurchased:products withOrderID:orderID andRevenue:revenue andShippingCost:shippingCost andDiscount:discount andCoupon:coupon andParameters:parameters canBatchThisEvent:NO];

Cancelled purchase

Use the trackPurchaseCancelForOrderID to track a purchase cancelled after an order is completed.
Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackPurchaseCancel(forOrderID: orderID, canBatchThisEvent: false)

// Send event with additional params
BlueShift.sharedInstance()?.trackPurchaseCancel(forOrderID: orderID, andParameters: paramsDictionary, canBatchThisEvent: false)

// Send event without additional params
[[BlueShift sharedInstance] trackPurchaseCancelForOrderID:orderID canBatchThisEvent:NO];

// Send event with additional params
[[BlueShift sharedInstance] trackPurchaseCancelForOrderID:orderID andParameters:parameters canBatchThisEvent:NO];

Return a purchase

Use the trackPurchaseReturnForOrderID method to track a return of a purchase. You can call this method when the purchase return API is called.

Here's how to use it:

let product1 = BlueShiftProduct()
product1.sku = "PRM123"
product1.price = 50
product1.quantity = 2

let product2 = BlueShiftProduct()
product2.sku = "PRM123"
product2.price = 50
product2.quantity = 2

let product3 = BlueShiftProduct()
product3.sku = "PRM123"
product3.price = 50
product3.quantity = 2

let products = [product1, product2, product3]

// Send event without additional params
BlueShift.sharedInstance()?.trackPurchaseReturn(forOrderID: orderID, andProducts: dictionary, canBatchThisEvent: false)

// Send event with additional params
BlueShift.sharedInstance()?.trackPurchaseReturn(forOrderID: orderID, andProducts: products, andParameters: paramsDictionary, canBatchThisEvent: false)

BlueShiftProduct *product1 = [[BlueShiftProduct alloc] init];
[product1 setSku:@"PROM001"];
[product1 setPrice:100];
[product1 setQuantity:1];

BlueShiftProduct *product2 = [[BlueShiftProduct alloc] init];
[product2 setSku:@"SERSGQ002"];
[product2 setPrice:10];
[product2 setQuantity:2];

BlueShiftProduct *product3 = [[BlueShiftProduct alloc] init];
[product3 setSku:@"FERW006"];
[product3 setPrice:105];
[product3 setQuantity:1];

products = @[product1, product2, product3];

// Send event without additional params
[[BlueShift sharedInstance] trackPurchaseReturnForOrderID:orderID andProducts:products canBatchThisEvent:NO];

// Send event with additional params
[[BlueShift sharedInstance] trackPurchaseReturnForOrderID:orderID andProducts:products andParameters:parameters canBatchThisEvent:NO];

Product search

Use the trackProductSearchWithSkuArray method to track the events when a user searches for a product in your app. You can implement this method with optional filters and extra arguments.

Here's how to use it:

//without optional filters and extra arguments
BlueShift.sharedInstance()?.trackProductSearch(withSkuArray: [Any]!, andNumberOfResults: Int, andPageNumber: Int, andQuery: String!, andParameters: [AnyHashable : Any]!, canBatchThisEvent: Bool)

//with optional filters
BlueShift.sharedInstance()?.trackProductSearch(withSkuArray: [Any]!, andNumberOfResults: Int, andPageNumber: Int, andQuery: String!, andFilters: [AnyHashable : Any]!, canBatchThisEvent: Bool)

//with extra arguments
BlueShift.sharedInstance()?.trackProductSearch(withSkuArray: [Any]!, andNumberOfResults: Int, andPageNumber: Int, andQuery: String!, andFilters: [AnyHashable : Any]!, andParameters: [AnyHashable : Any]!, canBatchThisEvent: Bool)

//without optional filters and extra arguments
[[BlueShift sharedInstance] trackProductSearchWithSkuArray:(NSArray *)skuArray andNumberOfResults:(NSInteger)numberOfResults andPageNumber:(NSInteger)pageNumber andQuery:(NSString *)query andParameters:(NSDictionary *)parameters canBatchThisEvent:(BOOL)isBatchEvent];

//with optional filters
[[BlueShift sharedInstance] trackProductSearchWithSkuArray:(NSArray *)skuArray andNumberOfResults:(NSInteger)numberOfResults andPageNumber:(NSInteger)pageNumber andQuery:(NSString *)query andFilters:(NSDictionary *)filters canBatchThisEvent:(BOOL)isBatchEvent];

//with extra arguments
[[BlueShift sharedInstance] trackProductSearchWithSkuArray:(NSArray *)skuArray andNumberOfResults:(NSInteger)numberOfResults andPageNumber:(NSInteger)pageNumber andQuery:(NSString *)query andFilters:(NSDictionary *)filters andParameters:(NSDictionary *)parameters canBatchThisEvent:(BOOL)isBatchEvent];

Subscribe to emails

Use the trackEmailListSubscriptionForEmail method to track if the user has subscribed to emails.

Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackEmailListSubscription(forEmail: "Email Id", canBatchThisEvent: false)

// Send event with additional params
BlueShift.sharedInstance()?.trackEmailListSubscription(forEmail: "Email Id", andParameters: paramsDictionary, canBatchThisEvent: false)

// Send event without additional params
[[BlueShift sharedInstance] trackEmailListSubscriptionForEmail:@"Email Id" canBatchThisEvent:NO];

// Send event with additional params
[[BlueShift sharedInstance] trackEmailListSubscriptionForEmail:@"Email Id" andParameters:paramsDictionary canBatchThisEvent:NO];

Unsubscribe from emails

Use the trackEmailListUnsubscriptionForEmail if a user unsubscribes from emails.
Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackEmailListUnsubscription(forEmail: "Email Id", canBatchThisEvent: false)

// Send event with additional params
BlueShift.sharedInstance()?.trackEmailListUnsubscription(forEmail: "Email Id", andParameters: paramsDictionary, canBatchThisEvent: NO)

// Send event without additional params
[[BlueShift sharedInstance] trackEmailListUnsubscriptionForEmail:@"Email Id" canBatchThisEvent:NO]

// Send event with additional params
[[BlueShift sharedInstance] trackEmailListUnsubscriptionForEmail:@"Email Id" andParameters:paramsDictionary canBatchThisEvent:NO]

Initialize a subscription

Use the trackSubscriptionInitializationForSubscriptionState method to track if a user starts a subscription in your app.

Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackSubscriptionInitialization(for: BlueShiftSubscriptionState, andCycleType: String!, andCycleLength: Int, andSubscriptionType: String!, andPrice: Float, andStartDate: TimeInterval, canBatchThisEvent: Bool)

// Send event with additional params
BlueShift.sharedInstance()?.trackSubscriptionInitialization(for: BlueShiftSubscriptionState, andCycleType: String!, andCycleLength: Int, andSubscriptionType: String!, andPrice: Float, andStartDate: TimeInterval, andParameters: [AnyHashable : Any]!, canBatchThisEvent: Bool)

// Send event without additional params
[[BlueShift sharedInstance] trackSubscriptionInitializationForSubscriptionState:(BlueShiftSubscriptionState)subscriptionState andCycleType:(NSString *)cycleType andCycleLength:(NSInteger)cycleLength andSubscriptionType:(NSString *)subscriptionType andPrice:(float)price andStartDate:(NSTimeInterval)startDate canBatchThisEvent:(BOOL)isBatchEvent];

// Send event with additional params
[[BlueShift sharedInstance] trackSubscriptionInitializationForSubscriptionState:(BlueShiftSubscriptionState)subscriptionState andCycleType:(NSString *)cycleType andCycleLength:(NSInteger)cycleLength andSubscriptionType:(NSString *)subscriptionType andPrice:(float)price andStartDate:(NSTimeInterval)startDate andParameters:(NSDictionary *)parameters canBatchThisEvent:(BOOL)isBatchEvent];

Pause a subscription

Use the trackSubscriptionPause method to track if a user has paused a subscription.
Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackSubscriptionPause(withBatchThisEvent: Bool)

// Send event with additional params
BlueShift.sharedInstance()?.trackSubscriptionPause(withParameters: [AnyHashable : Any]!, canBatchThisEvent: Bool)

// Send event without additional params
[[BlueShift sharedInstance] trackSubscriptionPauseWithBatchThisEvent:(BOOL)isBatchEvent];

// Send event with additional params
[[BlueShift sharedInstance] trackSubscriptionPauseWithParameters:(NSDictionary *)parameters canBatchThisEvent:(BOOL)isBatchEvent];

Resume/un-pause a subscription

Use the trackSubscriptionUnpause method to track if a user resumes a paused subscription.

Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackSubscriptionUnpause(withBatchThisEvent: Bool)

// Send event with additional params
BlueShift.sharedInstance()?.trackSubscriptionUnpause(withParameters: [AnyHashable : Any]!, canBatchThisEvent: Bool)

// Send event without additional params
[[BlueShift sharedInstance] trackSubscriptionUnpauseWithBatchThisEvent:(BOOL)isBatchEvent];

// Send event with additional params
[[BlueShift sharedInstance] trackSubscriptionUnpauseWithParameters:(NSDictionary *)parameters canBatchThisEvent:(BOOL)isBatchEvent];

Cancel a subscription

Use the trackSubscriptionCancel method to track if a user cancels a currently running subscription.

Here's how to use it:

// Send event without additional params
BlueShift.sharedInstance()?.trackSubscriptionCancel(withBatchThisEvent: Bool)

// Send event with additional params
BlueShift.sharedInstance()?.trackSubscriptionCancel(withParamters: [AnyHashable : Any]!, canBatchThisEvent: Bool)

// Send event without additional params
[[BlueShift sharedInstance] trackSubscriptionCancelWithBatchThisEvent:(BOOL)isBatchEvent];

// Send event with additional params
[[BlueShift sharedInstance] trackSubscriptionCancelWithParamters:(NSDictionary *)parameters canBatchThisEvent:(BOOL)isBatchEvent];

Events that the SDK tracks out-of-the-box

In addition, the SDK tracks below events automatically.

App open

The SDK calls the app_open event every time when user taps on a push notification to launch the app or the user launches the app from the closed state.

From SDK v2.1.13, the automatic app_open event when the app is launched from the killed state is disabled by default and also throttled by the SDK based on the automaticAppOpenTimeInterval.

You can enable the automatic app_open events when the app is launched from the killed state by setting enableAppOpenTrackEvent to true during the SDK initialization.

config.enableAppOpenTrackEvent = true

[config setEnableAppOpenTrackEvent:YES];

The default automaticAppOpenTimeInterval is set to 24 hours, so SDK will fire only one app_open event in 24 hours. This default behavior can be changed by setting the custom automaticAppOpenTimeInterval during SDK initialization.

// set time interval in seconds
config.automaticAppOpenTimeInterval = 300

// set time interval in seconds
[config setAutomaticAppOpenTimeInterval:300];

In case you want to fire app open manually from the app, here is how you can do it.

//You can pass the app open details as dictionary or pass it as nil
BlueShift.sharedInstance()?.appDelegate.trackAppOpen(withParameters: details)

//You can pass the app open details as dictionary or pass it as nil
[[[BlueShift sharedInstance]appDelegate] trackAppOpenWithParameters:details];

App install & App update

From SDK v2.5.0 onwards, SDK will automatically track the app installs and app updates using events app_install and app_update.

App Install

When you launch your app for the very first time after installation, the Blueshift SDK recognizes this as a new app install and automatically fires an app_install event to Blueshift.

App Update

The Blueshift SDK keeps track of your app's version. When you open the app after a successful update, the SDK detects the change in version and fires an app_update event to Blueshift. Additionally, the SDK includes the previous app version as part of this event data, labeled as previous_app_version.

FAQs

What happens if my app is updated from a version that didn't have the Blueshift SDK integrated?
- Since no previous version information is stored, the SDK won't be able to detect the version change. In this scenario, the event will be treated as an app install and an app_install event will be fired.
What happens if my app is updated from a version with an older version of the Blueshift SDK?
- The Blueshift SDK will search for traces of the older version, such as configuration files. If these remnants are found, the SDK will recognize this as an app update and fire an app_update event.

Notifications

The Blueshift SDK automatically tracks the Push notification click event and In-app notification delivered, open and click events and sends them to Blueshift. The app developer does not need to add any code separately to track the push notification clicks.

Track events on your app

📘
Wait. Are you ready for this part?

Events that you can track on your iOS app using the methods in the SDK

Custom events

Identify a user

Screen view

Product view

Add to cart

Cart checkout

Purchase

Cancelled purchase

Return a purchase

Product search

Subscribe to emails

Unsubscribe from emails

Initialize a subscription

Pause a subscription

Resume/un-pause a subscription

Cancel a subscription

Events that the SDK tracks out-of-the-box

App open

App install & App update

Notifications

📘Wait. Are you ready for this part?

Events that you can track on your iOS app using the methods in the SDK

Custom events

Identify a user

Screen view

Product view

Add to cart

Cart checkout

Purchase

Cancelled purchase

Return a purchase

Product search

Subscribe to emails

Unsubscribe from emails

Initialize a subscription

Pause a subscription

Resume/un-pause a subscription

Cancel a subscription

Events that the SDK tracks out-of-the-box

App open

App install & App update

Notifications

📘
Wait. Are you ready for this part?