Behavior Data Collection Methods - iOS

In this topic:

• Behavior Data Collection Methods - iOS
• Introduction
• Field validations
• App Lifecycle Events
• The Data Collector Object
• Assign the ORADataCollector singleton to a variable
• Advertisement events
• Ad-click event
• Ad-impression event
• Content events
• Screen view event with name, ID and customParams
• Button tap event with name, ID and CustomParams
• Content view with name, ID and CustomParams
• Drag and drop events
• Media event
• Search events
• E-Commerce events
• Conversion event
• Product event - for multiple products
• Product event - for a single product
• Cart event
• Custom events with eventName and customParams
• Pausing and resuming events
• Pausing events
• Resuming events
• Collecting and transferring behavior data in real-time

Introduction

The Core module captures a set of default parameters from your device and mobile application. These default parameters are transmitted along with each event captured by the Infinity module. The list of default parameters are available at Default parameters captured by Core Module.

The Infinity module captures the behavior data with the help of convenience methods. Convenience methods are methods that can be used with minimal or no coding. The Infinity module also has a Custom Event convenience method that can help to capture behavior data from any event triggered by the mobile application.

Each of the convenience methods requires an eventMeta object to be passed as a mandatory argument for the method. The eventMeta object can be combined with additional arguments and passed in the convenience method. The arguments from the convenience methods are mapped parameters in the Infinity Library. The complete list of parameters in the Infinity library is available here.

The eventMeta object has the following properties:

For details of the complete list of Oracle Infinity Parameters, their descriptions and their values, click here.

Field validations

The allowable characters for the values of arguments in the event capture methods include the following:

• Alphanumeric characters (letters, numbers)
• Special characters (punctuation marks, mathematical and other conventional symbols).

The Character limits for arguments of the string data type are as follows:

Note: The total length of a custom event method can not exceed 4096 characters

App Lifecycle Events

The Infinity module captures the App Lifecycle events by default based on the configuration set in the Core module. You can read more about capturing the App life cycle events.

The Data Collector Object

The primary interface for using the Core module is the ORADataCollector class. ORADataCollector provides a singleton object that may be used throughout your project. To instantiate the singleton object, call the [ORADataCollector sharedCollector] method. This method returns a pointer to the singleton. This instance may be assigned to a variable name or used inline.

Assign the ORADataCollector singleton to a variable

Objective C

ORADataCollector *collector = [ORADataCollector sharedCollector];
		

Swift 5.1

let collector = ORADataCollector.shared()
		

Alternatively, the singleton may be referenced inline using the [ORADataCollector sharedCollector] method

Advertisement events

Ad-click event

The triggerAdClick:customParam: method is used to trigger an event when a user taps an advertisement within the mobile app.

Objective C

NSArray *adName = @"Ad Name 1";
				NSDictionary *customParams = @{@"myCustomParam":@"myCustomValue"};
				[collector triggerAdClick:adName customParam:customParams];
		

Swift 5.1

let adName = "Ad Name 1"
				let customParams = ["myCustomParam":"myCustomValue"]
				collector!.triggerAdClick(adName, customParams: customParams)
		

• adName: This argument is used to specify the name of the advertisement the user interacted with on the mobile application.
• customParams (optional): Specifies dictionary of additional custom params.

Ad-impression event

The triggerAdImpression:customParam: method collects data when a mobile application user views one or more advertisements within the mobile application. This method has the provision to capture events pertaining to viewing multiple advertisements within a single screen view as well.

Objective C

NSArray *adNames = @[@"Ad Name 1", @"Ad Name 2", @"Ad Name 3"];
				NSDictionary *customParams = @{@"myCustomParam":@"myCustomValue"};
				[collector triggerAdImpression:adNames customParam:customParams];
		

Swift 5.1

let adNames = ["Ad Name 1", "Ad Name 2", "Ad Name 3"]
				let customParams = ["myCustomParam":"myCustomValue"]
				collector!.triggerAdImpression(adNames, customParam: customParams)
		

• adNames (optional): This argument is used to pass a set of advertisement names displayed on the mobile app screen, as an array of Strings []
• customParams (optional): Specifies dictionary of additional custom params.

