diff --git a/Analytics/Analytics.json b/Analytics/Analytics.json index 4afc8ea17..24ed3a03f 100644 --- a/Analytics/Analytics.json +++ b/Analytics/Analytics.json @@ -4,7 +4,7 @@ "info": { "title": "Analytics API", "class": "Analytics", - "description": "The `Analytics` plugin allows sending analytics events to dedicated backends." + "description": "The `Analytics` plugin allows sending analytics events to dedicated backends. Currently the SIFT backend is supported." }, "common": { "$ref": "../common/common.json" @@ -49,17 +49,20 @@ "example": 35000 }, "eventPayload":{ - "summary": "The payload of the event", + "summary": "Custom payload of the event in JSON format. User defined colection of objects and keys. May be an empty object", "type": "object", - "example": { - "key1": "value1", - "key2": "value2" + "properties": { + "keyOrObject": { + "summary": "User defined custom key or object", + "type": "string", + "example": "value1" + } } } }, "methods": { "sendEvent":{ - "summary": "Send event", + "summary": "Enqueue an event to be sent to the SIFT analytics backend", "params": { "type":"object", "properties": { @@ -97,32 +100,9 @@ ] }, "result": { - "$ref": "#/common/result" - } - }, - "setSessionId" : { - "summary": "Set the session ID for the analytics events", - "params": { - "type":"object", - "properties": { - "sessionId":{ - "summary": "Session ID", - "type": "string", - "example": "1234567890" - } - }, - "required": [ - "sessionId" - ] - }, - "result": { - "$ref": "#/common/result" - } - }, - "setTimeReady" : { - "summary": "Let the analytics plugin know that the system time is ready and valid", - "result": { - "$ref": "#/common/result" + "summary": "On success null will be returned", + "type": "string", + "example": "null" } } } diff --git a/Analytics/AnalyticsPlugin.json b/Analytics/AnalyticsPlugin.json index 5e36a8ec3..27383a2bb 100644 --- a/Analytics/AnalyticsPlugin.json +++ b/Analytics/AnalyticsPlugin.json @@ -1,13 +1,120 @@ { - "$schema": "https://raw.githubusercontent.com/rdkcentral/rdkservices/main/Tools/json_generator/schemas/plugin.schema.json", - "info": { - "title": "Analytics Plugin", - "callsign": "org.rdk.Analytics", - "locator": "libWPEFrameworkAnalytics.so", - "status": "development", - "description": "The `Analytics` plugin allows to send analytics events to dedicated backends." - }, - "interface": { - "$ref": "Analytics.json#" - } -} + "$schema":"https://raw.githubusercontent.com/rdkcentral/rdkservices/main/Tools/json_generator/schemas/plugin.schema.json", + "info":{ + "title":"Analytics Plugin", + "callsign":"org.rdk.Analytics", + "locator":"libWPEFrameworkAnalytics.so", + "status":"development", + "description":"The `Analytics` plugin allows to send analytics events to dedicated backends. Currently the SIFT backend is supported." + }, + "configuration":{ + "type":"object", + "properties":{ + "configuration":{ + "type":"object", + "properties":{ + "deviceosname":{ + "description":"Device OS name", + "type":"string" + }, + "sift":{ + "type":"object", + "properties":{ + "schema2":{ + "description":"If true, enables Sift 2.0 schema, otherwise uses Sift 1.0 schema", + "type":"boolean" + }, + "commonschema":{ + "description":"Sift schema common schema", + "type":"string" + }, + "env":{ + "description":"Sift schema environment", + "type":"string" + }, + "productname":{ + "description":"Sift schema product name", + "type":"string" + }, + "loggername":{ + "description":"Sift schema logger name", + "type":"string" + }, + "loggerversion":{ + "description":"Sift schema logger version", + "type":"string" + }, + "platformdefault":{ + "description":"Sift schema platform default value", + "type":"string" + }, + "maxrandomisationwindowtime":{ + "description":"Sift uploader max randomisation window time of posting queued events in seconds", + "type":"number" + }, + "maxeventsinpost":{ + "description":"Sift uploader max events in single post", + "type":"number" + }, + "maxretries":{ + "description":"Sift uploader max retries posting events", + "type":"number" + }, + "minretryperiod":{ + "description":"Sift uploader min retry period seconds", + "type":"number" + }, + "maxretryperiod":{ + "description":"Sift uploader max retry period seconds", + "type":"number" + }, + "exponentialperiodicfactor":{ + "description":"Sift uploader exponential periodic factor for retry delay", + "type":"number" + }, + "storepath":{ + "description":"Sift store path to persistent queue with events", + "type":"number" + }, + "eventslimit":{ + "description":"Sift store events limit", + "type":"number" + }, + "url":{ + "description":"URL to Sift server endpoint", + "type":"string" + } + }, + "required":[ + "schema2", + "commonschema", + "productname", + "loggername", + "loggerversion", + "platformdefault", + "maxrandomisationwindowtime", + "maxeventsinpost", + "maxretries", + "minretryperiod", + "maxretryperiod", + "exponentialperiodicfactor", + "storepath", + "eventslimit", + "url" + ] + } + }, + "required":[ + "deviceosname", + "sift" + ] + } + }, + "required":[ + "configuration" + ] + }, + "interface":{ + "$ref":"Analytics.json#" + } +} \ No newline at end of file diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 31d419daf..aa8cf9aa1 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -4,6 +4,7 @@ - [**Developer Guide**](developerguide/develperguidefornewplugin.md) - [**API Reference**](/README) - [ActivityMonitor](api/ActivityMonitorPlugin.md) + - [Analytics](api/AnalyticsPlugin.md) - [AVInput](api/AVInputPlugin.md) - [Bluetooth](api/BluetoothPlugin.md) - [CompositeInput](api/CompositeInputPlugin.md) diff --git a/docs/api/AnalyticsPlugin.md b/docs/api/AnalyticsPlugin.md new file mode 100644 index 000000000..d581c49fb --- /dev/null +++ b/docs/api/AnalyticsPlugin.md @@ -0,0 +1,137 @@ + + +# Analytics Plugin + +**Version: [1.0.1](https://github.com/rdkcentral/rdkservices/blob/main/Analytics/CHANGELOG.md)** + +A org.rdk.Analytics plugin for Thunder framework. + +### Table of Contents + +- [Abbreviation, Acronyms and Terms](#head.Abbreviation,_Acronyms_and_Terms) +- [Description](#head.Description) +- [Configuration](#head.Configuration) +- [Methods](#head.Methods) + + +# Abbreviation, Acronyms and Terms + +[[Refer to this link](userguide/aat.md)] + + +# Description + +The `Analytics` plugin allows to send analytics events to dedicated backends. Currently the SIFT backend is supported. + +The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [[Thunder](#ref.Thunder)]. + + +# Configuration + +The table below lists configuration options of the plugin. + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| callsign | string | Plugin instance name (default: *org.rdk.Analytics*) | +| classname | string | Class name: *org.rdk.Analytics* | +| locator | string | Library name: *libWPEFrameworkAnalytics.so* | +| autostart | boolean | Determines if the plugin shall be started automatically along with the framework | +| configuration | object | | +| configuration.deviceosname | string | Device OS name | +| configuration.sift | object | | +| configuration.sift.schema2 | boolean | If true, enables Sift 2.0 schema, otherwise uses Sift 1.0 schema | +| configuration.sift.commonschema | string | Sift schema common schema | +| configuration.sift?.env | string | *(optional)* Sift schema environment | +| configuration.sift.productname | string | Sift schema product name | +| configuration.sift.loggername | string | Sift schema logger name | +| configuration.sift.loggerversion | string | Sift schema logger version | +| configuration.sift.platformdefault | string | Sift schema platform default value | +| configuration.sift.maxrandomisationwindowtime | number | Sift uploader max randomisation window time of posting queued events in seconds | +| configuration.sift.maxeventsinpost | number | Sift uploader max events in single post | +| configuration.sift.maxretries | number | Sift uploader max retries posting events | +| configuration.sift.minretryperiod | number | Sift uploader min retry period seconds | +| configuration.sift.maxretryperiod | number | Sift uploader max retry period seconds | +| configuration.sift.exponentialperiodicfactor | number | Sift uploader exponential periodic factor for retry delay | +| configuration.sift.storepath | number | Sift store path to persistent queue with events | +| configuration.sift.eventslimit | number | Sift store events limit | +| configuration.sift.url | string | URL to Sift server endpoint | + + +# Methods + +The following methods are provided by the org.rdk.Analytics plugin: + +Analytics interface methods: + +| Method | Description | +| :-------- | :-------- | +| [sendEvent](#method.sendEvent) | Enqueue an event to be sent to the SIFT analytics backend | + + + +## *sendEvent [method](#head.Methods)* + +Enqueue an event to be sent to the SIFT analytics backend. + +### Events + +No Events + +### Parameters + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| params | object | | +| params.eventName | string | Name of the event | +| params?.eventVersion | string | *(optional)* Version number of event schema | +| params.eventSource | string | Name of the component that originates the event (Durable App ID if an App) | +| params.eventSourceVersion | string | Version number for the component that originates the event | +| params.cetList | array | An array of Capability Exclusion Tags to be included on the report. Each CET will exclude the event from being processed for the specified process, any may result in the event being dropped. May be an array of length zero | +| params.cetList[#] | string | | +| params?.epochTimestamp | integer | *(optional)* Timestamp for the START of this event, epoch time, in ms UTC | +| params?.uptimeTimestamp | integer | *(optional)* Timestamp for the START of this event, uptime of the device, in ms. ONLY to be used when Time quality is not good | +| params.eventPayload | object | Custom payload of the event in JSON format. User defined colection of objects and keys. May be an empty object | +| params.eventPayload.keyOrObject | string | User defined custom key or object | + +### Result + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| result | string | On success null will be returned | + +### Example + +#### Request + +```json +{ + "jsonrpc": "2.0", + "id": 42, + "method": "org.rdk.Analytics.sendEvent", + "params": { + "eventName": "app_summary", + "eventVersion": "1.0.0", + "eventSource": "epg", + "eventSourceVersion": "1.0.0", + "cetList": [ + "cet1" + ], + "epochTimestamp": 1721906631000, + "uptimeTimestamp": 35000, + "eventPayload": { + "keyOrObject": "value1" + } + } +} +``` + +#### Response + +```json +{ + "jsonrpc": "2.0", + "id": 42, + "result": "null" +} +``` + diff --git a/docs/api/_sidebar.md b/docs/api/_sidebar.md index bbaf88535..15e8de848 100644 --- a/docs/api/_sidebar.md +++ b/docs/api/_sidebar.md @@ -4,6 +4,7 @@ - [**Developer Guide**](developerguide/develperguidefornewplugin.md) - [**API Reference**](/README) - [ActivityMonitor](api/ActivityMonitorPlugin.md) + - [Analytics](api/AnalyticsPlugin.md) - [AVInput](api/AVInputPlugin.md) - [Bluetooth](api/BluetoothPlugin.md) - [CompositeInput](api/CompositeInputPlugin.md)