> For the complete documentation index, see [llms.txt](https://rosetta-ai.gitbook.io/sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rosetta-ai.gitbook.io/sdk/rosetta.ai-sdk-developers-guide/sdk-v1.0-latest-version/how-to-use.md).

# 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:

```javascript
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:

```javascript
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!

{% hint style="info" %}
The **app ID** will be provided at the very beginning of Rosetta.ai service. You can set the value by config command.
{% endhint %}

**● 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

```javascript
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

<table data-header-hidden><thead><tr><th width="164">Field</th><th width="150">Required</th><th width="159.31466402322457">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Required</td><td>Data Type</td><td>Description</td></tr><tr><td><code>appId</code></td><td>Yes (SDK)<br>No (plugin)</td><td>String</td><td>Authentication for Rosetta.ai is done via <code>appId</code>.</td></tr><tr><td><code>shopperId</code></td><td>No</td><td>String</td><td>The ID of the user in the account system of your website</td></tr><tr><td><code>contact</code></td><td>No</td><td>Objects</td><td><code>line_id</code>&#x3C;string | null | undefined>: the line ID of the current shopper.<br>So far, we only accept <code>line_id</code> in contact.</td></tr></tbody></table>

## `query`

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

Sending `query` command by the following method:

```javascript
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

```javascript
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

<table data-header-hidden><thead><tr><th width="128.02552241024398">Parameter</th><th width="103.58775205377145">Required</th><th width="192">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>Fields</td><td>Required</td><td>Data Type</td><td>Description</td></tr><tr><td><code>engines</code></td><td>Yes</td><td>Array of String</td><td>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.</td></tr><tr><td><code>items</code></td><td>No</td><td>Array of String</td><td><p>Array of <strong>item ID</strong>.</p><p>The <strong>item ID</strong> is the ID of your product. Some engine needs to be used with <code>items</code>, you can provide only the current product ID in the product detail page, or the ID of each products in the cart.</p></td></tr><tr><td><code>filters</code></td><td>No</td><td>Object</td><td><p><strong><code>categoryTree</code></strong>&#x3C;string[]>:  The category tree of the products that you want to get from recommended data.<br><strong><code>category</code></strong>&#x3C;string>: The category of the products that you want to get from recommended data.</p><p><strong><code>tags</code></strong>&#x3C;string[]>: The tags of the products that you want to get from recommended data.</p><p><strong><code>item</code></strong>&#x3C;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.</p></td></tr></tbody></table>

**Example of response**

The response is an array of object

```json
[{
  "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

<table data-header-hidden><thead><tr><th width="305.26073429990225">Type</th><th>Definition</th></tr></thead><tbody><tr><td>Type</td><td>Definition</td></tr><tr><td><code>render</code></td><td>When the recommender is rendered on the page.</td></tr><tr><td><code>view</code></td><td>When the recommender is seen by the user.</td></tr><tr><td><code>click</code></td><td>When the user clicks on an item.</td></tr><tr><td><code>select</code></td><td>When the user adds an item to the cart.</td></tr><tr><td><code>unselect</code></td><td>When the user removes an item from the cart.</td></tr></tbody></table>

{% hint style="info" %}
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.).&#x20;
{% endhint %}

### Examples

#### render

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

#### view

```javascript
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).

```javascript
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.

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

#### unselect

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

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

{% hint style="warning" %}
You **must** have these events defined throughout your site. By not doing so, the accuracy of predictions will suffer greatly.
{% endhint %}

### 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                                                  | <p>The ID of your product.<br>This will be null or optional when the action type is <code>render</code> and <code>view</code>.</p>                                         |
| `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:

```javascript
rosettaData.command('purchase', params)
```

### Example

```javascript
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                                                  | <p>The ID of your product.<br>This will be null or optional when the action type is <code>render</code> and <code>view</code>.</p>                                         |
| `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.                                                                                                              |

<table data-header-hidden><thead><tr><th width="208.05834979777828">Fields</th><th width="150">Required</th><th width="150">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>Fields</td><td>Required</td><td>Data Type</td><td>Description</td></tr><tr><td><code>orderNumber</code></td><td>Yes</td><td>String</td><td>The ID of the order which records the purchase</td></tr><tr><td><code>products</code></td><td>Yes</td><td>Array of Object</td><td><p><strong><code>target</code></strong>&#x3C;string>: The local ID of your current product<br><strong><code>quantity</code></strong>&#x3C;number>: The quantity of the current product in the order</p><p><strong><code>total</code></strong>&#x3C;number>: The total price amount of the product<br><span class="math">total=price∗quantity</span><em><mark style="color:purple;">​</mark></em></p></td></tr><tr><td><code>total</code></td><td>Yes</td><td>number</td><td>The total amount of the order</td></tr><tr><td><code>currency</code></td><td>Yes</td><td>String</td><td>The currency of the purchase</td></tr></tbody></table>

If you have any installation questions, feel free to contact us: [Rosetta.ai](https://www.rosetta.ai/) ｜ [Medium](https://blog.rosetta.ai/) ｜ [Facebook](https://www.facebook.com/RosettaAI/)