The Infinity parameters and their values specific to this event are as follows:

Content events

Screen view event with name, ID and customParams

The triggerScreenViewWithName:screenId:customParams: method is used to collect data when the mobile app loads a screen or navigates to a screen with additional data like screen name, screen ID and customParams.

Objective C

NSDictionary *customParams = @{@"myCustomParam":@"myCustomValue"};
				[collector triggerScreenViewWithName:@"CheckoutViewController" screenId:@"Checkout" customParams:customParams];
		

Swift 5.1

let customParams = ["myCustomParam":"myCustomValue"]
				collector!.triggerScreenView(withName: "CheckoutView", screenId: "Checkout", customParams: customParams)
		

• screenName (optional): Specifies the name of the Screen view.
• screenId (optional): Specifies the id of the Screen view.
• customParams (optional): Specifies dictionary of additional custom params.

The Infinity parameters and their values specific to this event are as follows:

Button tap event with name, ID and CustomParams

The triggerButtonClickWithName:buttonId:customParams: method is used to trigger an event when a user taps a button within the application with additional data like button name, button ID and customParams.

Objective C

NSDictionary *customParams = @{@"myCustomParam":@"myCustomValue"};
				[collector triggerButtonClickWithName:@"Button Name" buttonId:@"Button Id" customParams:customParams];
		

Swift 5.1

let customParams = ["myCustomParam":"myCustomValue"]
				collector!.triggerButtonClick(withName: "buttonname", buttonId: "buttonId", customParams: customParams) 
		

Below are the arguments to be passed to this method

• buttonName : (optional) Specifies the name of the Button tap.
• buttonId : (optional) Specifies the id of the Button tap.
• customParams (optional): Specifies dictionary of additional custom params.

The Infinity parameters and their values specific to this event are as follows:

Content view with name, ID and CustomParams

The triggerContentViewWithName:contentId:customParams method collects data when the user views content on the screen such as text, image, and so on. with additional data like content name, Id and customParams.

Objective C

NSDictionary *customParams = @{@"myCustomParam":@"myCustomValue"};
				[collector triggerContentViewWithName:@"ContentViewEventName" contentId:@"ContentViewEventId" customParams:customParams];
		

Swift 5.1

let customParams = ["myCustomParam":"myCustomValue"]
				collector!.triggerContentView(withName: "ContentViewEventName", contentId: "ContentViewEventId", customParams: customParams)
		

Below are the arguments to be passed to this method

• contentName (optional): Specifies the name of the Content View event.
• contentId (optional): Specifies the id of the Content View event.
• customParams (optional): Specifies dictionary of additional custom params.

The Infinity parameters and their values specific to this event are as follows:

Drag and drop events

The triggerEventForDragAndDrop: method is used to capture drag and drop events in a screen.

Objective C

ORAEventMeta *eventMetaData = [ORAEventMeta eventMetaForPath:@"/application/drag_and_drop"
				description:@"drag and drop event description"
				type:@"drag_and_drop"
				customParams:@{@"myCustomParam":@"myCustomValue"}];
				[collector triggerEventForDragAndDrop:eventMetaData];
		

Swift 5.1

let eventMetaData = ORAEventMeta(eventPath: "/application/drag_and_drop",
				description:"drag and drop event description",
				type:"drag_and_drop",
				customParams:["myCustomParam":"myCustomValue"])
				collector!.triggerEvent(forDragAndDrop: eventMetaData)
		

Additional arguments are required to be passed along with eventMeta object for this event

• None

The Infinity parameters and their values specific to this event are as follows:

Media event

The triggerMediaEvent:mediaType:mediaEventType:customParams method collects data when a media event, such as a user viewing or playing or loading a video occurs

Objective C

NSString *mediaName = @"mediaEventName";
				NSString *mediaType = @"mediaType";
				NSString *mediaEventType = @"mediaEventType";
				[collector triggerMediaEvent:mediaName mediaType:mediaType mediaEventType:mediaEventType customParams:@{@"myCustomParam":@"myCustomValue"}];
		

