Dengage iOS SDK for sending visitor behavior and rendering product recommendations.
Important warning
ProductView, Basket Add/Remove, View Basket, Purchase and Click events must match productId.
This tutorial provides a very simple and quick introduction to the Dengage integration for iOS applications by walking you through details of different events.
To see sample application using iOS SDK, please check iOS SDK repository.
Dengage uses different event types for different visitor actions. You can define following events by using Dengage iOS SDK:
If your request body has a field statusCode, then you have an error in your request. Details of errors are given in below table:
Every event in Dengage shares common parameters and you can add these parameters to all events that will be defined later.
Details of common parameters for events are given below:
Dengage accounts have two important system variables used in integration: APP KEY and Data Center. You can access these values from Integrations menu of Dengage Panel:
To access Integrations menu of Dengage Panel, please login to your Dengage account and navigate to
Settings > Integrations.
Dengage uses podfile for integration into the project. Inside your Xcode project's root folder run the following commands.
- Run pod init to create an empty pod file
- Run pod install to add Cocoapods to your project
- Run open YourProject.xcworkspace to your new Xcode project's workspace.
After, import Segmentify must be defined in AppDelegate.swift and in required classes..
Dengage iOS SDK requires App key, Subdomain and Data Center URL to establish a connection.
Define configuration method in AppDelegate.swift file.
Example configuration is given below:
SegmentifyManager.config(
appkey: “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”,
dataCenterUrl: “https://xxx.segmentify.com“,
subDomain: “example.com”
)
If you do not want console log to be visible, define it as false.
let _ = SegmentifyManager.logStatus(isVisible: true)
You can use the following command to set new configs
SegmentifyManager.setConfig(apiKey: newApiKey, dataCenterUrl: newDataCenterUrl, subDomain: newDomain)
An empty array of type RecommendationModel is required where the products to be suggested are stored within any view controller.
Example;
var recommendations : [RecommendationModel] = []
The response will be stored in this array as the response.
Basic response method for spesific event;
SegmentifyManager.sharedManager(
appKey: appKey,
dataCenterUrl: dataCenterUrl,
subDomain: subDomain).setPageViewEvent(
SegmentifyObject: obj,
callback: { (response: [RecommendationModel]) in
self.recommendations = response
//for example to process on recommendations
self.createProducts(recommendations: self.recommendations)
})
Callback returns as a one-dimensional array. Optional operation on the array can be done to show it in the UI. Widget View is used when the page's widget is actually displayed. Related title: Interaction
func createProducts(recommendations : [RecommendationModel]) {
for recObj in recommendations {
if recObj.instanceId == "YOUR_CAMPAIGN_INSTANCE_ID" {
// to show details of the products in the UI
self.setProductInfos(products: recObj.products!)
}
}
}
When a visitor views a view controller, this event should be sent.
Parameters can be sent with page view event is given below (you can also add common parameters):
An example Page View request is given below:
//define page view object
let obj = PageModel()
obj.category = "Home Page"
obj.lang = "EN"
obj.region = "EU"
//send page view request
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: obj) {
(response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
An example of parameterized use as an alternative;
//send page view request
SegmentifyManager.sharedManager().sendPageView(
category: "Home page", subCategory: String?) {
(response: [RecommendationModel]) in
}
When a visitor wants to search products, this event should be sent.
There are two search type before search input and after search input. Before search input module works until the search is done. After search input starts working after searching. These recommendations are updated after minimum characters written in the search bar. Minimum character count presents in the campaign that is in search request response.
Parameters can be sent with search event is given below (you can also add common parameters):
An example search view request is given below:
//define search view object
let searchViewObj = SearchPageModel()
searchViewObj.query = "Dress"
searchViewObj.lang = "EN"
searchViewObj.region = "EU"
//send search view request
SegmentifyManager.sharedManager().sendSearchPageView(segmentifyObject: searchViewObj){
(response: SearchModel) in
self.response = response
//operations about search
}
SearchModel has five objects: products for product list, campaign for search campaign details, errorString in case of an error, instanceId and interactionId for action identity.
When a visitor views a product, this event should be sent.
If product is also inside a page, don't forget to send a page view event with category 'Product Page' and subCategory product's category too.
Parameters can be sent with product view event is given below (you can also add common parameters):
An example product view request is given below:
// START Page view request
// define page model object
let pageObj = PageModel()
pageObj.category = "Product Page"
// send page view request
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) {
(response: [RecommendationModel]) in
}
// END Page view request
//START Product view request
//define product model object
let ProductObj = ProductModel()
ProductObj.title = "Asymmetric Dress in Black"
ProductObj.category = "Womenswear"
ProductObj.image = "//cdn.shopify.com/s/files/1/1524/5822/products/2014_11_17_Lana_Look034_02_300x300.jpg?v=1475497696"
ProductObj.url = "https://segmentify-shop.myshopify.com/products/asymmetric-dress-black"
ProductObj.inStock = true
ProductObj.brand = "Amelia Toro"
ProductObj.price = 578
ProductObj.productId = "25799860937"
ProductObj.noUpdate = true
//send product view request
SegmentifyManager.sharedManager().sendProductView(segmentifyObject: ProductObj) {
(response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Product view request
An example of parameterized use as an alternative;
//START Page View request
//define page model object
let pageObj = PageModel()
pageObj.category = "Product Page"
//send page view request
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) {
(response: [RecommendationModel]) in
}
//END Page View request
//send product view request
SegmentifyManager.sharedManager().sendProductView(
productID : "25799860937",
title : "Asymmetric Dress in Black",
category : "Womenswear",
price : 578,
brand : "Amelia Toro",
stock : true,
url: "https://segmentify-shop.myshopify.com/products/asymmetric-dress-black",
image: "//cdn.shopify.com/s/files/1/1524/5822/products/2014_11_17_Lana_Look034_02_300x300.jpg?v=1475497696") {
(response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
Dengage uses basket operations as intermediary step for measuring success of recommendations throughout the conversion funnel. Basket success rate is also reported by Trendify and Bannerify to show individual performance of products, categories, brands and banners.
Basket operations are similar to page view and product view. There are two possible steps in a basket operation these are: add product to basket, remove product from basket.
When a visitor adds a product to basket/cart, this event should be sent.
An example request is given below:
//Define basket operations model
let addBasketObj = BasketModel()
addBasketObj.step = "add"
addBasketObj.productId = "25800400265"
addBasketObj.quantity = "2"
addBasketObj.price = 358
//Send add to basket event
SegmentifyManager.sharedManager().sendAddOrRemoveBasket(segmentifyObject: addBasketObj)
An example of parameterized use as an alternative;
//Send add to basket event
SegmentifyManager.sharedManager().sendAddOrRemoveBasket(basketStep : "add", productID : "25800400265", quantity : 2,price : 358)
When a visitor removes a product from basket/cart, this event should be sent.
An example request is given below:
//Define basket operations model
let removeBasketObj = BasketModel()
removeBasketObj.productId = "25799860937"
removeBasketObj.price = 578
removeBasketObj.quantity = "1"
removeBasketObj.step = "remove"
//Send remove from basket request
SegmentifyManager.sharedManager().sendAddOrRemoveBasket(segmentifyObject: obj)
An example of parameterized use as an alternative;
//Send add to basket event
SegmentifyManager.sharedManager().sendAddOrRemoveBasket(basketStep : "remove", productID : "25800400265", quantity : 2,price : 358)
Parameters can be sent with basket operations event is given below (you can also add common parameters):
Dengage uses checkout operations to measure success of recommendations throughout the conversion funnel. Checkout information and steps are also used in email & personalization campaigns. Campaign, Trendify, Bannerify and Sales reports are feed from checkout information. It is essential for both analyitcs and recommendation capabilities to function properly.
Dengage track four different steps of checkout operation:
View Basket is the first step of checkout funnel, and followed by Customer Information.
When a visitor views his/her basket/cart, this event should be sent with basket details.
An example request is given below:
//START Page view request
let pageObj = PageModel()
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) { (response: [RecommendationModel]) in
}
//END Page view request
//START Basket View Request
var productsArray = [Any]()
let firstProduct = ["price":"78","productId":"25799809929","quantity":"1"]
productsArray.append(firstProduct)
let checkoutObj = CheckoutModel()
checkoutObj.productList = productsArray
checkoutObj.totalPrice = 78
SegmentifyManager.sharedManager().sendViewBasket(segmentifyObject: checkoutObj) { (response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Basket View Request
An example of parameterized use as an alternative;
//START Page view request
let pageObj = PageModel()
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) { (response: [RecommendationModel]) in
}
//END Page view request
//START Basket View Request
var productsArray = [Any]()
let firstProduct = ["price":"78","productId":"25799809929","quantity":"1"]
productsArray.append(firstProduct)
SegmentifyManager.sharedManager().sendViewBasket(totalPrice: 78, productList: productsArray) { (response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Basket View Request
Customer Information is the second step of checkout funnel, and preceeded by View Basket & followed by Payment Information.
When a visitor enters customer information as second step of checkout funnel, this event should be sent with basket details.
An example request is given below:
//START Page view request
let pageObj = PageModel()
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) { (response: [RecommendationModel]) in
}
//END Page view request
//START Customer information request
var productsArray = [Any]()
let firstProduct = ["price":"78","productId":"25799809929","quantity":"1"]
productsArray.append(firstProduct)
let custInfObj = CheckoutModel()
custInfObj.productList = productsArray
custInfObj.totalPrice = 78
SegmentifyManager.sharedManager().sendCustomerInformation(segmentifyObject: custInfObj) { (response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Customer information request
An example of parameterized use as an alternative;
//START Page view request
let pageObj = PageModel()
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) { (response: [RecommendationModel]) in
}
//END Page view request
//START Customer information request
var productsArray = [Any]()
let firstProduct = ["price":"78","productId":"25799809929","quantity":"1"]
productsArray.append(firstProduct)
SegmentifyManager.sharedManager().sendCustomerInformation(totalPrice: 78, productList: productsArray) { (response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Customer information request
Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.
Payment Information is the third step of checkout funnel, and preceeded by Payment Information & followed by Purchase/Success.
When a visitor enters payment information as third step of checkout funnel, this event should be sent with basket details.
An example request is given below:
//START Page view request
let pageObj = PageModel()
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) { (response: [RecommendationModel]) in
}
//END Page view request
//START Payment information request
//example array
var productsArray = [Any]()
let firstProduct = ["price":"78","productId":"25799809929","quantity":"1"]
//append product to example array
productsArray.append(firstProduct)
//define a variable type of CheckoutModel
let paymentInf = CheckoutModel()
paymentInf.totalPrice = 78
paymentInf.productList = productsArray
//payment information request
SegmentifyManager.sharedManager().sendViewBasket(segmentifyObject: paymentInf) { (response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Payment information request
An example of parameterized use as an alternative;
//START Page view request
let pageObj = PageModel()
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) { (response: [RecommendationModel]) in
}
//END Page view request
//START Payment information request
//example array
var productsArray = [Any]()
let firstProduct = ["price":"78","productId":"25799809929","quantity":"1"]
//append product to example array
productsArray.append(firstProduct)
//Send user register request
SegmentifyManager.sharedManager().sendPurchase(totalPrice: 78, productList: productsArray, orderNo: 1234) { (response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Payment information request
Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.
Purchase/Success is the fourth and final step of checkout funnel, and preceeded by Payment Information.
When a visitor finalizes a purchase, this event should be sent with basket details.
An example request is given below:
//START Page View
let pageViewObj = PageModel()
pageViewObj.category = "Purchase Success Page"
//send page view request
SegmentifyManager.sharedManager().sendPageView(segmentifyObject: obj) { (response: [RecommendationModel]) in
}
//END Page View
//START Purchase Success request
var productsArray = [Any]()
let firstProduct = ["price":"78","productId":"25799809929","quantity":"1"]
productsArray.append(firstProduct)
let purchaseObj = CheckoutModel()
purchaseObj.productList = productsArray
purchaseObj.totalPrice = 78
purchaseObj.orderNo = "12313"
//Puchase success request
SegmentifyManager.sharedManager().sendPurchase(segmentifyObject: purchaseObj) { (response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Purchase Success request
An example of parameterized use as an alternative;
//START Page view request let pageObj = PageModel() SegmentifyManager.sharedManager().sendPageView(segmentifyObject: pageObj) { (response: [RecommendationModel]) in} //END Page view request //START Purchase Success request //example array var productsArray = [Any]() let firstProduct = ["price":"78","productId":"25799809929","quantity":"1"] //append product to example array productsArray.append(firstProduct) //Send user register request SegmentifyManager.sharedManager().sendPayment(totalPrice: 78, productList: productsArray, orderNo: 1234) { (response: [RecommendationModel]) in self.recommendations = response //operations about recommendations } //END Purchase Success request
Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.
Detailed explanation for each parameter is given below:
Each product inside the basket can be defined with following parameters. See Checkout Parameters for defining checkout operation in which basket product is also defined.
Dengage tracks important user operations like sign-up/register, sign-in/login, sign-out/logout and also you can share your customer's information with Dengage by sending an update event.
Important warning
The userid must be used for the unification operation on all channels in the same userId. See the success department for the web side
There are 4 possible user/visitor operations:
When a visitor registers (sign-up) to your website, you should send a new user event.
If you want to share details of an already registered user with Dengage, please use User Update.
Details of parameters of new user is given below:
An example request is given below:
//Create new user Object
let newUserObj = UserModel()
//Define user object's username and email
newUserObj.username = "Segmentify"
newUserObj.email = "example@Segmentify.com"
//Send user register request
SegmentifyManager.sharedManager().sendUserRegister(segmentifyObject: newUserObj)
An example of parameterized use as an alternative;
//Send user register request
segmentifyManager.sharedManager().sendUserRegister(username: "segmentify", fullName: "Segmentify User", email: "example@Segmentify.com", mobilePhone: "123456789", gender: "Male/Female", age: "4", birthdate: "04/2014")
When a registered customer logins (sign-in), a user login event should be sent to Dengage.
Details of parameters of user login is given below:
An example request is given below:
//Create user Object
let UserObj = UserModel()
//Define user object's username and email
UserObj.username = "Segmentify"
UserObj.email = "example@Segmentify.com"
//Send user login request
SegmentifyManager.sharedManager().sendUserLogin(segmentifyObject: UserObj)
An example of parameterized use as an alternative;
//Send user login request
SegmentifyManager.sharedManager().sendUserLogin(username: "Segmentify", email: "example@segmentify.com")
When a registered customer logouts (sign-out), a user logout event should be sent to Dengage.
Details of parameters of user logout is given below:
An example request is given below:
/Create user Object
let UserObj = UserModel()
//Define user object's username and email
UserObj.username = "segmentify"
UserObj.email = "example@segmentify.com"
//Send user logout request
SegmentifyManager.sharedManager().sendUserLogout(segmentifyObject: UserObj)
An example of parameterized use as an alternative;
//Send user logout request
SegmentifyManager.sharedManager().sendUserLogout(username: "Segmentify", email: "example@segmentify.com")
When you want to share an already registered customer information, provide details of the customer by sending an user update event. You can use both this integration for both frequently updating user information and instant updates when customer updates his/her personal information.
If you want to share a new registered user with Dengage, please use New User.
Details of parameters of user update is given below:
An example request is given below:
//Create new user Object
let UserObj = UserModel()
//Define user object's username and email
UserObj.username = "Segmentify"
UserObj.email = "example@segmentify.com"
//Send user update request
SegmentifyManager.sharedManager().sendUserRegister(segmentifyObject: UserObj)
An example of parameterized use as an alternative;
//Send user update request
DegmentifyManager.sharedManager().sendUserUpdate(username : "Segmentify", fullName : "Segmentify Test", email : "example@segmentify.com", mobilePhone : "123456789", gender : "Male/Female", age : "4", birthdate : "04/2014", isRegistered : true, isLogin : false)
This event is used when userid wants to be changed.
let userObj = UserChangeModel()
userObj.userId = "XXXXXXXXXXX"
SegmentifyManager.sharedManager().sendChangeUser(SegmentifyObject: userObj)
This integration enables any event & data important for you to be tracked by Dengage and become actionable. With this integration, you can send any non standard events & data to Dengage, and gives endless opportunities to track and take actions to your visitor's behaviour.
Details of parameters of custom event is given below:
An example request is given below:
//Config for Segmentify manager
SegmentifyManager.config(appkey: Constant.segmentifyApiKey, dataCenterUrl: Constant.segmentifyDataCenterUrl, subDomain: Constant.segmentifySubDomain)
//START Custom Event Request
let customObj = CustomEventModel()
let paramDict = ["PRICE":"200-500"]
customObj.type = "test"
customObj.params = paramDict as [String : AnyObject]
SegmentifyManager.sharedManager().sendCustomEvent(segmentifyObject: customObj) { (response: [RecommendationModel]) in
self.recommendations = response
//operations about recommendations
}
//END Custom Event Request
Dengage needs to be thrown to use the information from widgets.
Widget View is used when the page's widget is actually displayed.
if recObj.instanceId == "scn_61869cb94553e000" { // recObj is the recomendationModel object returned from the productView event
//Any actions related to product's
self.interactionId = recObj.interactionId
self.impressionId = recObj.instanceId
SegmentifyManager.sharedManager().sendWidgetView(instanceId: self.impressionId!, interactionId: self.interactionId!)
}
It is necessary to notify the product productId and which campaign it belongs to when it is clicked on a product in any recommendation.
SegmentifyManager.sharedManager().sendClickView(instanceId: self.impressionId!, interactionId: productID)
It is necessary to notify the productId when it is clicked on a product in any search result.
If identity of the campaign in search response is "BEFORE_SEARCH" then instanceId should be bs_product.
If identity of the campaign in search response is "SEARCH" then instanceId should be product.
SegmentifyManager.sharedManager().sendClickView(instanceId: "product", interactionId: "123456789" )
Parameters can be sent with banner operations event is given below (you can also add common parameters):
// Banner impression event
let bannerImpressionOperationModel = BannerOperationsModel()
bannerImpressionOperationModel.type = "impression"
bannerImpressionOperationModel.title = "Gorgeous Duo T-Shirt & Trousers"
bannerImpressionOperationModel.group = "Home Page Slider"
bannerImpressionOperationModel.order = 1
SegmentifyManager.sharedManager().sendBannerImpressionEvent(segmentifyObject: bannerImpressionOperationModel)
// Banner click event
let bannerClickOperationModel = BannerOperationsModel()
bannerClickOperationModel.type = "click"
bannerClickOperationModel.title = "Gorgeous Duo T-Shirt & Trousers"
bannerClickOperationModel.group = "Home Page Slider"
bannerClickOperationModel.order = 1
SegmentifyManager.sharedManager().sendBannerClickEvent(segmentifyObject: bannerClickOperationModel)
// Banner update event
let bannerUpdateOperationModel = BannerOperationsModel()
bannerUpdateOperationModel.type = "update"
bannerUpdateOperationModel.title = "Gorgeous Duo T-Shirt & Trousers"
bannerUpdateOperationModel.group = "Home Page Slider"
bannerUpdateOperationModel.order = 2
SegmentifyManager.sharedManager().sendBannerUpdateEvent(segmentifyObject: bannerUpdateOperationModel);
Parameters can be sent with banner group view event is given below (you can also add common parameters):
// Banner Group View Model
let bannerGroupViewModel = BannerGroupViewModel()
bannerGroupViewModel.group = "Home Page Slider"
// optional parameters
var internalBannerViewArray = [InternalBannerModel]()
let internalBannerModel = InternalBannerModel()
internalBannerModel.title = "Gorgeous Duo T-Shirt & Trousers"
internalBannerModel.order = 1
internalBannerModel.image = "https://cdn.segmentify.com/demo/banner-img2.jpg"
internalBannerModel.urls = ["https://www.example.com/gorgeous-duo-tshirt-trousers"]
internalBannerViewArray.append(internalBannerModel)
let internalBannerModel2 = InternalBannerModel()
internalBannerModel2.title = "Ready to Renew"
internalBannerModel2.order = 2
internalBannerModel2.image = "https://cdn.segmentify.com/demo/banner-img1.jpg"
internalBannerModel2.urls = ["https://www.example.com/ready-to-renew"]
internalBannerViewArray.append(internalBannerModel2)
bannerGroupViewModel.banners = internalBannerViewArray
// optional parameters end
SegmentifyManager.sharedManager().sendBannerGroupViewEvent(segmentifyObject: bannerGroupViewModel)
Parameters can be sent with banner group view event is given below (you can also add common parameters):
// Banner Group View Model
let bannerGroupViewModel = BannerGroupViewModel()
bannerGroupViewModel.group = "Home Page Slider"
// optional parameters
var internalBannerViewArray = [InternalBannerModel]()
let internalBannerModel = InternalBannerModel()
internalBannerModel.title = "Gorgeous Duo T-Shirt & Trousers"
internalBannerModel.order = 1
internalBannerModel.image = "https://cdn.segmentify.com/demo/banner-img2.jpg"
internalBannerModel.urls = ["https://www.example.com/gorgeous-duo-tshirt-trousers"]
internalBannerViewArray.append(internalBannerModel)
let internalBannerModel2 = InternalBannerModel()
internalBannerModel2.title = "Ready to Renew"
internalBannerModel2.order = 2
internalBannerModel2.image = "https://cdn.segmentify.com/demo/banner-img1.jpg"
internalBannerModel2.urls = ["https://www.example.com/ready-to-renew"]
internalBannerViewArray.append(internalBannerModel2)
bannerGroupViewModel.banners = internalBannerViewArray
// optional parameters end
SegmentifyManager.sharedManager().sendBannerGroupViewEvent(segmentifyObject: bannerGroupViewModel)
On your application development phase debug logs can be enabled or disabled by following call, by default debug level logging is enabled
DsegmentifyManager.logStatus(isVisible: false)