Skip to content

Integration of Catalogue information and user behavior data

This tutorial will cover how to integrate your catalogue information into GAIP and how to setup user behavior tracking and integrate with GAIP.

Catalogue information integration.

Prerequisite: Environment setup is complete (mapping creation and the index creation).

There are two ways to import your catalogue information into GAIP. 1. Upload you catalogue information as a CSV or JSON file using the POST /v1/item/save endpoint.
2. Fetch data from your API (or any external API) using the POST /v1/item/save/remote endpoint.

For uploading the data using a CSV file or JSON file, please use the POST /v1/item/save endpoint. Simply upload the file and confirm the server response is success. Confirm the task was sccessfull using the GET/v1/tasks/{task_id} endpoint.

Info

This will throw an error/Task will fail, if the keys during the Mapping creation step does not match with the keys in the file, OR the indices were not created succesfully.

To fetch data from external API, use the POST /v1/item/save/remote endpoint. From the earlier example, to fetch data from Shop API, using POST /v1/item/save/remote endpoint, we can use the below request body to fetch the data. There are some required parameters to successfully save the items. The key and value types of the parameters are depicted below:

name key type value type description
url str str Represents URL of the product details api from where you want to fetch items into recommender
method str str Represents api method of the endpoint from which you want to fetch data into recommender.
headers Optional[Dict[str, str]] str Represents the meta data associated with api request and response.
query_parameters Optional[Dict[str, str]] str Represents the query parameter of api endpoint. It could be required to fetch data from external api otherwise you can keep it empty.
body_parameters Optional[Dict[str, str]] str Represents the body parameter of api endpoint. It could be required to fetch data from external api otherwise you can keep it empty.
response_items_key str str Represents the key of response items which you want to fetch into recommender .
response_item_key Optional[str] str If you have multiple keys in response you can use the key from where you want to fetch items. It could be empty as well.

Example request body :

{
  "url": "https://api.doozie.shop/v1/sandbox/v1/api/items/search", 
  "method": "POST",
  "headers": {
    "accept": "application/json",
    "Content-Type": "application/json"
  },
  "query_parameters": {
  },
  "body_parameters": {
    "rakuten_query_parameters": {
        "keyword": "Pant"
    },
    "yahoo_query_parameters": {
        "query": "Pant"
    }
  },
  "response_items_key": "result",
  "response_item_key": ""
}

After hitting either of the endpoint above to import your data into GAIP, you will get a task ID in the response. Use this task ID and hit the /v1/tasks/{task_id} endpoint to confirm the operation was successful. In case it fails, you can also find the details there.

Search Items in GAIP after import

You can search items by passing list of item ids fromPOST /v1/items endpoint.

It is recommended to use this endpoint to confirm that the item catalogue import into GAIP was successull.

This endpoint will return searched items with item details. There are some prerequisite parameters which you have to pass in request body.

Parameters:

name key type value type description
entity_id Optional[str] str entity_id could be either item_id or user_id or None.
ids List[str] str List of item ids.

User behavior tracking and integration

GAIP can collect different user behavior related information to optimize the recommendation for the user. The data collected are below is a list of the types of user behavior with their endpoints.

Data type Endpoint
Product browsing: When user goes to a product detil page or clicks on a product for a pop-up etc. /v1/items/browse
Product Purchase: When uers purchase a product and its quantity. /v1/items/purchase
Rating: When a user rates a product. /v1/items/rating
User: User information usch as Age, gender and other customized attributes depending on your website. /v1/items/rating

There are 3 ways to integrate and send the above user behavior related data to GAIP

  1. Google Tag Manager
  2. Server to server integration
  3. Client to server integration

You can also bulk upload user behavior data from the past. For that, please refer to Import user behavior data section.

Comparison of each approach for data integration

Approach GTM Server to Server Client to Server
Description Use Google tag manager (GTM) to collect data (User behavior) from your website and send it to GAIP via endpoint. The data is captured in the backend server of your website and then sent to GAIP via endpoint. The data is directly sent from your front end (Client side) to GAIP via endpoint. (This approach is stil under development will be coming soon.)
Pros Easy to implement, No coding required, Flexible configuration More secure, Data integrity, Controlled environment Real-time data, Less server dependency
Cons Limited customization, need to have basic knowledge about GTM, Dependency on third-party service More complex to set up, Potential latency, Maintenance required Less secure, Potential for inconsistent data, Dependency on client-side behavior

Below we will show the implementaino of each approach.

PLEASE BE ADVISED: The following is a general guideline, and it may vary across different websites, contingent upon the specific implementation of your website.

Google Tag manager

Prerequisite: Your website must have GTM setup. If you do not have GTM setup, you can easily do the setup by following the guidelines here.

If you are not familiar with basic GTM concepts, such as Tags, Triggers and Variables, please familiarize yourself first with these concepts before proceeding with this approach. You can find more resources related to this here.

Collecting and sending user broswing data