Swift 5.1

let mediaName = "mediaEventName"
				let mediaType = "mediaType"
				let mediaEventType = "mediaEventType"
				collector!.triggerMediaEvent(forMedia: mediaName, mediaType: mediaType, mediaEventType: mediaEventType, customParams: ["myCustomParam": "myCustomValue"])
		

• mediaName: (optional) Specifies the name of the media content accessed during an event, for example, the name of a video clip.
• mediaType: (optional) Specifies a type of media, accessed during the event, such as QuickTime or mp3.
• mediaEventType: (optional) Specifies a type of media event that occurred, such as a view of media content.
• customParams: (optional) Specifies an Additional params as key value pair.

The Infinity parameters and their values specific to this event are as follows:

Search events

The triggerSearch:searchResult:customParams: method collects data when a mobile application user searches within the application. It is useful to capture the search term and the number of results.

Objective C

[collector triggerSearch:@"shiny boots" searchResult:10 customParams:@{@"key": @"value"}];
		

Swift 5.1

collector.triggerSearch("shiny boots", searchResult:10, customParams: ["key": "value"])					
		

The Infinity parameters and their values specific to this event are as follows:

E-Commerce events

Conversion event

A conversion event is an event that represents a completed activity and is important to your business. Examples of conversion events are purchases, registrations etc.

The triggerConversion:customParams: method is used to collect data when a conversion event occurs

Objective C

NSString *conversionName = @"Purchase: shiny boots";
				NSDictionary *customParams = @{@"myCustomParam":@"myCustomValue"};
				[collector triggerConversion:conversionName customParams:customParams];
		

Swift 5.1

let conversionName = "Purchase: shiny boots"
				let customParams:["myCustomParam":"myCustomValue"])
				collector!.triggerConversion(conversionName, customParams: customParams)
		

• conversionName: (optional) :Specifies the value used to identify the type of conversion i.e. registration, purchase etc.
• customParams (optional) : Specifies dictionary of additional custom params.

The Infinity parameters and their values specific to this event are as follows:

Product event - for multiple products

The triggerEventForProduct:contentGroup:eventMeta: method is used to collect behavior data when multiple products are either viewed, added or removed.

Objective C

