iOS SDK Readme

This SDK enables easy communication with Engine API and can be used by any application which is built using iOS.

Using this SDK you can report events and get actions from Engine API.

Installation

pod 'monetate-ios-sdk'
pod 'monetate-ios-sdk', :git => 'https://github.com/monetate/kibo-ios-sdk-cocoapod.git', :branch => 'main'

Using the SDK

Below are the details about methods and classes with their description and usage.

Personalization Class

  • Personalization in the main class. Before reporting any event, you must first create an instance of the Personalization class.
  • This class takes three parameters as arguments: account, user, and contextMap. account and contextMap are objects, and details of those are below.
Personalization.setup(
  account: Account(instance: "p", domain: "localhost.org", name: "a-701b337c", shortname: "localhost"),
  user: User(kiboId: "auto"),
  contextMap: setupContextMap()
)
 
let user = User(kiboId: "", deviceId: "", customerId: "")

user takes the following parameters:

  • Kibo ID (also know as Monetate ID): (provided by end user, if not generated internally when set as "auto")
  • Device ID: device id (provided by end user)
  • Customer ID: customer id (provided by end user)

When you are creating the instance of user, consider the following:

  • In the user details you must have a deviceId or KiboId. customerId is optional.
  • All parameters are strings.
  • If both deviceId and kiboId is present, the object will default to using deviceId.
  • If both deviceId and KiboId are not present, then message must include deviceId or kiboId to be logged. 
    • deviceId: pass a hardcoded deviceId as a string
    • customerID: pass a hardcoded customerID as a string
    • kiboId/monetateId: pass "auto" to automatically generate and assign a kiboID/monetateId. Alternatively, you can pass a hardcoded kiboId or monetateId as a string.

Account Class

let account = Account(instance: "p", domain: "localhost.org", name: "a-701b337c", shortname: "localhost")

Account contains the following objects as parameters:

  • domain
  • name
  • Instance
  • shortname

These are account details, and are all required parameters.

ContextMap Class

func setupContextMap () -> ContextMap {
   return ContextMap(
      userAgent: UserAgent(auto: true),
      ipAddress: IPAddress(ipAddress: "192.168.0.1"),
      coordinates: Coordinates.init(auto: true),
      screenSize: ScreenSize(auto: true),
      
cart: {() in
         let promise = Promise<Cart, Error>()
         promise.succeed(value: Cart(cartLines: [CartLine(sku: "SKU-111", pid: "PID-111", quantity: 2, currency: "USD", value: "460"), CartLine(sku: "SKU-222", pid: "PID-222", quantity: 4, currency: "USD", value: "560")]))
         return promise.future
   },
      purchase: {
         let promise = Promise<Purchase, Error>()
         let p = Purchase(account: "account-232", domain: "tem.dom.main", instance: "temp", purchaseId: "pur-23232", purchaseLines: [
            PurchaseLine(sku: "SKU-123", pid: "Prod-1232", quantity: 2, currency: "USD", value: "2.99")
         ])
         promise.succeed(value: p)
         return promise.future
   },
      productDetailView: { () in
         let promise = Promise<ProductDetailView, Error>()
         let result = ProductDetailView.init(products: [
            Product.init(productId: "PROD-9898", sku: "SKU-9898"),
            Product.init(productId: "PROD-8989", sku: "SKU-8989")
         ])
         promise.succeed(value: result)
         return promise.future
   },
      productThumbnailView: {
         let promise = Promise<ProductThumbnailView, Error>()
         let result =     ProductThumbnailView.init(products: [""])
         promise.succeed(value: result)
         return promise.future
   },
      pageView: { () in
         let promise = Promise<PageView, Error>()
         let r = PageView(pageType: "profile", path: "/profile", url: "http:/home", categories: nil, breadcrumbs: nil)
         promise.succeed(value: r)
         return promise.future
   },
      metadata: { () in
         let promise = Promise<Metadata, Error>()
         let r = Metadata(metadata: JSONValue(dictionaryLiteral: ("Key1", "Val1"), ("Key2", "Val2")))
         promise.succeed(value: r)
         return promise.future
   },
      customVariables: { () in
         let promise = Promise<CustomVariables, Error>()
         let r = CustomVariables(customVariables: [
            CustomVariablesModel(variable: "TempVariable", value: JSONValue.init(dictionaryLiteral: ("String", "JSONValue"))),
            CustomVariablesModel(variable: "KEY", value: JSONValue.init(dictionaryLiteral: ("String", "JSONValue")))
         ])
         promise.succeed(value: r)
         return promise.future
   })
   
}

ContextMap is a basic storage structure where you can keep events data. If event reports are missing any data, they will refer to the ContextMap to try to fill in this missing data. You can set eventData in the ContextMap to simplify future event reports. For example, you can report an IpAddress event and store that data into the ContextMap object for easy access in future use.

Setting eventData is optional.

Reporting Events

Reporting events is done with the following methods.

Report

public func report (context:ContextEnum, event: MEvent?)

This method is used to report events. It takes three parameters as arguments: the event type as context, the event data, and a kiboPersonalization to perform a callback operation. This method is a void type, and returns nothing.

Example usage:

let address =  Ipaddress(ipAddress:key:"127.0.0.0");
Personalization.shared.report(context: .IpAddress, event: address)

GetActions

public func getActions (context:ContextEnum, requestId: String, event: MEvent?) -> Future<APIResponse, Error>

