Android Behavior Data Collection Methods
In this topic:
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:
Object | Object Property | Mandatory/Optional | Event Parameter | Infinity Parameter(s) Mapping | Description |
---|---|---|---|---|---|
eventMeta | This object stores the parameters attached to an event. | ||||
eventPath (dcsuri) | Mandatory | eventMeta.eventPath | data.page-uri | This parameter specifies the path in the application in which the event occurs. This parameter typically includes the path or screen name. | |
eventDesc | Mandatory | eventMeta.eventDesc | wt.pi, wt.ti | This parameter specifies the name of the screen on which the event occurs. This parameter typically includes the event name or screen name or a title that identifies the screen. | |
eventType | Mandatory | eventMeta.eventType | wt.ev | This parameter specifies the type of event that occurs, such as a View, Click and so on | |
customData | Optional | eventMeta.customData | eventMeta.customData |
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:
Argument Accepting String Values | Length |
---|---|
Values passed for content descriptions, path, content group names, or any custom data | 512 |
Custom Data Name | 64 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | data.page-uri | /ad/click |
2 | wt.ev | adclick |
3 | wt.a_an | adName
|
4 | wt.a_ac | 1 |
5 | wt.sys | adclick |
6 | wt.dl | 1 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | data.page-uri | /ad/impression |
2 | wt.ev | adimpression |
3 | wt.a_an | adNames
|
4 | wt.a_ai | "1;1;...;1" |
5 | wt.sys | adimpression |
6 | wt.dl | 61 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | ora.element_name | screenName
|
2 | ora.element_id | screenId
|
3 | ora.element_type | screen |
4 | data.page-uri | /screen/view |
5 | wt.ti | screenName
|
6 | wt.ev | screenView |
7 | wt.sys | screen |
8 | wt.dl | 0 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | ora.element_name | buttonName
|
2 | ora.element_id | buttonId
|
3 | ora.element_type | button |
4 | data.page-uri | /button/tap |
5 | wt.ev | buttonTap |
6 | wt.sys | button |
7 | wt.dl | 1 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | ora.element_name | contentName
|
2 | ora.element_id | contentId
|
3 | ora.element_type | content |
4 | data.page-uri | /content/view |
5 | wt.ev | contentView |
6 | wt.sys | content |
7 | wt.dl | 61 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | data.page-uri | application/drag_and_drop |
2 | wt.ti | eventMeta.eventDescr |
3 | wt.pi | eventMeta.eventDescr |
4 | wt.ev | eventMeta.eventType |
5 | wt.sys | drag_and_drop |
6 | wt.dl | 61 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | data.page-uri | /media |
2 | wt.ev | mediaEvent |
3 | wt.clip_n | mediaName
|
4 | wt.clip_t | mediaType
|
5 | wt.clip_ev | mediaEventType
|
6 | wt.sys | media |
7 | wt.dl | 60 |
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 usersearchResult
: Specifies the results of search query
The Infinity parameters and their values specific to this event are as follows:
Infinity Parameter | Value | Notes | |
---|---|---|---|
1 | data.page-uri | /search | |
2 | wt.ev | search | |
3 | wt.oss | searchPhrase
|
Phrase searched by the user |
4 | wt.oss_r | searchResult
|
Results of search query |
5 | wt.sys | search | |
6 | wt.dl | 60 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | data.page-uri | /conversion |
2 | wt.ev | conversion |
3 | wt.conv | conversionName
|
4 | wt.si_cs | 1 |
5 | wt.sys | conversion |
6 | wt.dl | 60 |
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 dataproductName
: 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:
Infinity Parameter | Value | Notes | |
---|---|---|---|
1 | data.page-uri | eventMeta.eventPath | |
2 | wt.ti | eventMeta.eventDescr | |
3 | wt.pi | eventMeta.eventDescr | |
4 | wt.ev | eventMeta.eventType | |
5 | wt.cg_n | contentGroup | |
6 | wt.tx_e | productMeta.type |
|
7 | wt.tx_s | productMeta.subtotal | Sub Total of the products in the cart |
8 | wt.tx_u | productMeta.units | No. of units in the transaction |
9 | wt.pn_id | productMeta.productId | |
10 | wt.pn_sku | productMeta.productSku | |
11 | wt.dl | 0 | |
12 | wt.sys | product | |
13 | ora.product_name | productMeta.productName | |
14 | ora.product_category | productMeta.productCategory | |
15 | ora.product_brand | productMeta.productBrand |
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 anORAProduct
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 dataname
: 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:
Infinity Parameter | Value | Notes | |
---|---|---|---|
1 | data.page-uri | /product | |
2 | wt.ev | product | |
3 | wt.tx_e | product.type |
|
4 | wt.tx_s | product.subtotal | Sub Total of the products in the cart |
5 | wt.tx_u | product.units | No. of units in the transaction |
6 | wt.pn_id | product.id | |
7 | wt.pn_sku | product.sku | |
8 | wt.dl | 60 | |
9 | wt.sys | product | |
10 | ora.product_name | product.name | |
11 | ora.product_category | product.category | |
12 | ora.product_brand | product.brand |
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 anORAProduct
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 dataname
: 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:
# | Infinity Parameter | Value | Notes |
---|---|---|---|
1 | data.page-uri | /cart/transaction | |
2 | wt.ev | cartEvent | |
3 | wt.tx_e | p | |
4 | wt.tx_s | product.subTotal | Sub Total of the products in the cart |
5 | wt.tx_u | product.units | No. of units in the transaction |
6 | wt.pn_id | product.id | |
7 | wt.pn_sku | product.sku | |
8 | wt.tx_id | Invoice Date(autogenerated parameter) | |
9 | wt.tx_it | Invoice Time (autogenerated parameter | |
10 | wt.tx_i | Invoice Number | |
11 | wt.dl | 60 | |
12 | wt.sys | transaction | |
13 | ora.product_name | product.name | |
14 | ora.product_category | product.category | |
15 | ora.product_brand | product.brand |
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:
Infinity Parameter | Value | |
---|---|---|
1 | wt.ev | eventName
|
2 | data.page-uri | /custom |
3 | wt.sys | custom |
4 | wt.dl | 61 |
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:
Infinity Parameter | Value | |
---|---|---|
1 | data.page-uri | eventMeta.eventPath |
2 | wt.ti | eventMeta.eventDescr |
3 | wt.pi | eventMeta.eventDescr |
4 | wt.ev | eventMeta.eventType |
5 | wt.sys | sys_info |
6 | wt.dl | 61 |