This SDK enables easy communication with Engine API and can be used by any application which is built using Android.
Installation
Refer to Android SDK Implementation Guide for installation instructions.
Using the SDK
Below are the details about methods and classes with their description and usage.
Kibo Personalization Class
KiboPersonalization
is the main class, and creates the object used for all SDK activities. You can create an instance of this class with the following code:
sdkInstace = new KiboPersonalization(account, user, contextMap);
The parameters are three separate object classes and are required parameters.
Account
This object contains information about the account. You can create an instance of this class with the following code:
Account account = new Account(String domain, String accountName, String instance, String shortName);
You must provide values for all parameters.
User
This object contains information about the user. You can create an instance of this class with the following code:
User user = new User (String customerID, String deviceId, String kiboId);
Either kiboId
or deviceId
is required in calls. If both are present, the application will use deviceId
. You can specify "auto" for kiboId
to have the SDK automatically generate an ID to use.
customerId
is optional.
Context Map
This object contains optional contextual data such as app/page data layer, state, or other variables. This data is used for reported events that do not include the specified data. For instance, if an event report does not specify an IP address, the Engine API uses the IP address data stored in the context map.
You can create an instance of this class with the following code:
ContextMap contextMap = new ContextMap();
This object includes a set method to store data. For example, if you wanted to store an IP address in the context map, you can use the following code:
contextMap.setIpAddress("127.0.0.0");
The object contains the following variables that can be used to store data:
coordinates
screenSize
ipAddress
userAgent
Cart
PageView
Methods
The following methods are available to use.
Report
This method is used to report events. Pass the event type as context
and the event data as events
. The naming convention of events for this is CommonConstants.<event name>
, where <event name>
is the name of the event to pass. The complete list of event names available to use is listed in the Event Type Constants section.
public void report(String context, Object events)
For example, if you want to report an IP address event, you can use the following code:
IpAddress address = new IpAddress(); address.setIpAddress("127.0.0.0."); kiboPersonalization.report(CommonConstants.ContextIpaddress, address);
Get Action
This method is used to record events and request decisions.
public void getActions(String requestId, String context, Object events)
Parameters:
requestId
is the request identifier tying the response back to an event.context
is the name of the event. This parameter is optional. If you use this parameter, includecontextMap
data relevant to the requirements for the event.eventData
is the data associated with the events. This parameter is optional.
This method returns an object containing the JSON of the event.
Flush
This method sends all queued data immediately. Use this method if you want to report an event immediately.
public String flush()
This method might throw the following exceptions that you might need to handle:
InterruptedException
ExecutionException
TimeoutException
Example usage:
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); IpAddress address = new IpAddress(); address.setIpAddress("127.0.0.0."); kiboPersonalization.report(CommonConstants.ContextIpaddress, address); kiboPersonalization.flush();
Set Customer ID
This method sets or updates the customerId
of the User object.
public void setCustomerId(String customerId)
Event Type Constants
Event types are then referenced by the name CommonConstants.eventName
. The available event names are:
- RecordImpressions
- RecordPageEvents
- RecordRecClicks
- RecordRecImpressions
- ContextCustomVariables
- ContextUserAgent
- ContextPageView
- ContextProductView
- ContextCart
- ContextPurchase
- ContextMetadata
- ContextProductDetailView
- ContextProductThumbnailView
- ContextReferrer
- ContextCoordinates
- ContextScreenSize
- ContextClosedSession
Event Examples
The following code samples demonstrate how you can use the SDK for each possible event.
ProductViewEvent
Account account = new Account("localhost.org", "a-701b337c", "p", "localhost"); User user = new User(); user.setCustomerId(null); user.setDeviceId(null); user.setKiboId("auto"); ContextMap contextMap = new ContextMap(); KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); ProductView productView = new ProductView(); productView.setProducts(new String[] { "product1", "product2" }); // Passing raw data while reporting event (one way of reporting data) kiboPersonalization.report(CommonConstants.ContextProductView, productView); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextProductView, new ProductViewFunctionReference() { @Override public ProductView getProductView() { // Implement the code to get the ProductView details, create the instance of ProductView class as shown below, set the data to it and then return the Productview object ProductView productView = new ProductView(); productView.setProducts(new String[] { "product1", "product2" }); return productView; } });
ReferrerEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); Referrer referrer = new Referrer(); referrer.setReferrer("test.com"); // Passing raw data while reporting (one way of reporting data) kiboPersonalization.report(CommonConstants.ContextReferrer, referrer); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextReferrer, new ReferrerFunctionReference() { @Override public Referrer getReferrer() { // Implement the code to get the Referrer details , create the instance of Referrer class as shown below , set the data to it and then return the Referrer object Referrer referrer = new Referrer(); referrer.setReferrer("test.com"); return referrer; } });
CoordinatesEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); Coordinates coordinates = new Coordinates(); coordinates.setLatitude("1212"); coordinates.setLongitude("2323"); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextCoordinates, coordinates); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextCoordinates, new CoordinatesFunctionReference() { @Override public Coordinates getLocation() { // Implement the code to get the coordinates, and return it accordingly by setting those to coordinates class as show below Coordinates coordinates = new Coordinates(); coordinates.setLatitude("1212"); coordinates.setLongitude("3232"); return coordinates; } });
ScreenSizeEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); ScreenSize screenSize = new ScreenSize(); screenSize.setHeight(1211); screenSize.setWidth(2323); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextScreenSize, screenSize); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextScreenSize, new ScreenSizeFunctionReference() { @Override public ScreenSize getScreenSize() { // Implement the code to get the ScreenSize details , create the instance of ScreenSize class as shown below, set the data to it and then return ScreenSize object ScreenSize screenSize = new ScreenSize(); screenSize.setHeight(1211); screenSize.setWidth(2323); return screenSize; } });
UserAgentEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); kiboPersonalization.report(CommonConstants.ContextUserAgent, new UserAgent("test_agent")); KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); public DeviceDetails getData() { DeviceDetails deviceDetails = new DeviceDetails(); deviceDetails.setDevice(Build.DEVICE); deviceDetails.setModel(Build.MODEL); deviceDetails.setProductName(Build.BRAND); deviceDetails.setOsVersion(System.getProperty("os.version")); deviceDetails.setOsApiLevel(Build.VERSION.RELEASE + "(" + Build.VERSION.SDK_INT + ")"); return deviceDetails; } DeviceDetails details = getData(); String data = kiboPersonalization.refactorDeviceDetails(details); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextUserAgent, new UserAgent(data)); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextUserAgent, new UserAgentFunctionReference() { @Override public UserAgent getUserAgent() { DeviceDetails details = getData(); String data = kiboPersonalization.refactorDeviceDetails(details); return new UserAgent(data); } });
IPAddressEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); IpAddress address = new IpAddress(); address.setIpAddress("127.0.0.0."); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextIpAddress, address); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextIpAddress, new IpAddressFunctionReference() { @Override public IpAddress getIpAddress() { // Implement the code to get the IpAddress details, create the instance of IpAddress class as shown below, set the data to it and then return IpAddress object IpAddress address = new IpAddress(); address.setIpAddress("127.0.0.0."); return address; } });
RecordImpressionEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); Impressions impressions = new Impressions(); impressions.setimpressionIds(new String[] { "testimpressionsId1", "testimpressionsId2" }); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.RecordImpressions, impressions); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.RecordImpressions, new ImpressionsFunctionReference() { @Override public Impressions getImpressions() { // Implement the code to get the Impressions details, create the instance of Impressions class as shown below, set the data to it and then return Impressions object Impressions impressions = new Impressions(); impressions.setimpressionIds(new String[] { "impressionsId1", "impressionsId2" }); return impressions; } });
CartEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); CartLine cartLine = new CartLine(); cartLine.setCurrency("INR"); cartLine.setPid("PID"); cartLine.setQuantity(2); cartLine.setSku("SKU"); cartLine.setUnitPrice("000"); cartLine.setValue("11"); CartLine cartLine2 = new CartLine(); cartLine2.setCurrency("USA"); cartLine2.setPid("PID"); cartLine2.setQuantity(2); cartLine2.setSku("SKU"); cartLine2.setUnitPrice("9999"); cartLine2.setValue("111"); Cart cart = new Cart(); cart.setCartLines(new CartLine[] { cartLine, cartLine2 }); /* Passing raw data while reporting (one of of reporting data) */ kiboPersonalization.report(CommonConstants.ContextCart, cart); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextCart, new CartFunctionReference() { @Override public Cart getCart() { // Implement the code to get the Cart details, create the instance of Cart class as shown below, set the data to it and then return Cart object CartLine cartLine = new CartLine(); cartLine.setCurrency("INR"); cartLine.setPid("PID"); cartLine.setQuantity(2); cartLine.setSku("SKU"); cartLine.setUnitPrice("000"); cartLine.setValue("11"); Cart cart = new Cart(); cart.setCartLines(new CartLine[] { cartLine }); return cart; } }, kiboPersonalization);
MetadataEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); MetaData data = new MetaData(); data.setMetadata(new Language("INR")); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextMetadata, data); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextMetadata, new MetadataFunctionReference() { @Override public MetaData getMetaData() { // Implement the code to get the MetaData details, create the instance of MetaData class as shown below, set the data to it and then return MetaData object MetaData data = new MetaData(); data.setMetadata(new Language("INR")); return data; } });
EndcapClicksDataEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); Products products_1 = new Products(); products_1.setProductId("PID_1"); products_1.setSku("SKU_1"); EndcapClicks endcapClicks = new EndcapClicks(); endcapClicks.setActionId("1234567"); endcapClicks.setProducts(new Products[] { products_1 }); EndcapClicksData endcapClicksData = new EndcapClicksData(); endcapClicksData.setEndcapClicks(new EndcapClicks[] { endcapClicks, endcapClicks_2 }); // Passing raw data while reporting (one way of reporting data) kiboPersonalization.report(CommonConstants.RecordEndcapClicks, endcapClicksData2); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.RecordEndcapClicks, new EndcapClicksFunctionReference() { @Override public EndcapClicksData getEndcapClicks() { // Implement the code to get the EndcapClicksData details, create the instance of EndcapClicksData class as shown below, set the data to it and then return EndcapClicksData object Products products_1 = new Products(); products_1.setProductId("PID_1"); products_1.setSku("SKU_1"); EndcapClicks endcapClicks = new EndcapClicks(); endcapClicks.setActionId("1234567"); endcapClicks.setProducts(new Products[] { products_1 }); // Second product data below Products products_2 = new Products(); products_2.setProductId("PID_2"); products_2.setSku("SKU_2"); Products products_3 = new Products(); products_3.setProductId("PID_3"); products_3.setSku("SKU_3"); EndcapClicks endcapClicks_2 = new EndcapClicks(); endcapClicks_2.setActionId("123456789"); endcapClicks_2.setProducts(new Products[] { products_2, products_3 }); EndcapClicksData endcapClicksData = new EndcapClicksData(); endcapClicksData.setEndcapClicks(new EndcapClicks[] { endcapClicks, endcapClicks_2 }); return endcapClicksData; } });
PageViewEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); PageView pageView = new PageView(); pageView.setBreadcrumbs(new String[] { "breadcrums_1", "breadcrums_2", "breadcrums_3" }); pageView.setCategories(new String[] { "category_1", "category_2" }); pageView.setPageType("home_page"); pageView.setUrl("NA"); // Passing raw data while reporting (one way of reporting data) kiboPersonalization.report(CommonConstants.ContextPageView, pageView); // Passing function as parameter while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextPageView, new PageViewFunctionReference() { @Override public PageView getPageView() { // Implement the code to get the PageView details, create the instance of PageView class as shown below, set the data to it and then return PageView object PageView pageView = new PageView(); pageView.setBreadcrumbs(new String[] { "breadcrums_1", "breadcrums_2", "breadcrums_3" }); pageView.setCategories(new String[] { "category_1", "category_2" }); pageView.setPageType("home_page"); pageView.setUrl("NA"); return pageView; } });
EndcapImpressionsDataEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); Products products = new Products(); products.setProductId("PID"); products.setSku("SKU"); Products products_22 = new Products(); products_22.setProductId("PID_2"); products_22.setSku("SKU_2"); EndcapImpressions endcapImpressions = new EndcapImpressions(); endcapImpressions.setActionId("1234567"); endcapImpressions.setProducts(new Products[] { products, products_22 }); Products products_44 = new Products(); products_44.setProductId("PID_4"); products_44.setSku("SKU_4"); Products products_55 = new Products(); products_55.setProductId("PID_5"); products_55.setSku("SKU_5"); EndcapImpressions endcapImpressions_2 = new EndcapImpressions(); endcapImpressions_2.setActionId("123456709"); endcapImpressions_2.setProducts(new Products[] { products_44, products_55 }); EndcapImpressionsData endcapImpressionsData = new EndcapImpressionsData(); endcapImpressionsData.setEndcapImpressions(new EndcapImpressions[] { endcapImpressions, endcapImpressions_2 }); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.RecordEndcapImpressions, endcapImpressionsData); // Passing data as function reference while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.RecordEndcapImpressions, new EndcapImpressionsFunctionReference() { @Override public EndcapImpressionsData getEndcapImpressions() { // Implement the code to get the EndcapImpressionsData details, create the instance of EndcapImpressionsData class as shown below, set the data to it and then return EndcapImpressionsData object Products products = new Products(); products.setProductId("PID_7"); products.setSku("SKU_7"); EndcapImpressions endcapImpressions = new EndcapImpressions(); endcapImpressions.setActionId("12345670111"); endcapImpressions.setProducts(new Products[] { products }); EndcapImpressionsData endcapImpressionsData2 = new EndcapImpressionsData(); endcapImpressionsData2.setEndcapImpressions(new EndcapImpression[ { endcapImpressions }); return endcapImpressionsData; } });
PageEventsEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); PageEvents pageEvents = new PageEvents(); pageEvents.setPageEvents(new String[] { "pageEvent_1", "pageEvent_2" }); /* Passing Raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.RecordPageEvents, pageEvents); // Passing data as function reference while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.RecordPageEvents, new PageEventsFunctionReference() { @Override public PageEvents getPageEvents() { // Implement the code to get the PageEvents details, create the instance of PageEvents class as shown below, set the data to it and then return PageEvents object PageEvents pageEvents = new PageEvents(); pageEvents.setPageEvents(new String[] { "pageEvent_1", "pageEvent_2" }); return pageEvents; } });
CustomVariablesEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); ContextVariable contextVariable = new ContextVariable(); contextVariable.setValue("key"); contextVariable.setVariable("value"); CustomVariables customVariables = new CustomVariables(); customVariables.setCustomVariables(new ContextVariable[] { contextVariable }); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextCustomVariables, customVariables); // Passing data as function reference while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextCustomVariables, new CustomVariablesFunctionReference() { @Override public CustomVariables getCustomVariables() { // Implement the code to get the CustomVariables details, create the instance of CustomVariables class as shown below, set the data to it and then return CustomVariables object ContextVariable contextVariable = new ContextVariable(); contextVariable.setValue("key"); contextVariable.setVariable("value"); CustomVariables customVariables = new CustomVariables(); customVariables.setCustomVariables(new ContextVariable[] { contextVariable }); return customVariables; } });
ProductDetailViewEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); Products products_111 = new Products(); products_111.setProductId("PID_111"); products_111.setSku("SKU_111"); Products products_222 = new Products(); products_222.setProductId("PID_222"); products_222.setSku("SKU_222"); ProductDetailView detailView = new ProductDetailView(); detailView.setProducts(new Products[] { products_111, products_1 }); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextProductDetailView, detailView); // Passing data as function reference while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextProductDetailView, new ProductDetailViewFunctionReference() { @Override public ProductDetailView getProductDetailView() { // Implement the code to get the ProductDetailView details, create the instance of ProductDetailView class as shown below, set the data to it and then return ProductDetailView object Products products = new Products(); products.setProductId("PID_111"); products.setSku("SKU_111"); ProductDetailView detailView = new ProductDetailView(); detailView_2.setProducts(new Products[] { products }); return detailView; } });
ProductThumbnailViewEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); ProductThumbnailView productThumbnailView = new ProductThumbnailView(); productThumbnailView.setProducts(new String[] { "product1", "product2", "product3" }); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextProductThumbnailView, productThumbnailView); // Passing data as function reference while reporting (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextProductThumbnailView, new ProductThumbnailViewFunctionReference() { @Override public ProductThumbnailView getProductThumbnailView() { // Implement the code to get the ProductThumbnailView details, create the instance of ProductThumbnailView class as shown below, set the data to it and then return ProductThumbnailView object ProductThumbnailView productThumbnailView = new ProductThumbnailView(); productThumbnailView.setProducts(new String[] { "product1", "product2", "product3" }); return productThumbnailView; } });
ClosedSessionEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); ClosedSession closedSession = new ClosedSession(); closedSession.setClosedSession(new com.kibo.personalization.androidsdk.model.objects.ClosedSession("test_id")); closedSession.setVersion("test_version"); /* Passing raw data while reporting (one way of reporting data) */ kiboPersonalization.report(CommonConstants.ContextClosedSession, closedSession); // Passing data as function reference while reporting - (other way of reporting data, its used in case if getting the event data may take time.) kiboPersonalization.report(CommonConstants.ContextClosedSession, new ClosedSessiFunctionReference() { @Override public ClosedSession getClosedSession() { // Implement the code to get the ClosedSession details, create the instance of ClosedSession class as shown below, set the data to it and then return ClosedSession object ClosedSession closedSession = new ClosedSession(); closedSession.setClosedSession(newcom.kibo.personalization.androidsdk.model.objects.ClosedSession("test_id")); closedSession.setVersion("test_version"); return null; } });
PurchaseEvent
KiboPersonalization kiboPersonalization = new KiboPersonalization(user, account, contextMap); PurchaseLine line = new PurchaseLine(); line.setCurrency("INR"); line.setPid("PID"); line.setQuantity(2); line.setSku("SKU"); line.setValue("12.00"); Purchase purchase = new Purchase(); purchase.setPurchaseLines(new PurchaseLine[] { line }); purchase.setAccount("tes_account"); purchase.setDomain("test_domain"); purchase.setInstance("test_instance"); purchase.setPurchaseId("test_purchase_id"); // Passing raw data while reporting kiboPersonalization.report(CommonConstants.ContextPurchase, purchase); // Passing data as function reference while reporting kiboPersonalization.report(CommonConstants.ContextPurchase, new PurchaseFunctionReference() { @Override public Purchase getPurchase() { // Implement the code to get the Purchase details, create the instance of Purchase class as shown below, set the data to it and then return Purchase object PurchaseLine line = new PurchaseLine(); line.setCurrency("INR"); line.setPid("PID"); line.setQuantity(2); line.setSku("SKU"); line.setValue("12.00"); Purchase purchase = new Purchase(); purchase.setPurchaseLines(new PurchaseLine[] { line }); purchase.setAccount("tes_account"); purchase.setDomain("test_domain"); purchase.setInstance("test_instance"); purchase.setPurchaseId("test_purchase_id"); return purchase; } });
DecisionEvent
This event does not need to be created. Pass a requestID
as a string in a call to the getActions
method and the SDK automatically creates a decision event.