getActions is used to report events along with the requestID, and returns JSON data as a response. You can also call this method with just the requestID to get JSON data for parsing purposes.

JSON data contains various data about the events that can be parsed and used for various purposes.

Example usage:

Personalization.shared.getActions(context: .IpAddress, requestId: requestId, event: IPAddress(ipAddress: key)).on(success: {(res) in self.handleAction(res: res)})

Flush

public func flush()

This method sends all queued data immediately.

Example usage:

Personalization.setup(
  account: Account(instance: "p", domain: "localhost.org", name: "a-701b337c", shortname: "localhost"),
  user: User(kiboId: "auto"),
  contextMap: setupContextMap()
)


Personalization.shared.report(context: .IpAddress, event: IPAddress(ipAddress:key))


Personalization.shared.flush();

Event Reporting Example

The following code is an example use case of the report and getAction methods for various events:

Personalization.setup(
  account: Account(instance: "p", domain: "localhost.org", name: "a-701b337c", shortname: "localhost"),
  user: User(kiboId: "auto"),
  contextMap: setupContextMap()
)

UserAgent:
  Personalization.shared.report(context: .UserAgent, event: UserAgent(key))

Personalization.shared.getActions(context: .UserAgent, requestId: requestId, event: UserAgent(key)).on(success:
{
  (res) in
  self.handleAction(res: res)
})

IpAddress:
  Personalization.shared.report(context: .IpAddress, event: IPAddress(ipAddress: key))
Personalization.shared.getActions(context: .IpAddress, requestId: requestId, event: IPAddress(ipAddress: key)).on(success:
{
  (res) in
  self.handleAction(res: res)
})
ScreenSize:
  Personalization.shared.report(context: .ScreenSize, event: ScreenSize(height: Int(val) !, width: Int(key) !))

Personalization.shared.getActions(context: .ScreenSize, requestId: requestId, event: ScreenSize(height: Int(val) !, width: Int(key) !)).on(success:
{
  (res) in
  self.handleAction(res: res)
})

Coordinates:
  Personalization.shared.report(context: .Coordinates, event: Coordinates(latitude: key, longitude: val))

Personalization.shared.getActions(context: .Coordinates, requestId: requestId, event: Coordinates(latitude: key, longitude: val)).on
{
  (res) in
  self.handleAction(res: res)
}

Cart:
  Personalization.shared.report(context: .Cart, event: Cart(cartLines: [CartLine(sku: "sku-11", pid: key, quantity: 2, currency: "USD", value: val)]))

Personalization.shared.getActions(context: .Cart, requestId: requestId, event: Cart(cartLines: [CartLine(sku: "sku-11", pid: key, quantity: 2, currency: "USD", value: val)])).on
{
  (res) in
  self.handleAction(res: res)
}

ProductDetailView:
  Personalization.shared.report(context: .ProductDetailView, event: ProductDetailView(products: [Product(productId: key, sku: val)]))

Personalization.shared.getActions(context: .ProductDetailView, requestId: requestId, event: ProductDetailView(products: [Product(productId: key, sku: val)])).on(success:
{
  (res) in
  print("response", res.status, res.data ? .toString)
  self.handleAction(res: res)
})
Purchase:
  Personalization.shared.report(context: .Purchase, event: Purchase(account: "Flipkart", domain: "www.flipkart.com", instance: "instance-198", purchaseId: "PID-23892", purchaseLines: [PurchaseLine(sku: "sku-321", pid: key, quantity: 2, currency: "USD", value: val)]))

Personalization.shared.getActions(context: .Purchase, requestId: requestId, event: Purchase(account: "Flipkart", domain: "www.flipkart.com", instance: "instance-198", purchaseId: "PID-23892", purchaseLines: [PurchaseLine(sku: "sku-321", pid: key, quantity: 2, currency: "USD", value: val)])).on(success:
{
  (res) in
  self.handleAction(res: res)
  print("response", res.status, res.data ? .toString)
})

Metadata:
  Personalization.shared.report(context: .Metadata, event: Metadata(metadata: JSONValue(dictionaryLiteral: (key, JSONValue(stringLiteral: val)))))

Personalization.shared.getActions(context: .Metadata, requestId: requestId, event: Metadata(metadata: JSONValue(dictionaryLiteral: (key, JSONValue(stringLiteral: val))))).on(success:
{
  (res) in
  self.handleAction(res: res)
  print("response", res.status, res.data ? .toString)
})

CustomVariables
Personalization.shared.report(context: .CustomVariables, event: CustomVariables(customVariables: [CustomVariablesModel(variable: key, value: JSONValue(stringLiteral: val))]))

Personalization.shared.getActions(context: .CustomVariables, requestId: requestId, event: CustomVariables(customVariables: [CustomVariablesModel(variable: key, value: JSONValue(stringLiteral: val))])).on(success:
{
  (res) in
  self.handleAction(res: res)
  print("response", res.status, res.data ? .toString)
})

PageEvents:
  Personalization.shared.report(context: .PageEvents, event: PageEvents(pageEvents: ["HomeController"]))
Personalization.shared.getActions(context: .PageEvents, requestId: requestId, event:PageEvents(pageEvents: ["HomeController"])).on { (res) in
  self.handleAction(res: res)
  print("response", res.status, res.data?.toString)
}


Related Articles

How would you rate this article?
Thank you for your feedback!