class eMarketerTracker
The main class is called eMarketerTracker. It is singleton, so you don’t need to instantiate it, just call it’s default instance’s (eMarketerTracker.inst) methods. By design, this class will persist it’s e-Marketer state (that includes what campaigns are matching, and what actions are currently to be presented) across application shut down. You don’t need to manage the state. Right after calling eMarketerTracker.inst.initialize() (see below), the current state will be available. That is, eMarketerTracker.inst.getResult() will always return what campaigns are currently matching for the device user, or were matching last time.
All the methods of eMarketerTracker are thread-safe.
All the methods except eMarketerTracker.inst.getResult() and eMarketerTracker.inst.done() don’t query e-Marketer server, but delay their effect till eMarketerTracker.inst.getResult() or eMarketerTracker.inst.done()called.
Typical example:
// Before calling other methods, need to initialize
eMarketerTracker.inst.initialize("8C03F1C7FF861065B3D063CD6A4DD0F8E8008FE9") // replace API key with yours
// Log navigation to document called MainActivity
eMarketerTracker.inst.navigate("ViewController")
// Log that in this document product ID A1000 was viewed
eMarketerTracker.inst.productViewed("A1000")
// Get current state, that includes matching campaigns ("conditions") and actions to be presented
eMarketerTracker.inst.getResult()
{ result, error in
if let error = error
{ self.labelError.text = error.localizedDescription
}
else if let result = result
{ for item in result.conditions
{ // item.name
// ...
}
for item in result.actions
{ // item.name
// item.contentType
// ...
}
}
}
eMarketerTracker.inst.initialize()
func initialize(apiKey: String)
This method is the first one you need to call, before calling other methods. You can freely call it several times, this will not hurt.
- apiKey – Your account’s API key.
eMarketerTracker.inst.navigate()
func navigate(documentName: String)
e-Marketer is event-driven system. What actions will be presented, and what products recommended depends on user’s behavior. So you need to log what your user is doing, like what document he is viewing.
- documentName – the “document” is whatever you define like that. Typically it is an activity name. In e-Marketer panel you can specify on what documents actions need to be presented, and what actions (e.g. what recommendation algorithm).
If you call eMarketerTracker.inst.navigate(), and then report product interaction events (see below), these events will be attributed to the current document the user is in – the document you logged through this method.
eMarketerTracker.inst.logUserData()
func logUserData(field: String, value: String)
Send to e-Marketer information about the user, like his email, gender, and so on. Later in e-Marketer panel you will be able to use this information. Either to target specific users, to show appropriate products, or to print this information inside an action content. For example, if you send a user email to e-Marketer, you will be able to create a mailing list, so this user will receive promotional or informative emails.
- field – can be any field name, like “first_name”, “email”, or “Boots size”.
- value – the field’s value (like “Johnny”)
eMarketerTracker.inst.productViewed()
func productViewed(productId: String)
Report to e-Marketer the fact that certain product was viewed by your visitor (because you probably just presented it in the application). For e-Marketer it’s important to know that the product was viewed. You can base recommendations on last viewed product, or all viewed products. And also e-Marketer can avoid showing the currently viewing product in recommendations (because the user sees it anyway).
- productId – the “Internal ID” column in your products catalog, that you imported to e-Marketer.
eMarketerTracker.inst.productAddedToCart()
func productAddedToCart(productId: String)
Report to e-Marketer the fact that certain product was added to cart in your application. You can have recommendations based on currently in-cart products. And if the user abandons the purchase, you can create an email campaign that will recommend to the user products similar to those he had in his cart.
- productId – the “Internal ID” column in your products catalog, that you imported to e-Marketer.
eMarketerTracker.inst.productLiked()
func productLiked(productId: String)
If your application supports wishlists, or favorites, or something similar, call this method to report e-Marketer about such event. e-Marketer will save the state of this product as “liked”, and you will be able to create action that presents all the liked products (that you reported).
- productId – the “Internal ID” column in your products catalog, that you imported to e-Marketer.
eMarketerTracker.inst.productPurchased()
func productPurchased(productId: String)
Report to e-Marketer that a product was purchased through your application.
- productId – the “Internal ID” column in your products catalog, that you imported to e-Marketer.
eMarketerTracker.inst.productUnliked()
func productUnliked(productId: String)
A product removed from wishlist in your application. If such product was not reported as “liked” in the past, this call will have no effect.
- productId – the “Internal ID” column in your products catalog, that you imported to e-Marketer.
eMarketerTracker.inst.productRemovedFromCart()
func productRemovedFromCart(productId: String)
A product removed from cart in your application. If such product was not reported as “added to cart” in the past, this call will have no effect.
- productId – the “Internal ID” column in your products catalog, that you imported to e-Marketer.
eMarketerTracker.inst.productsPurchased()
func productsPurchased()
Report that all the products that were reported as “added to cart” were purchased in your application. So they will become purchased on e-Marketer too.
eMarketerTracker.inst.productsUnliked()
func productsUnliked()
Report that all the products that were reported as “liked” were removed from wishlist in your application.
eMarketerTracker.inst.productsRemovedFromCart()
func productsRemovedFromCart()
Report that all the products that were reported as “added to cart” were removed from cart in your application, that is, the cart was emptied.
eMarketerTracker.inst.articleViewed()
func articleViewed(articleId: String)
eMarketerTracker.inst.articleLiked()
func articleLiked(articleId: String)
eMarketerTracker.inst.articleCommented()
func articleCommented(articleId: String)
eMarketerTracker.inst.articleUnliked()
func articleUnliked(articleId: String)
eMarketerTracker.inst.articleGoal()
func articleGoal(articleId: String)
eMarketerTracker.inst.reportActionClicked()
func reportActionClicked(clicked: eMarketerActionClicked)
When you present actions that eMarketerTracker.inst.getResult() returns in your application through action.renderOnWebView() method, the action is rendered and the user can interact with it. Like click on links in the action HTML, click “close” button (that is supposed to close the action), click on a product in a recommendation widget, and so on.
In these cases action.renderOnWebView() generates events, which are represented by eMarketerActionClicked objects. If you handle those events (closes the WebView widget if “close action” clicked, etc.), report to e-Marketer that you handled them by calling this method.
If you present an action in custom way (not through action.renderOnWebView()), still you are invited to report action events to e-Marketer by calling the following methods of Action object:
eMarketerTracker.inst.getResult()
func getResult(asyncResult: @escaping (_: eMarketerResult?, _: eMarketerError?) -> Void)
This is what we are here for. You called all the above methods in order to eventually get from e-Marketer what campaigns are matching, and what actions are to be presented now to the application user.
You can call this method in any time after eMarketerTracker.inst.initialize(): before eMarketerTracker.inst.navigate() or after. And you can call it several times. The result this method (asynchronously) returns will be different only after some events and/or navigation reports.
As already mentioned above, this state is persistent across application life cycle (this method will still return the same result after application restart).
Typical usage is like this:
eMarketerTracker.inst.getResult()
{ result, error in
if let error = error
{ // Some problem
}
else if let result = result
{ // Have result
}
}
The callback receives 2 parameters:
- result: eMarketerResult?
- error: eMarketerError?
eMarketerResult is dumb structure that only has two fields:
conditions: [eMarketerCondition] actions: [eMarketerAction]
- conditions – this is rarely needed. Only if you want to manually implement some logic in your application depending on what conditions (campaigns) are matching to the user.
- actions – this is the array of actions that you want to present to the user in your application
How will you present the actions, and will you, is your choice. This library provides a way to render HTML actions on a WebView component in your application. Also it gives you access to the HTML or JSON content of the action that you can present by yourself in a custom way.
eMarketerTracker.inst.startNewSession()
func startNewSession()
You can optionally call this method when your application was restarted, to separate events by different sessions. e-Marketer will automatically start new session 1.5 hours after first navigation.
eMarketerTracker.inst.done()
func done()
If you report an event, or series of events and/or navigations, and don’t call eMarketerTracker.inst.getResult(), call this method, to send pending events to e-Marketer It doesn’t hurt to call this method several times.
eMarketerTracker.inst.clearCache()
func clearCache() throws
This library caches various data, like action names, and content to files, and to SharedPreferences. It effectively manages the cache by itself, and normally you don’t need to call this method. Only call for debug purposes.
