Android Behavior Data Collection Methods

In this topic:

• Android Behavior Data Collection Methods
• Introduction
• Field Validations
• App Lifecycle Events
• Advertisement events
• Ad-click event
• Ad-impression event
• Content events
• Screen view event
• Button tap event
• Content view event
• Drag and drop event
• Media event
• Search event
• Ecommerce events
• Conversion event
• Product event
• Cart event
• Custom events
• Capture any event
• Collecting and transferring behavior data in real-time

Introduction

The Core module collects a set of parameters from the device and mobile application by default. The default parameters collected by the core module are listed here.

These default parameters are transmitted along with each of the behaviour events captured by the Infinity module. The Infinity module captures the behavior data with the help of convenience methods. Convenience methods in the Infinity module are helper functions that help to capture behavior data with minimal coding. As part of the convenience methods, the Infinity module has a Custom Event convenience method that can help to capture behavior data from any event triggered by the user.

Each of the convenience methods require the below parameters to be passed.

• eventMeta: This is an object that stores the parameters attached to an event.
  • eventPath: This parameter is used to specify the path in the application in which the event occurs.
  • eventDesc: This parameter is used to specify the name of the screen on which the event occurs.
  • eventType: This parameter is used to specify the type of event that occurs, such as a View or a Click.
• customData (optional): This is an object used to store a set of custom key-value pairs to pass additional data that is typically not included in the method, but relevant to the event.

The methods from the convenience methods are mapped parameters in the Infinity library. The complete list of parameters in the Infinity library are 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 string data type are as follows:

Note: The total length of a custom event method cannot 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 Lifecycle events here.

Advertisement events

Ad-click event

This method is used to collect behavior data when a mobile app user clicks on an advertisement within the mobile application.

Method:

triggerAdClick()

Syntax:

Map<String, String> triggerAdClick( @Nullable final String adName,
				@Nullable final Map<String, String> customParams);
		

Example:

triggerAdClick sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");
				ORADataCollector.getInstance(). triggerAdClick("Ad Name", customData);
		

Event specific parameter for this method:

• adName: This parameter is used to specify the name of the advertisement the user interacted with on the mobile application.

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

Ad-impression event

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

Method:

triggerAdImpression()

Syntax:

public Map<String, String> triggerAdImpression( @Nullable final String[] adNames,
				@Nullable final Map<String, String> customParams)
		

Example:

triggerAdImpression sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");
				String[] adNames = { "First Ad Name", "Second Ad Name", "Third Ad Name" };
				ORADataCollector.getInstance().triggerAdImpression(adNames, customData);
		

Event specific parameter for this method:

• adNames: An array of Strings containing a list of ad names shown to the user

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

Content events

Screen view event

This method is used to collect data when the mobile application user views a the contents of a screen, such as article or image.

Method:

triggerScreenView()

Syntax:

Map<String, String> triggerScreenView(  @Nullable final String screenName,
				@Nullable final String screenId,
				@Nullable final Map<String, String> customParams);
		

Example:

triggerScreenView sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customParams = new HashMap<String, String>();
				customParams.put("custom_key", "custom_value");
				ORADataCollector.getInstance().triggerScreenView("HelloWorld Screen View", "/HelloWorld/screen/view", customParams);
		

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

Button tap event

This method is used to collect data when an mobile application user taps on a button on the mobile app.

Method:

triggerButtonClick()

Syntax:

Map<String, String> triggerButtonClick( @Nullable final String buttonName,
				@Nullable final String buttonId,
				@Nullable final Map<String, String> customParams);
		

Example:

triggerButtonClick sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map customParams = new HashMap();
				customParams.put("custom_key", "custom_value");
				ORADataCollector.getInstance().triggerButtonClick("HelloWorld Button Tap Event", "/HelloWorld/button/click/event", customParams);
		

Event specific parameter for this method:

• none

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

Content view event

This method collects data when the user views content on the screen.

Method:

triggerContentView()

Syntax:

Map<String, String> triggerContentView( @Nullable final String contentName,
				@Nullable final String contentId,
				@Nullable final Map<String, String> customParams)
		

Example:

