Docs

Integrating Recommendations using PHP SDK

The Unbxd PHP SDK lets you easily configure Unbxd APIs in your website and accomplish the 3-step process to integrate Unbxd Recommendations in your eCommerce website.

Prerequisites

Before you start integrating, make sure that you have:
  • An Unbxd Recommendations account
  • Set up your console

Initializing the SDK

You can initialize the SDK by including the Unbxd.php class in your file. Include
'/<path of file> /Unbxd.php';

  • path of file: Specify the path of your file.

After you have created the Unbxd.php class, create an instance of the class.

$unbxd = new Unbxd();

Once the instance of the class is created, configure the clients with your Unbxd credentials.

$unbxd->configure("<Site_Key>" , "<API_key>", "<Secret_Key>");
  • $unbxd->configure: initializes the SDK using Unxbd credentials
  • Site_Key: Your SITE KEY
  • API_Key: Your API KEY
  • Secret_Key: Your SECRET KEY

If your store uses HTTPS protocol, initialize in the following manner:

$unbxd->configure("<Your Site_Key>", "<Your API_Key>", "<Your Secret_Key>", true);
  • true: specifies an HTTPS protocol.

1. Uploading your Feed

Once your console is set up, you can upload your Product Feed.

Learn more about Product Feed.

Full Feed Upload

To replace the existing Product Feed with a new one, or if you are uploading your Product Feed for the first time, you need to make a .push(true) call as shown below:

Format:
$response = 
$unbxd -> getFeedClient() ->addSchema(“fieldname”,new DataType(“datatypename”)) ->addProduct(newFeedProduct(“skuid1”,$attribute1)) ->addProduct(newFeedProduct(“skuid2”,$attribute2)) ->push(true);//response is Feedresponse
  • addSchema: adds a custom field to the schema.
  • fieldname: name of the custom field. Learn about Unbxd schema.
  • datatypename: specify the datatype.
  • addProduct: adds a new product or pid.
  • newFeedProduct: denotes a new product.
  • skuid: SKU ID of the product.
  • $attribute: specifies the fields of a product.
  • push(true): specifies a full feed upload.
Example:
$response = 
$unbxd -> getFeedClient() ->addSchema("color",new DataType("text")) ->addProduct(newFeedProduct("whit2243211",$attribute1)) ->addProduct(newFeedProduct("sku2",$attribute2)) ->push(true);//response is Feedresponse

Learn more about Full Feed Upload.

Incremental Upload

For making incremental updates on your existing Product Feed, you can perform Incremental uploads.

You can perform the following incremental actions:

  • Add
  • Update
  • Delete

Learn more about incremental feed upload.

Adding your products

Once you have successfully initialized the SDK, you can add products to your existing Product feed by making a call as shown below:

Format:
$attribute1 = array("fieldname1"=>"fieldvalue1", "fieldname2"=>"fieldvalue2", "fieldname3"=>"fieldvalue3" , "fieldname4"=>"fieldvalue4");/*for product-1*/
$attribute2 = array("fieldname1"=>"fieldvalue1", "fieldname2"=>"fieldvalue2", "fieldname3"=>"fieldvalue3" , "fieldname4"=>"fieldvalue4");/*for product-2*/
  • array(): adds the comma-separated values as product fields.
Example:

The following lines of code will upload product- 1 and product - 2 to Unbxd's servers.

$attribute1 = array("title"=>"nice shoes", "brand"=>"Adidas", "category"=> "Sports Shoes" , "price" => 1100);/*for product-1*/
$attribute2 = array("title"=>"leather jacket", "brand"=>"Adidas", "category"=> "Jackets" , "price" => 5000);/*for product-2*/

Here, a custom field "color" is added to the existing feed.

price field value must not be enclosed within double quotes.

Response

Once you are done uploading your products, Unbxd server will return a response similar to the one shown below:

$response = 
$unbxd -> getFeedClient() ->addSchema(“color”,new DataType(“text”)) ->addProduct(newFeedProduct(“sku1”,$attribute1)) ->addProduct(newFeedProduct(“sku2”,$attribute2)) ->push(false);
  • .push(false): specifies an incremental upload.
addproduct is the default feed action in a full feed import.

Updating your Products

If you wish to update the existing field values of a product, do the following:

Format:
$new_attribute = array("fieldname1"=>"fieldvalue1", "fieldname2"=>"fieldvalue2", "fieldname3"=>"fieldvalue3" , "fieldname1"=>"fieldvalue1");/*for product-1*/       
  • $new_attribute: specifies newly added field (attribute).