ORAEventMeta *eventMetaData = [ORAEventMeta eventMetaForPath:@"/products/footwear"
				description:@"user viewed XP-4011"
				type:@"product view"
				customParams:@{@"myCustomParam":@"myCustomValue"}];
				NSString *contentGroup = @"footwear content group";
				ORAProductMeta *productMeta = [ORAProductMeta eventProductForType:@"v"
				subtotal:@[@"1.00", @"2.00", @"3.00"]
				units:@[@"3",@"5",@"1"]
				productId:@[@"XP-4011",@"XP-4012"]
				productSku:@[@"SKU_A", @"SKU_B", @"SKU_A"]
				productName:@[@"NAME_A, @"NAME_B", @"Name_C"]
				productCategory:@[@"CAT_A, @"CAT_B", @"CAT_C"]
				productBrand:@[@"BRAND_A", @"BRAND_B", @"BRAND_C"]];
				NSString *contentGroup = @"footwear content group";
				[collector triggerEventForProduct:productMeta contentGroup:contentGroup eventMeta:eventMetaData];
		

Swift 5.1

let eventMetaData = ORAEventMeta(eventPath: "/products/footwear",
				description:"user viewed XP-4011",
				type:"product view",
				customParams:["myCustomParam":"myCustomValue"])
				let type = "v"
				let subtotal = ["1.00", "2.00", "3.00"]
				let units = ["3","5","1"]
				let productId = ["XP-4011", "XP-4012"]
				let productSku = ["SKU_A", "SKU_B", "SKU_A"]
				let productName = ["NAME_A", "NAME_B", "NAME_C"]
				let productCategory = ["CAT_A", "CAT_B", "CAT_C"]
				let productBrand = ["BRAND_A", "BRAND_B", "BRAND_C"]
				let productMeta = ORAProductMeta(type:type, subtotal:subtotal, units:units, productSku:productSku, productName:productName, productCategory:productCategory, productBrand:productBrand)
				let contentGroup = @"footwear content group";
				collector!.triggerEvent(forProduct: productMeta, contentGroup:contentGroup, eventMeta:eventMetaData)
		

Additional arguments are required to be passed along with eventMeta object for this event

• contentGroup (optional): Specifies the category to which the content of the screen is related to.
• productMeta: Specifies an ORAProductMeta object that stores product-specific parameters associated with this event.
  • productType: Specifies a product identifier. Acceptable values are "a", "v", "r". "a" -> when product added, "v" -> when product viewed, "r" -> when product removed
  • productIds (optional): Specifies a product identifier.
  • productSkus: Specifies a unique product stock-keeping unit (SKU) number.
  • productUnits: Specifies the quantity of each product associated with the event.
  • productNames(optional): Specifies the name of each product associated with the event.
  • productCategories(optional): Specifies the category of each product associated with the event
  • productBrands(optional): Specifies the brand of each product associated with the event.
  • productSubTotals: Specifies the total cost of each product (product subtotal - units * price).
    • The currency associated with the cost is not available. The currency has to be passed as an optional parameter with the event.

Product event - for a single product

The triggerProductEvent:customParams: method is used to collect behavior data when a single product is either viewed, added or removed.

Objective C

 ORAProduct *product = [ORAProduct eventProductWithType:@"r"
				identifier:@"IDENTIFIER_P"
				sku:@"SKU_P"
				name:@"NAME_P"
				category:@"CATEGORY_P"
				brand:@"BRAND_P"
				subtotal:2.00
				units:4];
				[[ORADataCollector sharedCollector] triggerProductEvent:product 
				customParams:@{@"myCustomParam":@"myCustomValue"}];
		

Swift 5.1

let product = ORAProduct.eventProduct(withType: "r", identifier: "IDENTIFIER_P", sku: "SKU_P", name: "NAME_P", category: "CATEGORY_P", brand: "BRAND_P", subtotal: 2.00, units: 4)
				ORADataCollector.shared()?.triggerProductEvent(product, customParams: ["myCustomParam":"myCustomValue"])
		

Additional arguments are required to be passed along with eventMeta object for this event

• product: Specifies an ORAProduct object that stores product-specific parameters associated with this event.
  • type: Specifies a product identifier. Acceptable values are "a", "v", "r". "a" -> when product added, "v" -> when product viewed, "r" -> when product removed
  • identifier: Specifies a product identifier.
  • sku: Specifies a unique product stock-keeping unit (SKU) number.
  • units: Specifies the quantity of each product associated with the event.
  • name: Specifies the name of each product associated with the event.
  • category: Specifies the category of each product associated with the event.
  • brand: Specifies the brand of each product associated with the event.
  • subTotal: Specifies the total cost of each product (product subtotal - units * price).
    • The currency associated with the cost is not available. The currency has to be passed as an optional parameter with the event.

Cart event

The triggerCartEvent:invoiceNumber:customParams method is used to collect behavior data when a cart-related event such as adding products to the cart, modifying contents of a cart, etc. occurs.

Objective C

NSString * invoiceNumber = @"123456789";
				ORAProduct *product1 = [ORAProduct eventProductWithType:@"p" identifier:@"XP-4011" sku:@"SKU_A" name:@"NAME_A" category:@"CAT_A" brand:@"BRAND_A" subtotal:10 units:1];
				ORAProduct *product2 = [ORAProduct eventProductWithType:@"p" identifier:@"XP-4012" sku:@"SKU_B" name:@"NAME_B" category:@"CAT_B" brand:@"BRAND_B" subtotal:20 units:2];
				ORAProduct *product3 = [ORAProduct eventProductWithType:@"p" identifier:@"XP-4013" sku:@"SKU_C" name:@"NAME_C" category:@"CAT_C" brand:@"BRAND_C" subtotal:30 units:3];
				NSArray *productArray = [[NSArray alloc]initWithObjects:product1,product2,product3, nil];
				[collector triggerCartEvent:productArray invoiceNumber:invoiceNumber customParams:@{@"myCustomParam":@"myCustomValue"}];
		

Swift 5.1

guard let product1 = ORAProduct.eventProduct(withType: "p", identifier: "XP-4011", sku: "SKU_A", name: "NAME_A", category: "CAT_A", brand: "BRAND_A", subtotal: 10, units: 1) else { return }
				guard let product2 = ORAProduct.eventProduct(withType: "p", identifier: "XP-4012", sku: "SKU_B", name: "NAME_B", category: "CAT_B", brand: "BRAND_B", subtotal: 20, units: 2) else { return }
				guard let product3 = ORAProduct.eventProduct(withType: "p", identifier: "XP-4013", sku: "SKU_C", name: "NAME_C", category: "CAT_C", brand: "BRAND_C", subtotal: 30, units: 3) else { return }
				let productArray = [product1, product2, product3]       
				let invoiceNumber = "123456789";
				collector!.triggerCartEvent(productArray, invoiceNumber: invoiceNumber, customParams: ["myCustomParam":"myCustomValue"])
		

Additional arguments are required to be passed along with eventMeta object for this event

• oraProducts: Specifies the array of ORAProduct object to which the product is related to.
  • ORAProduct: Specifies an ORAProductMeta object that stores product-specific parameters associated with this event.
    • type: Specifies a product type (provide "a", "v", "r").
    • identifier (optional): Specifies a product identifier.
    • sku: Specifies a unique product stock-keeping unit (SKU) number.
    • name: Specifies the name of each product associated with the event.
    • category: Specifies the category of each product associated with the event.
    • brand: Specifies the brand of each product associated with the event.
    • subtotal: Specifies the subtotal total of each product associated with the event.
    • units: Specifies the total quantity of each product.
• invoiceNumber: Specifies the invoice number which is related to cart transaction
• customParams (optional) : Specifies dictionary of additional custom params.

The Infinity parameters and their values specific to this event are as follows:

Custom events with eventName and customParams

The triggerEventWithName:customParams: method is used to collect data when an event of interest occurs and is not supported by any of the available convenience methods with eventName and customParams.

Objective C

NSDictionary *customParams = @{@"myCustomParam":@"myCustomValue"};
				[collector triggerEventWithName:@"custom event name" customParams:customParams];
		

Swift 5.1

let customParams = ["myCustomParam":"myCustomValue"]
				collector!.triggerEvent(withName: "custom event name", customParams: customParams)
		

Below are the arguments to be passed to this method

• eventName : Specifies the name of the Custom event.
• customParams (optional) : Specifies dictionary of additional custom params.

The Infinity parameters and their values specific to this event are as follows:

Pausing and resuming events

Pausing events

Objective C

[collector pauseEventTransmission];  // Pauses the collection of events
		

Swift 5.1

collector.pauseEventTransmission()  // Pauses the collection of events
		

Resuming events

Objective C

[collector resumeEventTransmission];  // Resumes the collection of events
		

Swift 5.1

collector.resumeEventTransmission()  // Resumes the collection of events
		

Collecting and transferring behavior data in real-time

The aforementioned variants of the triggerEvent methods enable the creation and queuing of behavior data in the local database. When the time interval specified for data transmission in the configuration is hit, the events are transmitted to the data collection servers. This process is asynchronous.

To serve use cases that require behavior data in real-time, you can use the triggerEventImmediately: method. This method does not store the data in the local database. However, to facilitate behavior data collection on the mobile application when the user is using the mobile app without internet, you can use the ORAConfigImmediateEventStoringEnabled parameter to temporarily persist the event data into the local database and push it to the server when connectivity is available.

Objective C

// Once we've set up our basic information, pass it to the data collector
				NSDictionary *event = @{ORA_DCSURI: EVENT_PATH_BUTTON};
				[[ORADataCollector sharedCollector] triggerEventImmediately:event];
		

Swift 5.1

// Once we've set up our basic information, pass it to the data collector
				let event = [ORA_DCSURI: EVENT_PATH_BUTTON];
				collector!.triggerEventImmediately(event);
		

Learn more

Behavior Data Collection Methods - Android

Oracle CX Infinity Module