docs(specs): review Insights API spec (#1647)

Co-authored-by: gazconroy <gazconroyster@gmail.com>
Co-authored-by: Clément Vannicatte <vannicattec@gmail.com>
Co-authored-by: Mouaad Aallam <mouaad.aallam@algolia.com>

.github/.cache_version

@@ -1 +1 @@
-0.0.29
+0.0.31

clients/algoliasearch-client-dart/packages/client_insights/example/insights.dart

@@ -9,19 +9,18 @@ void main() async {
 
   // Creating an InsightEvents object with a list of InsightEvent objects.
   // Each InsightEvent represents an event such as a user viewing a specific item.
-  final events = InsightEvents(
+  final events = InsightsEvents(
     events: [
-      InsightEvent(
-        eventType: EventType.view,
+      ViewedObjectIDs(
+        eventType: ViewEvent.view,
         eventName: 'View event',
         index: 'instant_search',
         userToken: 'anonymous',
-        queryID: '43b15df305339e827f0ac0bdc5ebcaa7',
         objectIDs: ['5477500'],
       )
     ],
   );
-  await insights.pushEvents(insightEvents: events);
+  await insights.pushEvents(insightsEvents: events);
 
   // Close the client and dispose of all underlying resources.
   insights.dispose();

specs/insights/common/schemas/ClickEvent.yml

@@ -0,0 +1,2 @@
+type: string
+enum: [click]

specs/insights/common/schemas/ClickedFilters.yml

@@ -0,0 +1,23 @@
+type: object
+title: Clicked filters
+description: Use this event to track when users click facet filters in your user interface.
+additionalProperties: false
+properties:
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  eventType:
+    $ref: './ClickEvent.yml'
+  index:
+    $ref: './EventAttributes.yml#/index'
+  filters:
+    $ref: './EventAttributes.yml#/filters'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+required:
+  - eventName
+  - eventType
+  - index
+  - filters
+  - userToken

specs/insights/common/schemas/ClickedObjectIDs.yml

@@ -0,0 +1,27 @@
+type: object
+title: Clicked object IDs
+description: |
+  Use this event to track when users click items unrelated to a previous Algolia request.
+  For example, if you don't use Algolia to build your category pages, use this event.
+
+  To track click events related to Algolia requests, use the "Clicked object IDs after search" event.
+additionalProperties: false
+properties:
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  eventType:
+    $ref: './ClickEvent.yml'
+  index:
+    $ref: './EventAttributes.yml#/index'
+  objectIDs:
+    $ref: './EventAttributes.yml#/objectIDs'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+required:
+  - eventName
+  - eventType
+  - index
+  - objectIDs
+  - userToken

specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml

@@ -0,0 +1,34 @@
+type: object
+title: Clicked object IDs after search
+description: |
+  Click event after an Algolia request.
+
+  Use this event to track when users click items in the search results.
+  If you're building your category pages with Algolia,
+  you'll also use this event.
+additionalProperties: false
+properties:
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  eventType:
+    $ref: './ClickEvent.yml'
+  index:
+    $ref: './EventAttributes.yml#/index'
+  objectIDs:
+    $ref: './EventAttributes.yml#/objectIDs'
+  positions:
+    $ref: './EventAttributes.yml#/positions'
+  queryID:
+    $ref: './EventAttributes.yml#/queryID'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+required:
+  - eventName
+  - eventType
+  - index
+  - objectIDs
+  - positions
+  - queryID
+  - userToken

specs/insights/common/schemas/ConversionEvent.yml

@@ -0,0 +1,2 @@
+type: string
+enum: [conversion]

specs/insights/common/schemas/ConvertedFilters.yml

@@ -0,0 +1,22 @@
+type: object
+title: Converted filters
+additionalProperties: false
+properties:
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  eventType:
+    $ref: './ConversionEvent.yml'
+  index:
+    $ref: './EventAttributes.yml#/index'
+  filters:
+    $ref: './EventAttributes.yml#/filters'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+required:
+  - eventName
+  - eventType
+  - index
+  - filters
+  - userToken

specs/insights/common/schemas/ConvertedObjectIDs.yml

@@ -0,0 +1,27 @@
+type: object
+title: Converted object IDs
+description: |
+  Use this event to track when users convert on items unrelated to a previous Algolia request.
+  For example, if you don't use Algolia to build your category pages, use this event.
+
+  To track conversion events related to Algolia requests, use the "Converted object IDs after search" event.
+additionalProperties: false
+properties:
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  eventType:
+    $ref: './ConversionEvent.yml'
+  index:
+    $ref: './EventAttributes.yml#/index'
+  objectIDs:
+    $ref: './EventAttributes.yml#/objectIDs'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+required:
+  - eventName
+  - eventType
+  - index
+  - objectIDs
+  - userToken

specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml

@@ -0,0 +1,32 @@
+type: object
+title: Converted object IDs after search
+description: |
+  Use this event to track when users convert after a previous Algolia request.
+  For example, a user clicks on an item in the search results to view the product detail page.
+  Then, the user adds the item to their shopping cart.
+
+  If you're building your category pages with Algolia,
+  you'll also use this event.
+additionalProperties: false
+properties:
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  eventType:
+    $ref: './ConversionEvent.yml'
+  index:
+    $ref: './EventAttributes.yml#/index'
+  objectIDs:
+    $ref: './EventAttributes.yml#/objectIDs'
+  queryID:
+    $ref: './EventAttributes.yml#/queryID'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+required:
+  - eventName
+  - eventType
+  - index
+  - objectIDs
+  - queryID
+  - userToken

specs/insights/common/schemas/EventAttributes.yml

@@ -0,0 +1,83 @@
+eventName:
+  type: string
+  minLength: 1
+  maxLength: 64
+  description: |
+    Can contain up to 64 ASCII characters. 
+
+    Consider naming events consistently—for example,
+    by adopting Segment's
+    [object-action](https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/#the-object-action-framework)
+    framework.
+  example: Product Clicked
+
+index:
+  type: string
+  description: Name of the Algolia index.
+  example: YourIndexName
+
+userToken:
+  type: string
+  minLength: 1
+  maxLength: 128
+  pattern: '[a-zA-Z0-9_=/+-]{1,128}'
+  description: |
+    Anonymous or pseudonymous user identifier. 
+
+    > **Note**: Never include personally identifiable information in user tokens.
+  example: test-user-1
+
+timestamp:
+  type: integer
+  format: int64
+  description: |
+    Time of the event in milliseconds in [Unix epoch time](https://wikipedia.org/wiki/Unix_time).
+    By default, the Insights API uses the time it receives an event as its timestamp.
+  example: 1687193127
+
+queryID:
+  type: string
+  pattern: '[0-9a-f]{32}'
+  minLength: 32
+  maxLength: 32
+  description: |
+    Unique identifier for a search query.
+
+    The query ID is required for events related to search or browse requests.
+    If you add `clickAnalytics: true` as a search request parameter, the query ID is included in the API response.
+  example: 3e48cd0616e466948dd85abf5c3fbbe2
+
+objectIDs:
+  type: array
+  description: List of object identifiers for items of an Algolia index.
+  items:
+    type: string
+  minItems: 1
+  maxItems: 20
+  example: ['object-1', 'object-2', 'object-3']
+
+filters:
+  type: array
+  description: |
+    Facet filters.
+
+    Each facet filter string must be URL-encoded, such as, `discount:10%25`.
+  items:
+    type: string
+  minItems: 1
+  maxItems: 20
+  example: ['brand:apple']
+
+positions:
+  type: array
+  items:
+    type: integer
+  minimum: 1
+  minItems: 1
+  maxItems: 20
+  description: |
+    Position of the clicked objects in the search results.
+
+    The first search result has a position of 1 (not 0).
+    You must provide 1 `position` for each `objectID`.
+  example: [1, 2, 5]

specs/insights/common/schemas/EventsItems.yml

@@ -0,0 +1,9 @@
+oneOf:
+  - $ref: './ClickedObjectIDsAfterSearch.yml'
+  - $ref: './ConvertedObjectIDsAfterSearch.yml'
+  - $ref: './ClickedObjectIDs.yml'
+  - $ref: './ConvertedObjectIDs.yml'
+  - $ref: './ClickedFilters.yml'
+  - $ref: './ConvertedFilters.yml'
+  - $ref: './ViewedObjectIDs.yml'
+  - $ref: './ViewedFilters.yml'

specs/insights/common/schemas/EventsResponse.yml

@@ -0,0 +1,10 @@
+type: object
+description: The response of the Insights API.
+additionalProperties: false
+properties:
+  message:
+    type: string
+    description: Details about the response, such as error messages.
+  status:
+    type: integer
+    description: The HTTP status code of the response.

specs/insights/common/schemas/ViewEvent.yml

@@ -0,0 +1,2 @@
+type: string
+enum: [view]

specs/insights/common/schemas/ViewedFilters.yml

@@ -0,0 +1,26 @@
+type: object
+title: Viewed filters
+description: |
+  Use this method to capture active filters.
+  For example, when browsing a category page,
+  users see content filtered on that specific category.
+additionalProperties: false
+properties:
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  eventType:
+    $ref: './ViewEvent.yml'
+  index:
+    $ref: './EventAttributes.yml#/index'
+  filters:
+    $ref: './EventAttributes.yml#/filters'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+required:
+  - eventName
+  - eventType
+  - index
+  - filters
+  - userToken

specs/insights/common/schemas/ViewedObjectIDs.yml

@@ -0,0 +1,23 @@
+type: object
+title: Viewed object IDs
+description: Use this event to track when users viewed items in the search results.
+additionalProperties: false
+properties:
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  eventType:
+    $ref: './ViewEvent.yml'
+  index:
+    $ref: './EventAttributes.yml#/index'
+  objectIDs:
+    $ref: './EventAttributes.yml#/objectIDs'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+required:
+  - eventName
+  - eventType
+  - index
+  - objectIDs
+  - userToken