Example:
$new_attribute = array("title"=>"white shirt", "brand"=>"Van Huesen", "color"=>"pearl white" , "fieldname1"=>"fieldvalue1");/*for product-1*/       
Response
$response = $unbxd ->getFeedClient( )->updateProduct(newFeedProduct("sku1”,$new_attribute))->push(false);
  • .updateProduct: updates fields with the new values. Here, the value of the title field of product 1 is replaced with white shirt.
  • Usually, this action is used for updating the quantity field of a product.

    Deleting Products

    To delete a product from your existing product feed, you need to make a delete call. This feed action also allows you to delete multiple products from your Product Feed. You can delete an existing product as shown below:

    Format:
    $response = $unbxd ->getFeedClient()->deleteProduct("skuID")->push(false);//response is Feedresponse
    
    • .deleteProduct(): deletes the product using its SKU Id.

    Configuring Multi-valued Fields

    Custom fields are those fields that are not a part of Unbxd Feature fields. While uploading your feed, you can mark these custom fields to accept multiple values as shown below:

    Format:
    ->addSchema("fieldname",new DataType(“datatypename”), multivalue , autosuggest)
    
    Here,
    Example:
    ->addSchema("color",new DataType(“text”), true , false)
    

    Understanding Feed Response

    Understanding the Feed Response is as important as making an API call. The API response will give you processing status and message about the API request.

    Parameter() Description
    getStatusCode() 200 if success.
    getMessage() Get error message if any.
    getUploadID() ID for the upload request.
    getUnknownSchemaFields()List of fields whose schema was unknown if any.
    getfieldErrors Errors that occurred at a field level. This consists of .getfieldName, .getfieldValue, .getdataType, and .ismultiValued.
    getfieldName() Name of the field.
    getfieldValue()The field value with validation error.
    getdataType()The datatype of the field.
    ismultiValue()Identifies if the field is single valued or multi-valued.
    getErrorCode()Identifies if the field is single valued or multi-valued. True if field is multi-valued.

    2. Integrating Unbxd Analytics

    Once you have successfully uploaded your Product Feed, your next step is to integrate Unbxd Analytics in your store. This can be done in two ways:

    1. HTML metatags.
    2. RESTful APIs.

    Learn more about Unbxd Analytics APIs.

    Integrating Recommendations

    You can integrate Unbxd Recommendations and generate product recommendations for each widget by configuring the UnbxdRecommendation client. This client helps you make recommendation API calls to our servers. In the following sections, you will learn how to configure API calls for each recommendation widget:

    It is highly recommended that you avoid integrating the Viewed also Viewed and Bought also Bought widget on the same PDP (Product Detail Page). This would prevent the widgets from showing duplicate products in the widgets. This scenario may arise right after integrating the widgets, due to the lack of analytics data.

    Recently Viewed

    The following code will configure the UnbxdRecommendation client to fetch products that were recently viewed by the visitor:

    $response = $unbxd->getRecommendationsClient()->getRecentlyViewed(uid,"100.0.0.1"); 
    

    Here,

    • uid: This value can be fetched from the browser cookie: "unbxd.userId”

    • "100.0.0.1": IP address

    Recommended For You

    The following code will configure the UnbxdRecommendation client to fetch recommended products for your visitor:

    $response = $unbxd->getRecommendationsClient()->getRecommendedForYou(uid, "100.0.0.1");
    

    More Like This

    The following code will configure the UnbxdRecommendation client to fetch products similar to the product being viewed by the visitor:

    $response = $unbxd->getRecommendationsClient()->getMoreLikeThis("sku1", uid, "100.0.0.1");
    

    Here,

    • sku1: the SKU ID of the product

    Viewed Also Viewed

    The following code will configure the UnbxdRecommendation client to fetch products viewed by other visitors who were previously on the current (Product Detail Page) PDP:

    $response = $unbxd->getRecommendationsClient()->getAlsoViewed("sku1", uid,"100.0.0.1"); 
    

    Bought Also Bought

    The following code will configure the UnbxdRecommendation client to fetch products bought by other visitors:

    $response = $unbxd->getRecommendationsClient()->getAlsoBought("sku1", uid, "100.0.0.1");
    

    Homepage Top Sellers

    The following code will configure the UnbxdRecommendation client to fetch top selling products on the Homepage:

    $response = $unbxd->getRecommendationsClient()->getTopSellers(uid, "100.0.0.1");
    

    Category Top Sellers

    The following code will configure the UnbxdRecommendation client to fetch top selling products of a particular category:

    RecommendationResponse response = Unbxd.getRecommendationsClient().getCategoryTopSellers("Shoes", uid, "100.0.0.1");  
    

    Here,

    • shoes: is the category

    Brand Top Sellers

    The following code will configure the UnbxdRecommendation client to fetch top selling products of a particular brand:

    $response = $unbxd->getRecommendationsClient()->getBrandTopSellers("Adidas", uid, "100.0.0.1");  
    

    Here,

    • Adidas: is the Brand

    PDP Top Sellers

    The following code will configure the UnbxdRecommendation client to fetch top selling products on a particular Product Detail Page (PDP):

    $response = $unbxd->getRecommendationsClient()->getPDPTopSellers("sku1", uid, "100.0.0.1");  // uid is value of the cookie : "unbxd.userId"
    

    Cart Recommendation

    The following code will configure the UnbxdRecommendation client to fetch recommended products for the products added to cart:

    $response = $unbxd->getRecommendationsClient()->getCartRecommendations(uid, "100.0.0.1");  // uid is value of the cookie : "unbxd.userId"