In the first part of this series, we covered how to connect a mobile app to Marketing Cloud Personalization using Salesforce’s Mobile SDK. In this post, we’ll explore how to send catalog items from the mobile app to your dataset.
What’s new on the DemoApp?
Since the last post, I made some changes in the app. The app is connected to a free NASA API where takes information from the Mars Rover Photos connection. This connection returns an array of images taken on a specific earth’s date. For the demo purposes I’m only using the first record on that array. This API is designed to collect image data gathered by NASA’s Curiosity, Opportunity, and Spirit rovers on Mars. The API make it more easily available to other developers, educators, and citizen scientists.
The app has two different views, the main view and the display image view. In the main view, the user picks the Earth’s date and the app sends it to the API to retrieve a picture. The second view displays the picture along with some information (see image below). The goal here is to send the item (the picture and its information) to Personalization.
The role of Personalization’s Event API
Marketing Cloud Personalization provides an Event API that sources use to send event data to the platform, where the event pipeline processes it. Then you can return Campaigns data that can be served to the end user. Developers cannot use of this API to handle mobile application events.
“The Personalization Mobile SDK has separate functionality used for mobile app event processing, with built-in features that are currently unavailable through the Event API.”
So, we can eliminate possibility to use the Event API in this use case.
Tracking Items
Tracking items is an important part of any Personalization implementation. Configure the Catalog Object so that it log and event when a user has viewed productFor example, imagine you have an app that sells the sweaters you knit. You want to know how many users go to “Red and Blue Sweater” product. With that information you can promote other products that those users might like, so they will be more likely to buy from you.
There are two ways to track items and actions. Track catalog objects like Products, Articles, Blogs and Categories (which are the main catalog objects in Personalization) and you can also add Tags as a related catalog objects for those I name before.
You can also track actions like AddToCard, RemoveFromCart and Purchase.
Process Catalog Objects/Item Data
In order to process the catalog and item data we are going to sent from our mobile application, we need to activate the Process Item Data from Native Mobile Apps . This option will make it possible for Personalization to process the data. By default Personalization ignores all the mobile catalog data that it receives.
To activate this functionality, hover over SETTING > GENERAL SETUP > ADVANCE OPTIONS > Activate Process Item Data from Native Mobile Apps
The SDK currently works for Products, Articles and Blogs, those are called Items. They will be able to track purchases, comments, or views. They also will be able to relate with other catalog objects like brand, category and keyword.
Methods to process item data
The following methods are used to track the action of the users viewing and Item or the detail of and item. The web comparison for these methods are the SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject and the SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObjectDetail
viewItem: and viewItem:actionName:
These methods track when a user views an item. Personalization will automatically track the time spent viewing the item while the context, app, and user is active. The item will remain the one viewed until this method or viewItemDetail are called again. See documentation Here
The second method have the actionName parameter that is use for different action name to distinguish this View Item.
evergageScreen?.viewItem(_ item: EVGItem?) evergageScreen?.viewItem(_ item: EVGItem?, actionName: String?)
View Item Interaction in the Event Stream:
View Item interaction using the actionName parameter
EVGItemis an abstract base class. An item is something in the app that users can view or otherwise engage with. Classes like EVGProduct or EVGArticle inherits from this class
The question mark at the end of String and EVGItem means that the value is optional or can be nil . The last one can happen to the EVGItem if have some invalid value.
viewItemDetail: and viewItemDetail:actionName:
These methods track details when a user views an item, such as looking at other product images or opens the specifications tab. Personalization will automatically track the time spent viewing the item while the context, app, and user is active. The item will remain the one viewed until this method or viewItem: are called again.
The second method have the actionName parameter that its use for different action name to distinguish this View Item Detail.
evergageScreen?.viewItemDetail(_ item: EVGItem?) evergageScreen?.viewItemDetail(_ item: EVGItem?, actionName: String?)
View Item Detail interaction in the Event Stream:
View Item Detail interaction but using the actionName parameter:
Now we have define those EVGItem objects with the actual catalog object we want to track Blog / Category / Articles / Product.
The EVGProduct Class
By definition, a Product is an item that a business can sell to users. Products can be added to EVGLineItem objects when they have been ordered by the user.
We have a group of initializers we can use to create an Evergage product and send it back to Personalization. The EVGProduct class have variety of methods we can use. For this post I will show the most relevant to use.
Something important to remember is that in order to use classes like EVGProduct or EVGArticle, we need to import the
Evergagelibrary.
The productWithId: method
The most basic of them all, we just need to pass the ID of the product and that’s it. This can be useful if we don’t want to provide too much information.
evergageScreen?.viewItem(EVGProduct.init(id: "p123"))
The productWithId:name:price:url:imageUrl:evgDescription: method
Builds an EVGProduct, including many of the commonly used fields. This constructor use the id, name, price, url, image and description fields of the Product catalog object.
As a reminder , I’m building my Product catalog object using the images from the Mars Rover Photos with some other attributes that we got in the response from the API
For this constructor, the values I’m sending in the parameters are:
- The ID of the image returned in the JSON
- The full name of the camera that took the photo
- A price of 10 (just because this needs a value here)
- The image URL returned in the JSON
- A description I made using the earth, landing and launching dates.
All I just have to do is pass the new item using any of the method we use to track item data.
let item : EVGItem = EVGProduct.init(id:String(id),
name: name,
price: 10,
url: url,
imageUrl: imageUrl,
evgDescription: "This is a photo taken form \(roverName). Earth Date: \(earthDate). Landing Date: \(landingDate). Launch Date: \(launchDate)")
evergageScreen?.viewItemDetail(item)
The item declaration ir correct since EVGProduct inherits from EVGItem.
After populating the information, the catalog object will look like this inside Marketing Cloud Personalization:
The productFromJSONDictionary: method
As the name says it creates an EVGProduct from the provided JSON dictionary. A JSON dictionary is an array of key-value pair in the form [String : Any] where you add attributes from the Product catalog object.
let productDict : [String : Any] = [
"_id": String(id),
"url": url,
"name": name,
"imageUrl": imageUrl,
"description": "This is a photo taken form \(roverName). Earth Date: \(earthDate). Landing Date: \(landingDate). Launch Date: \(launchDate)",
"price": 10,
"currency": "USD",
"inventoryCount": 2
]
let itemJson: EVGItem? = EVGProduct.init(fromJSONDictionary: productDict)
evergageScreen?.viewItemDetail(itemJson, actionName: "User did specific action")
Then you can initialize the EVGProduct object with the constructor that uses the fromJSONDictionary parameter.
The last step here will be sent the action with the viewItemDetail method.
This is how the record should look like after the creation in the dataset.
Final Class
This is how our class will look with the methods to sent the item interactions.
Bonus: How to set attributes values?
Imagine you also want to set attributes to sent to personalization like first name, last name, email address or zip code. If you want to do that, all you need to do its to use the setUserAttribute method inside the AppDelegate class or after the user logs in. We used this class to pass the id of the user and to set the datasetID.
After the user logs in you can pass the information you need to personalization The setUserAttribute:forName: sets an attribute (a name/value pair) on the user. The next event will send the new value to the Personalization dataset.
evergage.setUserAttribute("attributeValue", forName: "attributeName")
//Following the example
evergage.userId = evergage.anonymousId
evergage.setUserAttribute("Raul", forName: "firstName")
evergage.setUserAttribute("Juliao", forName: "lastName")
evergage.setUserAttribute("raul@gmail.com", forName: "emailAddress")
evergage.setUserAttribute("123456", forName: "zipCode")
The set attributes event:
The Customer’s Profile view
Conclusion: Syncing Your Mobile App’s Catalog with Personalization
To wrap things up, setting up Articles, Blogs, and Categories works pretty much the same way as setting up Products. The structure stays consistent—you just have to keep in mind that each one belongs to a different class, so you’ll need to tweak things slightly depending on what you’re working with.
That said, one big limitation to note is that you can’t send custom attributes in catalog objects, even if you try using the JSON dictionary method. I tested a few different approaches, and unfortunately, it only supports the default attributes.
Also, the documentation doesn’t really go into detail about using other types of catalog objects outside of Articles, Blogs, Products, and Categories. It’s unclear if custom catalog objects are supported at all through the mobile SDK, which makes things a bit tricky if you’re looking to do something more advanced.
In part 3 we are going to take a look at how to set push notifications and mobile campaigns.