triggerContentView sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customParams = new HashMap<String, String>();
				customParams.put("custom_key", "custom_value");
				ORADataCollector.getInstance(). triggerContentViewEvent("Foot wear", "foot_wear_id", customParams);
		

Event specific parameter for this method:

• none

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

Drag and drop event

This method is used to capture drag and drop events in a screen.

Method:

triggerDragAndDropEvent()

Syntax:

public Map<String, String> triggerDragAndDropEvent(final ORAEventMeta eventMeta);
		

Example:

triggerDragAndDropEvent sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");
				final ORAEventMeta eventMeta = new ORAEventMeta("application/drag_and_drop", "Drag And Drop desc", customData);
				ORADataCollector.getInstance().triggerDragAndDropEvent(eventMeta);
		

Event specific parameter for this method:

• none

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

Media event

This method collects data when a when a media event, such as a user viewing or playing or loading a video occurs.

Method:

triggerMediaEvent()

Syntax:

public Map<String, String> triggerMediaEvent( @Nullable final String mediaName,
				@Nullable final String mediaType,
				@Nullable final String mediaEventType,
				@Nullable final Map<String, String> customParams)
		

Example:

triggerMediaEvent sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");
				ORADataCollector.getInstance().triggerMediaEvent("Media Name", "Media Type", "Media Event Type", customData);
		

Event specific parameter for this method:

• mediaName: Specifies the name of the media content the user accessed during an event, such as name of a video viewed by the user etc.
• mediaType: Specifies a extension of the media file accessed by the user during the event, such as mp4 or QuickTime or mp3 etc.
• mediaEventType: Specifies a type of media event that occurred, such as a load of media content, or viewing media content etc.

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

Search event

This method collects data when an mobile application user searches within the application. It is useful to capture the search term and the result.

Method:

triggerSearch()

Syntax:

Map<String, String> triggerSearch(@Nullable final String searchPhrase,
				final int searchResult,
				@Nullable final Map<String, String> customParams);
		

Example:

triggerSearch sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");
				ORADataCollector.getInstance().triggerSearch("glasses", "3", customData);
		

Event specific parameter for this method:

• searchPhrase: Specifies the phrase searched by the user
• searchResult: Specifies the results of search query

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

Ecommerce events

Conversion event

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

Method:

triggerConversion()

Syntax:

public Map<String, String> triggerConversion( @Nullable final String conversionName, 
				@Nullable final Map<String, String> customParams);
		

Example:

triggerConversion sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");
				ORADataCollector.getInstance().triggerConversionEvent("HelloWorld Conversion Event", customData);
		

Event specific parameter for this method:

• conversionName: Specifies the value used to identify the type of conversion i.e. registration, purchase etc.

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

Product event

This method is used to collect behavior data when a product is viewed.

Method:

triggerProductEvent()

Syntax:

public Map<String, String> triggerProductEvent(final ORAEventMeta eventMeta, final ORAProductMeta productMeta, final String contentGroup);
		

Example:

triggerProductEvent sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");
				final ORAEventMeta eventMeta = new ORAEventMeta("/HelloWorld/product/view", "HelloWorld Product View", "view", customData);
				final String[] productSubTotals = {"45.00", "8.25"};
				final String[] productUnits = {"5", "4"};
				final String[] productIds = {"productId1, productId2"};
				final String[] productSkus = {"productSku1", "productSku2"};
				final String[] productName = {"product 1", "product 2"};
				final String[] productCategory = {"Category 1", "Category 2"};
				final String[] productBrand = {"Brand 1", "Brand 2"};


				final ORAProductMeta productMeta = new ORAProductMeta("a", productSubTotals,
				productUnits, productIds, productSubTotals, productName, productCategory, productBrand)
				ORADataCollector.getInstance().triggerProductEvent(eventMeta, productMeta, "Content Group");
		

Event specific parameter for this method:

• 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 (provide "a", "v", "r").
  • productIds(optional): Specifies a product identifier.
  • productSkus: Specifies a unique product stock-keeping unit (SKU) number.
  • productUnits: Specifies the quantity of products associated with the event.
  • productSubtotals: Specifies a 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 behavior data
  • productName: Specifies the name of products associated with the event.
  • productCategory: Specifies the category of products associated with the event.
  • productBrand: Specifies the brand of products associated with the event.

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

