📘

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.


Documentation

The entire iOS Library documentation is available as well.

Client setup

  1. Download our iOS client and add it to your app.
  2. 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:

-(void)testGravityClient{
GravityClient *client = [[GravityClient alloc] initWithURL:@"https://<customerUserName>-<SERVERLOCATION>.gravityrd-services.com/grrec-<customerUserName>-war/WebshopServlet'" username:@"customerUserName" password:@"customerPassword"];
  
#Make a request
[client trackLocation];
[client setUserId:@"userId"];
[client setDelegate:self];
[client getItemRecommendations:@"ITEM_PAGE" limit:10 resultNameValues:@[@"Title", @"description"] attributes:@[[GravityNameValue nameValueWithName:@"currentItemId" value:@"1000301"]]];
  
  
#Add REC_CLICK event to the recommended items
GravityEvent *event = [[GravityEvent alloc] init];
    event.itemId = itemId;
    event.userId = userId;
    event.cookieId = cookieId;
    event.type = @"REC_CLICK";
    event.nameValues = [[NSMutableArray alloc] initWithObjects:
                        [[GravityNameValue alloc] initWithName:@"unitPrice" value:@"199.9"],
                        [[GravityNameValue alloc] initWithName:@"quantity" value:@"1"],
                        [[GravityNameValue alloc] initWithName:@"orderId" value:@"order-0123"], nil];
[client addEvent:event];

The GravityClient object will start location tracking as soon as it is created.
If you want to use the client without location tracking, you can initialize the object with one of the following constructors

initNoLocationTracking;
initWithURLNoLocationTracking:(NSString *)url;
initWithURLNoLocationTracking:(NSString *)url username:(NSString *)username password:(NSString *)password;

📘

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];

Add events

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:

Field nameDescriptionAPI
userIdThe identifier of the user whose action is logged.more
typeThe type of the event specifies the user action which triggered the event.more
timeThe UNIX timestamp of the event in seconds.more
recommendationIdThis 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
itemIdThe identifier of the item related to theusersaction.more
cookieIdTo 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.more

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:

#Add REC_CLICK event to the recommended items
GravityEvent *event = [[GravityEvent alloc] init];
    event.itemId = itemId;
    event.userId = userId;
    event.cookieId = cookieId;
    event.type = @"REC_CLICK";
    event.nameValues = [[NSMutableArray alloc] initWithObjects:
                        [[GravityNameValue alloc] initWithName:@"recommendationId" value:@"ASsadas3q232432-32432432-34"],nil];
[client addEvent:event];

📘

What is recommendationId?

recId is for passing the id of the recommendation which resulted that the users action (e.g. the user bought a book from the 'Recommended for you' box).

📘

Test the event was added successfully

Testing if everything were saved: It is possible to check if all the events and its name-values were saved. You only have to log in into the DASH and you can browse the stored information on the event page.

Add items

All recommendable entities are considered items in the system.

Add or update items

Below it's how to add/update items on a source code level via iOS lib calls. You should also set all of the item parameters in case of an update.

GravityItem *item = [[GravityItem alloc] init];
   item.Id = @"sampleItem2";
   item.title = @"Sample product 2";
   item.type = @"sampleItemType2";
   item.hidden = false;
   item.nameValues = [[NSMutableArray alloc] initWithObjects:
                      [[GravityNameValue alloc] initWithName:@"description" value:@"This is only a sample product 2."],
                      [[GravityNameValue alloc] initWithName:@"categoryPath" value:@"mainCategory/subCategory"],
                      [[GravityNameValue alloc] initWithName:@"url" value:@"http://example.com/sampleItem2"],
                      [[GravityNameValue alloc] initWithName:@"imageUrl" value:@"http://example.com/sampleItem2Image.jpg"], nil];
   [client updateItem:item];

Delete items

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.

GravityItem *item = [[GravityItem alloc] init];
    item.Id = @"sampleItem2";
    item.title = @"Sample product 2";
    item.type = @"sampleItemType2";
    item.hidden = true;     //please set hidden parameter true, if you do not want to get back the item in any recommendation
    item.nameValues = [[NSMutableArray alloc] initWithObjects:
                       [[GravityNameValue alloc] initWithName:@"description" value:@"This is only a sample product 2."],
                       [[GravityNameValue alloc] initWithName:@"categoryPath" value:@"mainCategory/subCategory"],
                       [[GravityNameValue alloc] initWithName:@"url" value:@"http://example.com/sampleItem2"],
                       [[GravityNameValue alloc] initWithName:@"imageUrl" value:@"http://example.com/sampleItem2Image.jpg"], nil];
    [client updateItem:item];

Add users

Users are to who the recommendation is made too.

Add or update users

Here follow how to achieve this in Objective-C source code:

GravityUser *user = [[GravityUser alloc] init];
    user.userId = @"testUser";
    user.hidden = false;
    user.nameValues = [[NSArray alloc] initWithObjects:
                       [[GravityNameValue alloc] initWithName:@"name" value:@"Test"],
                       [[GravityNameValue alloc] initWithName:@"gender" value:@"male"],
                       [[GravityNameValue alloc] initWithName:@"country" value:@"HUN"], nil];
    [client addUser:user];

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"]]
  1. If you do not want to add more parameters to the request, please use the following:
[client getItemRecommendations:@"SCENARIO_NAME" limit:10 resultNameValues:@[@"title"]];
  1. If you should add more parameters to the request, please use this version of the call:
[client getItemRecommendations:@"SCENARIO_NAME" limit:20 resultNameValues:@[@"title",@"description",@"price",@"category"] attributes:@[[GravityNameValue nameValueWithName:@"currentItemId" value:@"1000157509"]]];

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:

NSArray *resultNameValues = [[NSArray alloc] initWithObjects:@"title", @"type", nil];
 
 
GravityRecommendationContext *scenario1 = [[GravityRecommendationContext alloc] init];
    scenario1.scenarioId = @"ITEM_PAGE_TOP";
    scenario1.limit = 4;
    scenario1.nameValues = [[NSArray alloc] initWithObjects: [[GravityNameValue alloc] initWithName:@"itemOnPage" value:@"1000166667"], nil];
    scenario1.resultNameValues = [[NSArray alloc] initWithArray:resultNameValues];
 
 
GravityRecommendationContext *scenario2 = [[GravityRecommendationContext alloc] init];
    scenario2.scenarioId = @"ITEM_PAGE_BOTTOM";
    scenario2.limit = 4;
    scenario2.resultNameValues = [[NSArray alloc] initWithArray:resultNameValues];
    scenario1.nameValues = [[NSArray alloc] initWithObjects: [[GravityNameValue alloc] initWithName:@"itemOnPage" value:@"1000166667"], nil];
     
NSArray *bulkItems = [[NSArray alloc] initWithObjects:scenario1, scenario2, nil];
[gc getItemRecommendationsBulk:bulkItems];

Scenario information

You can query the list of available scenarios (with their properties) with the following function call:

[client getAllScenarioInfo];

This will return a list of GravityScenario objects. The scenario id will be the content of the apiName object.