IMPORTANT NOTE: Please keep in mind that trough network error or through other unexpected issues may an error occurs while getting the recommendation from or while adding events to the recommendation engine. This error can cause a program exception which always has to be handled in the proper way. Without handling the possible exceptions your code may terminate at an unexpected place and your site will operate abnormally. Even if you do not get a valid list of recommended items as a result of the recommendation request take care about hiding the recommendation widget or filling it with relevant items. Please ensure the safe error handling. Gravity does not take any responsibility for any damages caused by the lack or deficiency of error handling.
Each website/application has their own kind of items, with their own metadata and their own type of events. Please consult with your integration engineer about what applies to your case, and tailor the parameters described here as such.
The entire iOS Library documentation is available as well.
- Download our iOS client and add it to your app.
- The recommendation engine accessed by a GravityClient object. For the the client configuration parameters like the URL of the recommendation engine, the username and password should be set by GravityClient object like below.
To create a GravityClient object and a request would look like the following:
cookieId for every event and recommendation
You should add cookieId to every events and every item recommendation request in every case, furthermore if we know the userId, we will pass the userId next to cookieId. In case of mobile application (iOS and Android) we use deviceId for cookieId field, because it is a unique identifier. It comes from self.cookieId = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
Each website has its own subset of valid event types. Here's are the recommended lists of event types that our system accepts. Event types that you must integrate are part of the integration document. Each event have some data fields which usually has to be filled with the appropriate value. Event fields are the following:
|The type of the event specifies the user action which triggered the event.||more|
|userId||The identifier of the user whose action is logged.||more|
|itemId||The identifier of the item related to theusersaction.||more|
|time||The UNIX timestamp of the event in seconds.||more|
|recommendationId||This has to be filled if the action is related to a recommendation got from the recommendation engine. The recommendation id is always passedalongthe list of recommended items.||more|
|cookieId||To be able to identify guest users or registered users who are not logged in we always require to set the cookie id for every event.|
Additional informations are stored in name-values. The set of name-values are not predefined we only have a list of recommended name-values for the various event types but new name-values can be defined by our customers as well. On a source code level the call of add event would look like the following:
What is recommendationId?
Test the event was added successfully
Deletion can be also done by using addItems function. The only caveat is that you need to set the hidden parameter to true. You should also set all of the item parameters in case of a deletion, unless instructed otherwise by the integration engineer.
Users are to who the recommendation is made too.
Add or update users
Get item recommendation
Get single item recommendation
You should call the getItemRecommendations to get recommendation for a scenario:
- in the first parameter you should set the proper scenario name
- the second parameter is the limit (how many items want to get back)
- Please enumerate all the metadatas in the resultNameValues field to get back them.
- You have to add all the information to the attributes argument as a name-value pair.
- for example: attributes:@[[GravityNameValue nameValueWithName:@"currentItemId" value:@"100157509"]]
If you do not want to add more parameters to the request, please use the following:
If you should add more parameters to the request, please use this version of the call:
Get bulk item recommendation
Avoid duplactions on the same page
The bulk item recommendation method will help us to avoid the duplicated items between two or more scenarios which are on the same page. It can be used if more than one recommendation box is appered on one page. By using this we can filter out the result of the first recommendation from the second recommendation result.
You should call the getItemRecommendationsBulk to get recommendation for a scenario:
You can query the list of available scenarios (with their properties) with the following function call:
This will return a list of GravityScenario objects. The scenario id will be the content of the apiName object.