Setup a variable to capture the product name/title/ID, when the user goes a product details page or clicks on a product to enlarge it or open a pop up etc..

Setup a trigger so that the tag would fire when the user goes to a product page.

Create a custom HTML Tag with the above trigger and put the below code in the tag. In the below snippet, the variable to capture the product name/title or product ID is item_id.

    <script>
      if ({{ item_id }}) {
        var gaipUser = localStorage.getItem('gaip_user_id'); //this will be updated with
        var gaipMember = localStorage.getItem('gaip_member_id');//this will be updated 

        var gaipUser = localStorage.getItem('gaip_user_id');
        if (gaipUser == null) {
          localStorage.setItem('gaip_user_id', "12345") //to be replaced with function from GAIP
        }  
        var gaipMember = localStorage.getItem('gaip_member_id'); //need to replace with the datalayer variable, this is assuming that the phone number is saved in the browser already.


    var myHeaders = new Headers();
        myHeaders.append("accept", "application/json");
        myHeaders.append("project-key", "{{ YOUR_PROJECT_KEY_HERE }}");
        myHeaders.append("api-key", "{{ YOUR_API_KEY_HERE }}");
        myHeaders.append("Content-Type", "application/json");


        var raw = JSON.stringify({
          "user_id": gaipUser,
          "member_id": gaipMember,
          "item_id": {{ Click_ID }}
        });

        var requestOptions = {
          method: 'POST',
          headers: myHeaders,
          body: raw,
          redirect: 'follow'
        };

    fetch("https://api.recommender.gigalogy.com/v1/items/browse", requestOptions);
      }
    </script>

Collecting and sending user purchase data

Setup a variable to capture the all the purchase detail, when the user makes a purchase. This could be from the purchase confirmation page etc.

Setup a trigger so that the tag would fire when the user make the purchase.

Create a custom HTML Tag with the above trigger and put the below code. Here the variable to capture the purchase detail is item_list.

<script>
  if ({{ item_list }}) {

      var gaipUser = localStorage.getItem('gaip_user_id'); //this will be updated with
      var gaipMember = localStorage.getItem('gaip_member_id');//this will be updated 

      var gaipUser = localStorage.getItem('gaip_user_id');
      if (gaipUser == null) {
        localStorage.setItem('gaip_user_id', "12345") //to be replaced with function from GAIP
      }  
      var gaipMember = localStorage.getItem('gaip_member_id'); //need to replace with the datalayer variable, this is assuming that the phone number is saved in the browser already.

    var myHeaders = new Headers();
    myHeaders.append("accept", "application/json");
    myHeaders.append("project-key", "{{ YOUR_PROJECT_KEY_HERE }}");
    myHeaders.append("api-key", "{{ YOUR_API_KEY_HERE }}");
    myHeaders.append("Content-Type", "application/json"); 

    var raw = JSON.stringify({
      "user_id": gaipUser,
      "member_id": gaipMember, //This is
      "item_list": [
        {
          "item_id": "<ITEM_ID_1>", // Placeholder
          "price": "<PRICE_1>", // Placeholder
          "quantity": "<QUANTITY_1>" // Placeholder
        },
        {
          "item_id": "<ITEM_ID_2>", // Placeholder
          "price": "<PRICE_2>", // Placeholder
          "quantity": "<QUANTITY_2>" // Placeholder
        }
      ]
    });
    var requestOptions = {
      method: 'POST',
      headers: myHeaders,
      body: raw,
      redirect: 'follow'
    };

fetch("https://api.recommender.gigalogy.com/v1/purchase", requestOptions);
  }
</script>

Collecting and sending user rating data

Setup two variables to capture the product name/title/ID and the rating, when the user rates and item such as 2 star or 3 star etc. such as in the Doozie shop

Setup a trigger so that the tag would fire when the user rates a product.

Create a custom HTML Tag with the above trigger and but the below code. In the below sample snippet, the variable to capture the product name/title/ID is item_id and variable to capture the rating is rating.

<script>
  if ({{ item_id }} && {{ rating }}) {

      var gaipUser = localStorage.getItem('gaip_user_id'); //this will be updated with
      var gaipMember = localStorage.getItem('gaip_member_id');//this will be updated 

      var gaipUser = localStorage.getItem('gaip_user_id');
      if (gaipUser == null) {
        localStorage.setItem('gaip_user_id', "12345") //to be replaced with function from GAIP
      }  
      var gaipMember = localStorage.getItem('gaip_member_id'); //need to replace with the datalayer variable, this is assuming that the phone number is saved in the browser already.

    var myHeaders = new Headers();
    myHeaders.append("accept", "application/json");
    myHeaders.append("project-key", "{{ YOUR_PROJECT_KEY_HERE }}");
    myHeaders.append("api-key", "{{ YOUR_API_KEY_HERE }}");
    myHeaders.append("Content-Type", "application/json");

    var raw = JSON.stringify({
      "user_id": gaipUser,
      "member_id": gaipMember,
      "item_id": {{ Click_ID }},
      "rating": {{ rating }} // Including rating in the JSON object
    });

    var requestOptions = {
      method: 'POST',
      headers: myHeaders,
      body: raw,
      redirect: 'follow'
    };

fetch("https://api.recommender.gigalogy.com/v1/rating", requestOptions);
  }
