Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

intelligent search events api (headless) - update descriptions and examples #1314

Merged
merged 6 commits into from
Sep 19, 2024
Merged

intelligent search events api (headless) - update descriptions and examples #1314

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
82f9d71
update descriptions and examples
julia-rabello Sep 4, 2024
59d0288
improve description
julia-rabello Sep 4, 2024
9625832
improve description
julia-rabello Sep 4, 2024
7dae7f4
Update generated files by portman
Sep 4, 2024
c643141
Update VTEX - Intelligent Search Events API - Headless.json
julia-rabello Sep 19, 2024
348ed9d
Merge branch 'master' into is-headless-updates
julia-rabello Sep 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 23 additions & 37 deletions PostmanCollections/VTEX - Intelligent Search Events API - Headless.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
{
"_": {
"postman_id": "309092ed-7c43-4cb9-ba58-5081fb8fbc33"
"postman_id": "98c860ee-2779-4a3f-95c1-5bbaff19c696"
},
"item": [
{
"id": "6cc6f5ab-2a0e-47b4-b52a-f4ffe54e46f4",
"id": "e4f0e417-2665-403f-9695-110d8126032c",
"name": "Events",
"description": {
"content": "",
"type": "text/plain"
},
"item": [
{
"id": "6dc5ba04-11e5-4597-85ac-45d8a63238d3",
"id": "02fc4f7e-98aa-4b97-aceb-3e0becad8a96",
"name": "Save events",
"request": {
"name": "Save events",
"description": {
"content": "Creates search events to integrate with VTEX Intelligent Search using a headless implementation. \r\n\r\n >⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using VTEX's storefront solution, natively integrated with Intelligent Search\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).",
"content": "Creates search events to integrate with VTEX Intelligent Search using a headless implementation. \r\n\r\nRead [VTEX Intelligent Search Events API - Headless - Overview](https://developers.vtex.com/docs/api-reference/intelligent-search-events-api-headless) for more information on event types and user identification.\r\n\r\n>⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using VTEX's storefront solution, natively integrated with Intelligent Search\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).",
"type": "text/plain"
},
"url": {
Expand All @@ -32,11 +32,11 @@
{
"disabled": false,
"description": {
"content": "Name of the VTEX account. Used as part of the URL.",
"content": "(Required) Name of the VTEX account. Used as part of the URL.",
"type": "text/plain"
},
"type": "any",
"value": "{{accountName}}",
"value": "apiexamples",
"key": "accountName"
}
]
Expand All @@ -50,9 +50,10 @@
"method": "POST",
"body": {
"mode": "raw",
"raw": "{\n \"session\": \"zZlNhqz1vFJP6iPG5Oqtt\",\n \"anonymous\": \"Om1TNluGvgmSgU5OOTvkkd\",\n \"url\": \"https://example.com/search/?query=zapatilha\",\n \"agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\n \"type\": \"search.query\",\n \"text\": \"zapatilha\",\n \"misspelled\": true,\n \"match\": 392,\n \"operator\": \"and\"\n}",
"raw": "{\n \"session\": \"df66a4d239864d2e8497c89aea14a3ad\",\n \"anonymous\": \"eed429ecf04a4a23ae7f4429033b48cd\",\n \"url\": \"https://example.com/search/?query=zapatilha\",\n \"agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\n \"type\": \"search.query\",\n \"text\": \"zapatilha\",\n \"misspelled\": true,\n \"match\": 392,\n \"operator\": \"and\"\n}",
"options": {
"raw": {
"headerFamily": "json",
"language": "json"
}
}
Expand All @@ -63,7 +64,7 @@
"_": {
"postman_previewlanguage": "text"
},
"id": "3f5b2a2d-9206-4cea-8476-0d9758919b0a",
"id": "b7657979-ba01-4e44-8ee6-4d813a1f642c",
"name": "No content",
"originalRequest": {
"url": {
Expand All @@ -74,47 +75,37 @@
"{{baseUrl}}"
],
"query": [],
"variable": [
{
"disabled": false,
"description": {
"content": "Name of the VTEX account. Used as part of the URL.",
"type": "text/plain"
},
"type": "any",
"value": "{{accountName}}",
"key": "accountName"
}
]
"variable": []
},
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"method": "POST",
"body": {
"mode": "raw",
"raw": "{\n \"session\": \"zZlNhqz1vFJP6iPG5Oqtt\",\n \"anonymous\": \"Om1TNluGvgmSgU5OOTvkkd\",\n \"url\": \"https://example.com/search/?query=zapatilha\",\n \"agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\n \"type\": \"search.query\",\n \"text\": \"zapatilha\",\n \"misspelled\": true,\n \"match\": 392,\n \"operator\": \"and\"\n}",
"raw": "{\n \"session\": \"df66a4d239864d2e8497c89aea14a3ad\",\n \"anonymous\": \"eed429ecf04a4a23ae7f4429033b48cd\",\n \"url\": \"https://example.com/search/?query=zapatilha\",\n \"agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\n \"type\": \"search.query\",\n \"text\": \"zapatilha\",\n \"misspelled\": true,\n \"match\": 392,\n \"operator\": \"and\"\n}",
"options": {
"raw": {
"headerFamily": "json",
"language": "json"
}
}
}
},
"status": "No Content",
"code": 204,
"header": [
{
"key": "Content-Type",
"value": "text/plain"
}
],
"body": "",
"header": [],
"cookie": []
}
],
"event": [
{
"listen": "test",
"script": {
"id": "4ec76ece-0e32-49ed-9f31-12196a7d3f57",
"id": "67cbcde2-6263-4d3d-a991-15472a689805",
"type": "text/javascript",
"exec": [
"// Validate status 2xx \npm.test(\"[POST]::/event - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n",
Expand All @@ -134,27 +125,22 @@
"event": [],
"variable": [
{
"description": {
"content": "Name of the VTEX account. Used as part of the URL.",
"type": "text/plain"
},
"type": "any",
"value": "apiexamples",
"key": "accountName"
},
{
"type": "string",
"type": "any",
"value": "https://sp.vtex.com/event-api/v1/{{accountName}}",
"key": "baseUrl"
}
],
"info": {
"_postman_id": "309092ed-7c43-4cb9-ba58-5081fb8fbc33",
"_postman_id": "98c860ee-2779-4a3f-95c1-5bbaff19c696",
"name": "VTEX Intelligent Search Events API - Headless",
"version": {},
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"description": {
"content": "Intelligent Search Events API is responsible for collecting the search events to improve your search results, such as page interactions and conversion, in a headless implementation. Some of the features improved by this collection are the possibility to sort the products by clicks or record the top search in the autocomplete.\r\n\r\n>⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using Store Framework, since they are already integrated with all Intelligent Search features.\r\n\r\n## Building the request body\r\n\r\nIn the following sections, we detail the required structure for the request body of the `POST`[Save events](https://developers.vtex.com/docs/api-reference/intelligent-search-events-api-headless#post-/event) endpoint.\r\n\r\n### User identification\r\n\r\nTo identify the user, there are two required identifiers according to the [nanoid](https://github.com/ai/nanoid) pattern: `session` and `anonymous`. Read the API reference for more information on each field.\r\n\r\n> ⚠️ The `session` and `anonymous` identifiers need to be sent in every request.\r\n\r\n### Event type\r\n\r\nTo identify the events that occur in our search, the `type` field is required in the request. The most common event types are the following:\r\n\r\n| Event type | Value | Description |\r\n| - | - | - |\r\n| Session Ping | `session.ping` | Sends an ACK to the API to renew the session server-side. It should be sent every 1 minute. |\r\n| Page Cart | `page.cart` | Sends an event every time the shopper enters the cart page. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. |\r\n| Empty Cart | `page.empty_cart` | Sends an event if there are no products in the shopping cart at that time. | \r\n| Page Confirmation |`page.confirmation` | Sends a confirmation informing the products that were bought. |\r\n| Search Click | `search.click` | Sends an event every time a shopper clicks on a product from a search page. |\r\n| Search Query | `search.query` | Sends a query event every time the shopper makes a full-text search. |\r\n\r\n### Finding search query information\r\n\r\nSearch query information is possible to find in the Intelligent Search GraphQL response. To retrieve the information above, add operator, fuzzy, and correction attributes in the GraphQL query. Example:\r\n\r\n```graphql\r\nquery {\r\n productSearch(fullText: \"id:43534\") {\r\n products {\r\n productId\r\n productName\r\n ...\r\n }\r\n operator\r\n fuzzy\r\n correction{ \r\n misspelled\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Optional fields\r\n\r\nInformation to identify where the context of that request came from: `agent` and `URL`. Read the API reference for more information on each field.\r\n\r\n### Request body examples\r\n\r\nThe body is built by combining the user information, the event type, and add the optional fields. Below there is an example for each type of event.\r\n\r\n#### Session Ping\r\n\r\n```json\r\n{\r\n\t\"session\":\"zZlNhqz1vFJP6iPG5Oqdf\",\r\n\t\"anonymous\":\"Om1TNluGvgmSgU5OOTvdfg\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"session.ping\"\r\n}\r\n``` \r\n\r\n#### Page Cart \r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\": [\r\n {\r\n \"productId\": \"ABC123\",\r\n \"quantity\": 2\r\n },\r\n {\r\n \"productId\": \"XYZ789\",\r\n \"quantity\": 1\r\n }\r\n ],\r\n \"type\": \"page.cart\"\r\n}\r\n```\r\n\r\n#### Empty Cart \r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\": [],\r\n \"type\": \"page.empty_cart\"\r\n}\r\n```\r\n\r\n#### Page Confirmation\r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\": [\r\n {\r\n \"productId\": \"ABC123\",\r\n \"price\": 9.99,\r\n \"quantity\": 3\r\n },\r\n {\r\n \"productId\": \"XYZ789\",\r\n \"price\": 5.99,\r\n \"quantity\": 2\r\n }\r\n ],\r\n \"order\": \"123ABC\",\r\n \"type\": \"page.confirmation\"\r\n}\r\n```\r\n\r\n#### Search Click\r\n\r\n```json\r\n{\r\n\t\"type\": \"search.click\",\r\n\t\"productId\": \"12345\",\r\n\t\"position\": 1,\r\n\t\"url\": \"https://example.com/s?q=pneu&sort=score_desc&page=0\",\r\n\t\"text\": \"pneu\",\r\n\t\"agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36\",\r\n\t\"anonymous\": \"1ce47e50-3f10-4556-95d3-57d4881c03a4\",\r\n\t\"session\": \"51a53ce3-096d-4740-a6d0-3cf86085ba13\"\r\n}\r\n```\r\n\r\n#### Search Query\r\n\r\n```json\r\n{\r\n\t\"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n\t\"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"search.query\",\r\n\t\"text\":\"zapatilha\",\r\n\t\"misspelled\":true,\r\n\t\"match\":392,\r\n\t\"operator\":\"and\"\r\n}\r\n```\r\n",
"content": "Intelligent Search Events API is responsible for collecting the search events to improve your search results, such as page interactions and conversion, in a headless implementation. Some of the features improved by this collection are the possibility to sort the products by clicks or record the top search in the autocomplete.\r\n\r\n>⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using Store Framework, since they are already integrated with all Intelligent Search features.\r\n\r\n## Building the request body\r\n\r\nIn the following sections, we explain the required structure for the request body for saving events. Check the `POST` [Save events](https://developers.vtex.com/docs/api-reference/intelligent-search-events-api-headless#post-/event) endpoint reference for more detailed field descriptions and examples.\r\n\r\nFull request example (Session Ping):\r\n\r\n```json\r\ncurl --request post \\\r\n\t--url https://sp.vtex.com/event-api/v1/{accountName}/event \\\r\n\t--header 'Content-Type: application/json' \\\r\n\t--data '{\"session\":\"df66a4d239864d2e8497c89aea14a3ad\",\"anonymous\":\"eed429ecf04a4a23ae7f4429033b48cd\",\"url\":\"https://example.com/search/?query=zapatilha\",\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\"type\":\"search.query\",\"text\":\"zapatilha\",\"misspelled\":true,\"match\":392,\"operator\":\"and\"}'\r\n```\r\n\r\n### User identification\r\n\r\nTo identify the user, there are two required identifiers: `session` and `anonymous`. We recommend using a [Universally Unique Identifier (UUID) v4](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) without dashes.\r\n\r\nSample JavaScript code to generate a random UUID without dashes:\r\n\r\n```js\r\nwindow.crypto.randomUUID().replaceAll('-', '')\r\n```\r\n\r\n>⚠️ The `session` and `anonymous` identifiers need to be sent in every request.\r\n\r\n\r\n### Event type\r\n\r\nTo identify the events that occur in our search, the `type` field is required in the request. The most common event types are the following:\r\n\r\n| Event type | Value | Description |\r\n| - | - | - |\r\n| Session Ping | `session.ping` | Sends an ACK to the API to renew the session server-side. It should be sent every 1 minute. |\r\n| Page Confirmation |`page.confirmation` | Sends a confirmation informing the products that were bought. |\r\n| Search Click | `search.click` | Sends an event every time a shopper clicks on a product from a search page. |\r\n| Search Query | `search.query` | Sends a query event every time the shopper makes a full-text search. |\r\n\r\n### Optional fields\r\n\r\nInformation to identify where the context of that request came from: `agent` and `URL`. Read the API reference for more information on each field.\r\n\r\n### Request body examples per event type\r\n\r\nThe body is built by combining the user information, the event type, and add the optional fields. Below there is an example for each type of event.\r\n\r\n#### Session Ping\r\n\r\n\r\n```json\r\n{\r\n\t\"session\":\"df66a4d239864d2e8497c89aea14a3ad\",\r\n\t\"anonymous\":\"eed429ecf04a4a23ae7f4429033b48cd\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"session.ping\"\r\n}\r\n```\r\n\r\n#### Page Confirmation\r\n\r\n```json\r\n{\r\n \"session\":\"df66a4d239864d2e8497c89aea14a3ad\",\r\n \"anonymous\":\"eed429ecf04a4a23ae7f4429033b48cd\",\r\n \"products\": [\r\n {\r\n \"productId\": \"ABC123\",\r\n \"price\": 9.99,\r\n \"quantity\": 3\r\n },\r\n {\r\n \"productId\": \"XYZ789\",\r\n \"price\": 5.99,\r\n \"quantity\": 2\r\n }\r\n ],\r\n \"order\": \"123ABC\",\r\n \"type\": \"page.confirmation\"\r\n}\r\n```\r\n\r\n#### Search Click\r\n\r\n```json\r\n{\r\n\t\"type\": \"search.click\",\r\n\t\"productId\": \"12345\",\r\n\t\"position\": 1,\r\n\t\"url\": \"https://example.com/s?q=pneu&sort=score_desc&page=0\",\r\n\t\"text\": \"pneu\",\r\n\t\"agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36\",\r\n\t\"anonymous\": \"1ce47e50-3f10-4556-95d3-57d4881c03a4\",\r\n\t\"session\": \"51a53ce3-096d-4740-a6d0-3cf86085ba13\"\r\n}\r\n```\r\n\r\n#### Search Query\r\n\r\n```json\r\n{\r\n\t\"session\":\"df66a4d239864d2e8497c89aea14a3ad\",\r\n\t\"anonymous\":\"eed429ecf04a4a23ae7f4429033b48cd\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"search.query\",\r\n\t\"text\":\"zapatilha\",\r\n\t\"misspelled\":true,\r\n\t\"match\":392,\r\n\t\"operator\":\"and\"\r\n}\r\n```\r\n\r\n### Finding search query information\r\n\r\nSearch query information is possible to find in the Intelligent Search GraphQL response. To retrieve the information above, add operator, fuzzy, and correction attributes in the GraphQL query. Example:\r\n\r\n```graphql\r\nquery {\r\n productSearch(fullText: \"id:43534\") {\r\n products {\r\n productId\r\n productName\r\n ...\r\n }\r\n operator\r\n fuzzy\r\n correction{ \r\n misspelled\r\n }\r\n }\r\n}\r\n```",
"type": "text/plain"
}
}
Expand Down
Loading