How to use

In order to get and set data, the commands need to be implemented properly, following the instructions detailed in this section.

How to send commands?

You can send commands to Rosetta.ai by the following method:

rosettaData.command(name, params, cb)

name - 'config' | 'query' | 'event' | 'purchase'

params - based on the command name

cb - callback function, some commands support this

config

The config command is used to set up your app id and user id. This is not really needed for Plugin only users.

Sending config command by the following method:

rosettaData.command('config', params)

● If you are using SDK file

If you want to use the SDK file, then first thing to do is to call the config command for setting up the app ID. You need to do this before any other command in your code!

The app ID will be provided at the very beginning of Rosetta.ai service. You can set the value by config command.

● If you are using plugin file

You are using the plugin file, then you don't really need to set the app id because this is automatically done for you by in that file. However, if you still want to use custom data (like for example your Line app id), then you can use this command for setting this type of information.

Example

rosettaData.command('config', {
  appId: 'app_ID',
  shopperId: 'shopper_ID',
  contact: {
    line_id: 'line_user_1'
  },
})

Parameters

The following are the accepted parameters. You can send them in a JSON as seen in the example above

Field	Required	Data Type	Description
appId	Yes (SDK) No (plugin)	String	Authentication for Rosetta.ai is done via appId.
shopperId	No	String	The ID of the user in the account system of your website
contact	No	Objects	line_id<string | null | undefined>: the line ID of the current shopper. So far, we only accept line_id in contact.

query

The query command is used to get the data of recommended products.

Sending query command by the following method:

rosettaData.command('query', params, cb)

Via Sending query command with the parameters to fetch the API and get the data from the callback function.

Example

rosetta('query', {
  engines: ['engine_ID_1', 'engine_ID_2'],
  items: ['product_1'],
  filters: {
    categoryTree: ['New Arrival', 'Summer'],
  }
}, function (response) {
  console.log(response)
  /**
   * Render your own UI here
   */
})

Parameters

The following are the accepted parameters. You can send them in a JSON as seen in the example above

Fields	Required	Data Type	Description
engines	Yes	Array of String	Array of the engine ID used to get the recommended data. You could contact Rosetta.ai staff to know how to obtain the engine ID.
items	No	Array of String	Array of item ID. The item ID is the ID of your product. Some engine needs to be used with items, you can provide only the current product ID in the product detail page, or the ID of each products in the cart.
filters	No	Object	categoryTree<string[]>: The category tree of the products that you want to get from recommended data. category<string>: The category of the products that you want to get from recommended data. tags<string[]>: The tags of the products that you want to get from recommended data. item<string>: The string needs to be the same as a local ID from one of the items in the product feed. We will help to find the category_tree or the tags of the item.

Example of response

The response is an array of object

[{
  "id": "query_ID",
  "data": [{
    "item": 12345678,
    "property": {
        "local_id": "product_ID",
        "name": "product_name",
        "description": "product_description",
        "link": "product_link",
        "image_link": "product_image_link",
        "price": "1000.0",
        "currency": "TWD",
        "availability": "in stock",
        "vendor_name": "Rosetta Shop",
        "category_tree": [
            "On Sale",
            "50% Off"
        ],
        "sale_price": "500.0",
        "item_group_id": "product_ID",
        "type": "item"
    },
    "score": 1.0
  }],
  "created_at": 1592976508
}]

event

The event command is used to record your users' actions.

By doing so, you increase the reliability and accuracy of predictions over the time.

Event Types

Type	Definition
render	When the recommender is rendered on the page.
view	When the recommender is seen by the user.
click	When the user clicks on an item.
select	When the user adds an item to the cart.
unselect	When the user removes an item from the cart.

Remember that you only need to send attribution data is in click events. You don't need to send attribution data in other types of events. Rosetta will automatically record the attribution for the rest of the actions (select, unselect, etc.).

Examples

render

rosettaData.command('event', {
  type: "render",
  provider: "rosetta",
  context: "rosetta-carousel",
})

view

rosettaData.command('event', {
  type: "view",
  provider: "rosetta",
  context: "rosetta-carousel",
  source: "roestta_query_ID",
})

click

Please send the event command with attribution data(provider, context, source).

rosettaData.command('event', {
  type: "click",
  provider: "rosetta",
  context: "rosetta-carousel",
  source: "roestta_query_ID",
  target: "product_1",
})

select

Do not need to send the event command with attribution data.

rosettaData.command('event', {
  type: "select",
  target: "product_1",
})

unselect

Do not need to send the event command with attribution data.

rosettaData.command('event', {
  type: "unselect",
  target: "product_1",
})

You must have these events defined throughout your site. By not doing so, the accuracy of predictions will suffer greatly.

Parameters

The following are the accepted parameters. You can send them in a JSON as seen in the example above

Fields	Required	Data Type	Description
action	Yes	'render' | 'view' | 'click' | 'select' | 'unselect'	The event type defines what action your user does.
target	Yes(condition)	String	The ID of your product. This will be null or optional when the action type is render and view.
provider	No	'rosetta' | String	Where does the item come from. If the item comes from Rosetta.ai recommended data, please provide 'rosetta' as provider here. It is required when sending click event.
source	No	String	If it's an item that Rosetta.ai recommended, provide the ID from the response data. It's the query ID.
context	No	String	The name of the UI block that shows the recommended products.

purchase

The purchase command is used to record the data of the orders that your customers make.

Sending purchase command by the following method:

rosettaData.command('purchase', params)

Example

rosettaData.command('purchase', {
    orderNumber: "20220726042044309",
    currency: "TWD",
    total: 300,
    products: [
        {
            quantity: 1,
            target: "product_ID_1",
            total: 100
        },
        {
            quantity: 4,
            target: "product_ID_2",
            total: 200
        }
    ]
})

Parameters

The following are the accepted parameters. You can send them in a JSON as seen in the example above

Fields	Required	Data Type	Description
action	Yes	'render' | 'view' | 'click' | 'select' | 'unselect'	The event type defines what action your user does.
target	Yes(condition)	String	The ID of your product. This will be null or optional when the action type is render and view.
provider	No	'rosetta' | String	Where does the item come from. If the item comes from Rosetta.ai recommended data, please provide 'rosetta' as provider here. It is required when sending click event.
source	No	String	If it's an item that Rosetta.ai recommended, provide the ID from the response data. It's the query ID.
context	No	String	The name of the UI block that shows the recommended products.

Fields	Required	Data Type	Description
orderNumber	Yes	String	The ID of the order which records the purchase
products	Yes	Array of Object	target<string>: The local ID of your current product quantity<number>: The quantity of the current product in the order total<number>: The total price amount of the product $total=price∗quantity$​
total	Yes	number	The total amount of the order
currency	Yes	String	The currency of the purchase

If you have any installation questions, feel free to contact us: Rosetta.ai ｜ Medium ｜ Facebook