</script>

Collecting and sending user data

Setup variable to capture the iser information.

For this, the trigger could be setup up when the user logs in or updates account information etc.

Below is a sample custom HTML code to send the information to GAIP

<script>
  if ({{ user_info }}) {

      var gaipUser = localStorage.getItem('gaip_user_id'); //this will be updated with
      var gaipMember = localStorage.getItem('gaip_member_id');//this will be updated 

      var gaipUser = localStorage.getItem('gaip_user_id');
      if (gaipUser == null) {
        localStorage.setItem('gaip_user_id', "12345") //to be replaced with function from GAIP
      }  
      var gaipMember = localStorage.getItem('gaip_member_id'); //need to replace with the datalayer variable, this is assuming that the phone number is saved in the browser already.

    var myHeaders = new Headers();
    myHeaders.append("accept", "application/json");
    myHeaders.append("project-key", "{{ YOUR_PROJECT_KEY_HERE }}");
    myHeaders.append("api-key", "{{ YOUR_API_KEY_HERE }}");
    myHeaders.append("Content-Type", "application/json");

    var raw = JSON.stringify({
      "user_id": gaipUser,
      "member_id": gaipMember,      
      "user_info": {
          "address": "<ADDRESSS STRING>",
          "gender": "<INTEGER>", // 1 for male or 2 for female or 3 for others
          "age": <AGE_INTEGER>,
          "user_type": [
            {
              "key_name1": "value1_value2",
              "separator": "_"
            },
            {
              "key_name2": "value3"
            }
          ]
        }
    });

    var requestOptions = {
      method: 'POST',
      headers: myHeaders,
      body: raw,
      redirect: 'follow'
    };

fetch("https://api.recommender.gigalogy.com/v1/user", requestOptions);
  }
</script>

Server to server integration

User information

The below request path, takes user information, such as name, age, gender, address and saves them in the gaip database.

POST /v1/user

Here is an example request body

{
  "user_id": "a0cc6beb-2909-459b-be55-62196af78ce4",
  "member_id": "df3456tg-2909-459b-be55-62196afedf85",
  "user_info": {
    "address": "string",
    "gender": "integer --> 1 for male or 2 for female or 3 for others",
    "age": 25,
    "user_type": [
      {
        "key_name1": "value1_value2",
        "separator": "_"
      },
      {
        "key_name2": "value3"
      }
    ]
  }
}
You can find the sample code for implementation here

Product broswse

You can use the below endpoint to capture user browsing information and save them in GAIP database

POST /v1/items/browse

It takes user_id and item_id as required parameters.

Here is a example value of the request body

  {
    "user_id": "a0cc6beb-2909-459b-be55-62196af78ce4",
    "member_id": "df3456tg-2909-459b-be55-62196afedf85",
    "item_id": "1000764491"
  }

You can find sample code here

Product purchase

You can use the below endpoint to capture user's product purchase information and save them in GAIP database

POST /v1/purchase
It takes user_id, item_list which includes item_id, price, quantity for a specific item as required parameters.

Here is an example request body

  {
    "user_id": "a0cc6beb-2909-459b-be55-62196af78ce4",
    "member_id": "df3456tg-2909-459b-be55-62196afedf85",
    "item_list": [
      {
        "item_id": "1000757666",
        "price": 5000,
        "quantity": 1
      },
      {
        "item_id": "1000764491",
        "price": 400,
        "quantity": 7
      }
    ]
  }

You an find sample code for this implementation here

Product rating

You can use the below endpoint to capture user's product rating information and save them in GAIP database

POST /v1/rating

It takes user_id, item_id, and rating for the specific item as required parameters.

Here is a sample rrequest body

{
  "user_id": "a0cc6beb-2909-459b-be55-62196af78ce4",
  "member_id": "df3456tg-2909-459b-be55-62196afedf85",
  "item_id": "1000764491",
  "rating": "1"
}

You can find the sample code for this implementation here


If you want to save your data with bulk upload you can use above mentioned endpoint.

Client to server integration

This approach is stil under development will be coming soon.

Import user behavior data

Similar to data integration, all 4 kinds of user information (browse, purchase, rating, user) can be bulk uploaded. This could be usefull if you already have this information from the past and want to import it into GAIP.

To import user behavior and user information in bulk, first you need to create mapper to match the keys with GAIP.

To create the mapper, the endpoints with the example reqeust bodies can be found here in the gigalogy recommender page. You can also find the sample codes for mapper creation here in the API documentation page

Next we will user the below 4 endppints to upload each category of data in bulk

You can find these endpoints with the example request bodies here. The sample code can be found here in the API documentation page