Method:

triggerProductEvent()

Syntax:

Map<String, String> triggerProductEvent(final ORAProduct product,
				@Nullable final Map<String, String> customParams);
		

Example:

triggerProductEvent sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");
				ORAProduct product = new ORAProduct("v", "p_id_1",
				"sku_id_1","name_1","category_1",
				"brand_1", 1, 100);
				ORADataCollector.getInstance().triggerProductEvent(product, customData);
		

Event specific parameter for this method:

• Product: Specifies an ORAProduct object that stores product specific parameters associated with this event.
  • type: Specifies a type of the product event that occurred, such as v = product view, a = product add, r = product remove.
  • id(optional): Specifies a product identifier.
  • sku: Specifies a unique product stock-keeping unit (SKU) number.
  • units: Specifies the quantity of products associated with the event.
  • subTotal: Specifies a 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 behavior data
  • name: Specifies the name of products associated with the event.
  • category: Specifies the category of products associated with the event.
  • brand: Specifies the brand of products associated with the event.

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

Cart event

This method is used to collect behavior data when a cart related event such as adding products to a cart, modifying contents of a cart etc. occurs.

Method:

triggerCartEvent()

Syntax:

public Map<String, String> triggerCartEvent(@NonNull List<ORAProduct> oraProducts,
				@Nullable String invoiceNumber,
				@Nullable Map<String, String> customParams)
		

Example:

triggerCartEvent sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customData = new HashMap<String, String>();
				customData.put("custom_key", "custom_value");

				ORAProduct productA = new ORAProduct("a", "I_A", "SKU_A", "PROD_A", "CAT_A", "BRAND_A", 3, 1);
				ORAProduct productB = new ORAProduct("a", "I_B", "SKU_B", "PROD_B", "CAT_B", "BRAND_B", 5, 2);

				List<ORAProduct> productList = new ArrayList<>();
				productList.add(productA);
				productList.add(productB);
       
				ORADataCollector.getInstance().triggerCartEvent(productList, "45", customData);
		

Event specific parameter for this method:

• Product: Specifies an ORAProduct object that stores product specific parameters associated with this event.
  • type: Specifies a type of the product event that occurred, such as v = product view, a = product add, r = product remove.
  • id(optional): Specifies a product identifier.
  • sku: Specifies a unique product stock-keeping unit (SKU) number.
  • units: Specifies the quantity of products associated with the event.
  • subTotal: Specifies a 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 behavior data
  • name: Specifies the name of products associated with the event.
  • category: Specifies the category of products associated with the event.
  • brand: Specifies the brand of products associated with the event.

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

Custom events

Capture any event

This method is used to collect data when an event of interest occurs and is not supported by any of the available convenience methods.

Method:

triggerEvent()

Syntax:

Map<String, String> triggerEvent( @NonNull final String eventName,
				@Nullable final Map<String, String> customParams);
		

Example:

triggerEvent sample code

// Send custom key/value pairs as arguments to event methods (optional)
				Map <String, String> customParams = new HashMap<String, String>();
				customParams.put("custom_key", "custom_value");
				ORADataCollector.getInstance().triggerEvent("hello world event", customParams);
		

Event specific parameter for this method:

• None

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

Collecting and transferring behavior data in real-time

The aforementioned variants of the trigger event methods enable the creation and queueing 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 an asynchronous process.

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 the internet, you can use the ORABaseConfigSettings.IMMEDIATE_EVENT_STORING_ENABLED parameter to temporarily persist the event data into the local database and push it to the server when connectivity is available.

Syntax:

public Map<String, String> triggerEventImmediately(final ORAEventMap eventMap)
		

Example:

triggerEventImmediately sample code

// Send custom key/value pairs as arguments to event methods (optional)
				final ORAEventMap eventMap = new ORAEventMap(dcsuri, oraTi, oraPi, oraSys, oraDl, null);
				ORADataCollector.getInstance().triggerEventImmediately(eventMap);
		

Event specific parameter for this method:

• None

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