Mobile Event Types
The following are the types of events that you can report from your mobile app to Responsys for retargeting use cases. The sections following this table describe the key attributes that must be sent to Responsys for the mobile app event type, as well as optional attributes that you can include.
| Event Type Name | Event Type | Event Action | When to use this event |
|---|---|---|---|
$Searched
|
SEARCH | --- | The mobile app user has conducted a search in the app. See $Searched event attributes for more information. |
$Browsed
|
BROWSE | --- | The mobile app user has browsed a product details screen or product quick view overlay on a category screen. See $Browsed event attributes for more information. |
$AddedItemToCart
|
CART | ADD | The mobile app user has added an item to the cart. See $AddedItemToCart event attributes for more information. |
$RemovedItemFromCart
|
CART | REMOVE | The mobile app user has removed an item from the cart. See$RemovedItemFromCart event attributes for more information. |
$ClearedCart
|
CART | CLEAR | The mobile app user has cleared the cart. See $ClearedCart event attributes for more information. |
$UpdatedStageOfCart
|
CART | UPDATE | The mobile app user has advanced the state of the cart. See $UpdatedStageOfCart event attributes for more information. |
$PurchasedCart
|
CART | PURCHASE | The mobile app user has completed the purchase. See $PurchasedCart event attributes for more information. |
How the SDK processes the trackEvent call
The SDK groups mobile app events into a JSON request and sends the event data. When the event data arrives in the Responsys system, the system processes the JSON request and stores it in the proper mobile event definition table in the database. From there, Responsys can use the event data to derive the composite events that trigger actions in a remarketing program orchestration, such as sending a reminder message to a mobile app user who has added items to the shopping cart but not purchased the items.
Common Event Properties set by Responsys
The SDK includes the following common event properties in the request that it sends to Responsys – you do not need to do anything specific to have these included, except pass the event type value (for example, $AddedItemToCart) when calling the trackEvent method:
- Event Type: See list in the table above. In the mobile app code, you'll specify the event type value when calling the
trackEventmethod. - Account Token: The encoded Responsys account ID, a unique identifier that helps Responsys customers to interact with only their mobile applications.
- App Token/API Key: The unique identifier generated when you set up your mobile app's platforms in the Mobile App Developer Console in Responsys. It enables Responsys to communicate with your mobile app on the different platforms your mobile app supports. For example, when a push is intended for iOS only, the App Token enables Responsys to send push notifications to your mobile app installed on iOS devices. Also known as the API Key.
When Responsys receives the request from the mobile app, it puts the data into the correct mobile event definition table. Responsys derives the following key/value pairs – you do not need to specify them in the trackEvent event attributes.
| Name | Description | Value (type) |
|---|---|---|
Utype
|
The type of user ID. For mobile apps, always use D. | D (string) |
Uid
|
The user ID. For mobile apps, the SDK always sends the app token (also known as the API key) and the device ID and Responsys stores them concatenated with a colon (format shown in the Value column). Responsys uses the Uid to associate the event with the device’s App Channel List record and, for known users, the user’s Profile List record. | app_token:device_id (string) |
Etype
|
Event type. SDK derives this from the Event Type Name that you pass in the trackEvent call. |
One of the following (string): CART BROWSE SEARCH |
Action
|
Event action for CART event types. SDK derives this from the Event Type Name that you pass in the trackEvent call. | One of the following (string): ADD REMOVE CLEAR UPDATE PURCHASE |
Channel
|
Generically, the marketing channel where a visitor originated. Marketers can filter for Channel=M when they want to send a retargeting campaign for the mobile apps only. |
M (string) |
$Searched event attributes
The $Searched event captures when a user conducts a search in your mobile app. The captured search event data will be processed to identify Search Retargeting opportunities.
The $Searched event code should report the event after the search button/link is clicked, for example, on the subsequent search results screen.
Required retargeting event name
When your mobile app code calls trackEvent, it must include the event name: $Searched.
Required Attributes
When your mobile app code calls trackEvent, it must include the following attributes/event properties:
| Name | Description | Value (type) |
|---|---|---|
Searchterm
|
The search term used when the mobile app user ran the search. | (string) Example: dress shoes size 10 |
Optional Attributes
When your mobile app code calls trackEvent, it optionally can include the following attributes/event properties:
| Name | Description | Value (type) |
|---|---|---|
Aggpara01 Aggpara02 ... Aggpara12 |
Aggpara is an open-ended attribute that allows you to capture a value of your choice. For example, if you want to capture the brand of a product, you can dedicate Aggpara01 to store this value. You can send up to 12 different Aggpara attributes. When the retargeting tool processes the event data, the captured values for the Aggpara attribute will roll up into a comma-delimited list and be made available in the related Program entry variable. |
(string) Example: dress shoes size 10 |
$Browsed event attributes
The $Browsed event captures when a mobile app user browses a product details screen. The captured browse event data will be processed to identify Browse Abandonment opportunities.
The $Browsed event code should be reported when the user opens the product details screen. Some mobile apps feature "Preview" or "Quick View" overlay windows, which allow a user the ability to click on a link next to a product on the category screen to show more details about the product in an overlay window without leaving the category screen itself. This product details overlay window can be considered a $Browsed event. If this is true with your mobile app, the $Browsed event code can be called when the user opens the overlay window.
Required retargeting event name
When your mobile app code calls trackEvent, it must include the event name: $Browsed.
Required Attributes
Not applicable – the system sets all required attribute values.
Optional Attributes
When your mobile app code calls trackEvent, it optionally can include the following attributes/event properties:
| Name | Description | Value (type) |
|---|---|---|
Aggpara01 Aggpara02 Aggpara03 |
Aggpara is an open-ended attribute that allows you to capture a value of your choice. For example, if you want to capture the brand of a product, you can dedicate Aggpara01 to store this value. You can send up to 3 different Aggpara attributes. When the retargeting tool processes the event data, the captured values for the Aggpara attribute will roll up into a comma-delimited list and be made available in the related Program entry variable. |
(string) Example: Ultra Violet |
Pid
|
The product ID, SKU or a unique identifier of the product associated to the mobile app event. For the $Browsed event, the system expects a single value. | (string) Example: 113123dfdrr |
Pc
|
The product category of the product associated to the mobile app event. | (string) Example: Shoes |
Pcartid
|
Cart ID | (string) Example: 12cdsd234r |
Pprice
|
The price of the product associated to the mobile app event. | (string) Example: 500.00 |
Src
|
The source associated to the event. | Example: Your mobile app has different regional versions: US, Japan, and UK. You can use Src to capture the regional version of the mobile app. |
$AddedItemToCart event attributes
The $AddedItemToCart event captures when a mobile app user adds a product to the shopping cart. The captured add item event data will be processed to identify Cart Abandonment opportunities.
The $AddedItemToCart event code should report the event after the “add to cart” button/link is clicked, such as on the subsequent cart view screen or overlay.
The retargeting tool does not keep track of quantity. The retargeting tool registers each addition of the same product to the cart almost as if the mobile app user has added a new product. For example, if a mobile app user clicks the Add to Cart button for a product from the product details screen, and then clicks on the Add to Cart button for the same product shortly after, the retargeting tool sees that as two line items of the same product instead of two quantities of the same product in one line item. This is an important thing to note when using $RemovedItemFromCart.
Required retargeting event name
When your mobile app code calls trackEvent, it must include the event name: $AddedItemToCart.
Required Attributes
Not applicable – the system sets all required attribute values.
NOTE: For this CART event, Pid is not required, but we recommend including it.
Optional Attributes
When your mobile app code calls trackEvent, it optionally can include the following attributes/event properties:
| Name | Description | Value (type) |
|---|---|---|
Aggpara01 Aggpara02 Aggpara03 |
Aggpara is an open-ended attribute that allows you to capture a value of your choice. For example, if you want to capture the brand of a product, you can dedicate Aggpara01 to store this value. You can send up to 3 different Aggpara attributes. When the retargeting tool processes the event data, the captured values for the Aggpara attribute will roll up into a comma-delimited list and be made available in the related Program entry variable. |
(string) Example: MyBrand01 |
Lastpara01 Lastpara02 |
Lastpara is an open-ended attribute that allows you to capture a value of your choice. For example, if you want to capture the color of a product, you can dedicate Lastpara01 to store this value. You can send up to 2 different Lastpara attributes for this event. When the retargeting tool processes the event data, the captured values for the Lastpara attribute will roll up to feature the last value and be made available in the related Program entry variable. |
(string) Example: Ultra Violet |
Pid
|
The product ID, SKU or a unique identifier of the product associated to the mobile app event | (string) Example: 113123dfdrr |
Pc
|
The product category of the product associated to the mobile app event. | (string) Example: Shoes |
Pcartid
|
Cart ID | (string) Example: 12cdsd234r |
Pprice
|
The price of the product associated to the mobile app event. | (string – ensure that punctuation is URL encoded) Example: 500.00 |
Src
|
The source associated to the event. | Example: Your mobile app has different regional versions: US, Japan, and UK. You can use Src to capture the regional version of the mobile app. |
$RemovedItemFromCart event attributes
The $RemovedItemFromCart event captures when a mobile app user removes a product that was previously added to the shopping cart. This will help prevent products that the user is no longer interested in from appearing during the personalization of retargeting campaign messages. This will also help prevent the system from sending a retargeting campaign to the user if the user has removed all products from the shopping cart.
The $RemovedItemFromCart event code should report the event after the remove product button/link is clicked or when the quantity of the product has been reduced to zero in the cart view screen or overlay.
Required retargeting event name
When your mobile app code calls trackEvent, it must include the event name: $RemovedItemFromCart.
Required Attributes
When your mobile app code calls trackEvent, it must include the following attributes/event properties:
| Name | Description | Value (type) |
|---|---|---|
Pid
|
Product ID of the product removed from the cart. For the $RemovedItemFromCart event, the system expects a single value. |
(string) Example: 113123dfdrr |
Optional Attributes
Not applicable.
$ClearedCart event attributes
The $ClearedCart event captures when a mobile app user removes all products from the shopping cart.
The $ClearedCart event code should report the event when the clear cart button/link is clicked in the cart view screen or overlay.
Required retargeting event name
When your mobile app code calls trackEvent, it must include the event name: $ClearedCart
Required Attributes
Not applicable – the system sets all required attribute values.
Optional Attributes
Not applicable.
$UpdatedStageOfCart event attributes
The $UpdatedStageOfCart event is used to keep track of the stage of the purchasing process the mobile app user is in. Depending on the flow of your mobile app, users can move through several stages of the purchasing process from the moment they add the products to the cart to when they ultimately purchase the products. For example, after the user adds a product to the cart, the user can proceed with the purchase of the product by clicking the Checkout button to start the checkout process. This may take the user through several stages before they can finally purchase. It may begin with the Shipping Information screen and then the Billing Information screen. Finally, the flow may take the user to the Purchase Summary screen, where the user can click on a button to complete the purchase.
As you can see in this scenario, there are four stages before the product is actually purchased:
- Product(s) in Cart
- Shipping Information Screen
- Billing Information Screen
- Purchase Summary
When the retargeting tool processes the cart-related event data, it will feature the last stage the visitor is in when they enter the Cart Abandonment entry stage. You can use the information about what they last stage was to tailor the retargeting message.
The $UpdatedStageOfCart event code should report the event when the mobile app user proceeds to a new stage in the purchasing process. For example, this can be when they click on the Checkout button on the cart view screen, when they continue the checkout process and the shipping page is loaded, etc.
Required retargeting event name
When your mobile app code calls trackEvent, it must include the event name: $UpdatedStageOfCart
Required Attributes
When your mobile app code calls trackEvent, it must include the following attributes/event properties:
| Name | Description | Value (type) |
|---|---|---|
Stage
|
Stage of the event. Describes where the user is at in the purchase process. Values determined by the mobile app developer and marketer. | (string) Examples: Checkout BillingInfo ShippingInfo |
Optional Attributes
Not applicable.
$PurchasedCart event attributes
The $PurchasedCart event is associated to a mobile app user purchasing a product in the shopping cart. Marketers use this event mainly to prevent the system from sending a Cart Abandonment message after a user makes a purchase. Marketers should not use this event to trigger a Purchase Confirmation message or an e-receipt.
The $PurchasedCart event code should report the event after the user clicks the submit order button or when the mobile app displays the subsequent order confirmation screen. We recommend initiating the code only once and featuring the purchased products as a comma-delimited list in the Pid (product ID) attribute. Alternatively, you can initiate the event code for each product that the user purchased.
Required retargeting event name
When your mobile app code calls trackEvent, it must include the event name: $PurchasedCart
Required Attributes
When your mobile app code calls trackEvent, it must include the following attributes/event properties:
| Name | Description | Value (type) |
|---|---|---|
Pid
|
Product ID of the product(s) purchased. For the $PurchasedCart event, you can send a single event and include the product IDs for all items purchased as a set of comma-separated values. |
(string; comma-separated values when sending multiple Pid values in a single event) Examples: 113123dfdrr (single item) OR 123r34d,3ddadsqr,3r34rd (3 items) |
Optional Attributes
When your mobile app code calls trackEvent, it optionally can include the following attributes/event properties:
| Name | Description | Value (type) |
|---|---|---|
Aggpara01 Aggpara02 Aggpara03 |
Aggpara is an open-ended attribute that allows you to capture a value of your choice. For example, if you want to capture the brand of a product, you can dedicate Aggpara01 to store this value. You can send up to 3 different Aggpara attributes. When the retargeting tool processes the event data, the captured values for the Aggpara attribute will roll up into a comma-delimited list and be made available in the related Program entry variable. |
(string) Example: MyBrand01 |
Lastpara01 Lastpara02 |
Lastpara is an open-ended attribute that allows you to capture a value of your choice. For example, if you want to capture the color of a product, you can dedicate Lastpara01 to store this value. You can send up to 2 different Lastpara attributes for this event. When the retargeting tool processes the event data, the captured values for the Lastpara attribute will roll up to feature the last value and be made available in the related Program entry variable. |
(string) Example: Ultra Violet |
Pid
|
The product ID, SKU or a unique identifier of the product associated to the mobile app event | (string) Example: 113123dfdrr |
Pc
|
The product category of the product associated to the mobile app event. | (string) Example: Shoes |
Pcartid
|
Cart ID | (string) Example: 12cdsd234r |
Pprice
|
The price of the product associated to the mobile app event. | (string – ensure that punctuation is URL encoded) Example: 500.00 |
Src
|
The source associated to the event. | Example: Your mobile app has different regional versions: US, Japan, and UK. You can use Src to capture the regional version of the mobile app. |
Common Event Properties set by Responsys
The SDK includes the following common event properties in the request that it sends to Responsys – you do not need to do anything specific to have these included, except pass the event type value (for example, $AddedItemToCart) when calling the trackEvent method:
- Event Type: See list in the table above. In the mobile app code, you'll specify the event type value when calling the
trackEventmethod. - Account Token: The encoded Responsys account ID, a unique identifier that helps Responsys customers to interact with only their mobile applications.
- App Token/API Key: The unique identifier generated when you set up your mobile app's platforms in the Mobile App Developer Console in Responsys. It enables Responsys to communicate with your mobile app on the different platforms your mobile app supports. For example, when a push is intended for iOS only, the App Token enables Responsys to send push notifications to your mobile app installed on iOS devices. Also known as the API Key.
When Responsys receives the request from the mobile app, it puts the data into the correct mobile event definition table. Responsys derives the following key/value pairs – you do not need to specify them in the trackEvent event attributes.
| Name | Description | Value (type) |
|---|---|---|
Utype
|
The type of user ID. For mobile apps, always use D. | D (string) |
Uid
|
The user ID. For mobile apps, the SDK always sends the app token (also known as the API key) and the device ID and Responsys stores them concatenated with a colon (format shown in the Value column). Responsys uses the Uid to associate the event with the device’s App Channel List record and, for known users, the user’s Profile List record. | app_token:device_id (string) |
Etype
|
Event type. SDK derives this from the Event Type Name that you pass in the trackEvent call. | One of the following (string): CART BROWSE SEARCH |
Action
|
Event action for CART event types. SDK derives this from the Event Type Name that you pass in the trackEvent call. | One of the following (string): ADD REMOVE CLEAR UPDATE PURCHASE |
Channel
|
Generically, the marketing channel where a visitor originated. Marketers can filter for Channel=M when they want to send a retargeting campaign for the mobile apps only. |
M (string) |