{"id":20254571,"url":"https://github.com/guancecloud/datakit-js","last_synced_at":"2025-07-06T06:36:15.683Z","repository":{"id":57102592,"uuid":"372485597","full_name":"GuanceCloud/datakit-js","owner":"GuanceCloud","description":"DataFlux RUM Web side data indicator monitoring","archived":false,"fork":false,"pushed_at":"2024-06-25T10:24:10.000Z","size":3183,"stargazers_count":52,"open_issues_count":1,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-12-08T09:50:27.530Z","etag":null,"topics":["datakit","javascript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GuanceCloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-31T11:39:22.000Z","updated_at":"2024-10-18T03:40:58.000Z","dependencies_parsed_at":"2024-11-01T09:02:55.503Z","dependency_job_id":null,"html_url":"https://github.com/GuanceCloud/datakit-js","commit_stats":{"total_commits":382,"total_committers":2,"mean_commits":191.0,"dds":0.2958115183246073,"last_synced_commit":"13824d9f339d633187c842b8cc47efdc376588c7"},"previous_names":["dataflux-cn/datakit-js"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuanceCloud%2Fdatakit-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuanceCloud%2Fdatakit-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuanceCloud%2Fdatakit-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuanceCloud%2Fdatakit-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GuanceCloud","download_url":"https://codeload.github.com/GuanceCloud/datakit-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230388131,"owners_count":18217755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datakit","javascript"],"created_at":"2024-11-14T10:33:43.661Z","updated_at":"2025-07-06T06:36:15.677Z","avatar_url":"https://github.com/GuanceCloud.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Guance RUM SDK Quick Start Guide\n\n## Overview\n\nGuance RUM SDK (Real User Monitoring) provides a powerful set of tools for monitoring and analyzing the behavior and performance of real users in web applications. This quick start guide will help you integrate the RUM SDK into your web application quickly, distinguishing between DK method integration and public DataWay integration, and detailing how to add custom data TAGs.\n\n## Prerequisites\n\n- **Install DataKit**: Ensure that DataKit is installed and configured to be publicly accessible (for DK method integration) .\n- **Configure RUM Collector**: Follow the Guance documentation to configure the RUM collector .\n\n## Integration Methods\n\n### 1. DK Method Integration\n\n- Ensure that DataKit is installed and configured to be publicly accessible.\n- Obtain parameters such as `applicationId`, `env`, `version` from the Guance console Create Application.\n- When integrating the SDK, configure `datakitOrigin` with the domain name or IP of DataKit.\n\n### 2. Public OpenWay Integration\n\n- Log in to the Guance console, go to the **Synthetic Tests** page, click on **Create Application** in the top-left corner, and obtain parameters like `applicationId`, `clientToken`, and `site`. Create Application\n- Configure `site` and `clientToken` parameters, supporting SourceMap uploads via the console.\n- When integrating the SDK, there's no need to configure `datakitOrigin`; the SDK will send data to the public DataWay by default.\n\n## SDK Integration\n\n### NPM Integration\n\nInstall and import the SDK in your front-end project:\n\n```bash\nnpm install @cloudcare/browser-rum\n```\n\nInitialize the SDK in your project:\n\n```javascript\nimport { datafluxRum } from '@cloudcare/browser-rum'\n\ndatafluxRum.init({\n  applicationId: 'Your Application ID',\n  datakitOrigin: '\u003cDataKit Domain Name or IP\u003e', // Required for DK method integration\n  clientToken: 'clientToken', // Required for public OpenWay integration\n  site: 'Public OpenWay URL', // Required for public OpenWay integration\n  env: 'production',\n  version: '1.0.0',\n  sessionSampleRate: 100,\n  sessionReplaySampleRate: 70,\n  trackUserInteractions: true\n  // Other optional configurations...\n})\n\n// Enable session replay recording\ndatafluxRum.startSessionReplayRecording()\n```\n\n### Asynchronous CDN Loading\n\nAdd the script to your HTML file:\n\n```html\n\u003cscript\u003e\n  ;(function (h, o, u, n, d) {\n    h = h[d] = h[d] || {\n      q: [],\n      onReady: function (c) {\n        h.q.push(c)\n      }\n    }\n    ;(d = o.createElement(u)), (d.async = 1), (d.src = n)\n    n = o.getElementsByTagName(u)[0]\n    n.parentNode.insertBefore(d, n)\n  })(\n    window,\n    document,\n    'script',\n    'https://static.guance.com/browser-sdk/v3/dataflux-rum.js',\n    'DATAFLUX_RUM'\n  )\n\n  window.DATAFLUX_RUM.onReady(function () {\n    window.DATAFLUX_RUM.init({\n      applicationId: 'Your Application ID',\n      datakitOrigin: '\u003cDataKit Domain Name or IP\u003e', // Required for DK method integration\n      clientToken: 'clientToken', // Required for public OpenWay integration\n      site: 'Public OpenWay URL', // Required for public OpenWay integration\n      env: 'production',\n      version: '1.0.0',\n      sessionSampleRate: 100,\n      sessionReplaySampleRate: 70,\n      trackUserInteractions: true\n      // Other configurations...\n    })\n    // Enable session replay recording\n    window.DATAFLUX_RUM.startSessionReplayRecording()\n  })\n\u003c/script\u003e\n```\n\n### Synchronous CDN Loading\n\nAdd the script to your HTML file:\n\n```html\n\u003cscript\n  src=\"https://static.guance.com/browser-sdk/v3/dataflux-rum.js\"\n  type=\"text/javascript\"\n\u003e\u003c/script\u003e\n\u003cscript\u003e\n  window.DATAFLUX_RUM \u0026\u0026\n    window.DATAFLUX_RUM.init({\n      applicationId: 'Your Application ID',\n      datakitOrigin: '\u003cDataKit Domain Name or IP\u003e', // Required for DK method integration\n      clientToken: 'clientToken', // Required for public OpenWay integration\n      site: 'Public OpenWay URL', // Required for public OpenWay integration\n      env: 'production',\n      version: '1.0.0',\n      sessionSampleRate: 100,\n      sessionReplaySampleRate: 70,\n      trackUserInteractions: true\n      // Other configurations...\n    })\n  // Enable session replay recording\n  window.DATAFLUX_RUM \u0026\u0026 window.DATAFLUX_RUM.startSessionReplayRecording()\n\u003c/script\u003e\n```\n\n## Custom Data TAG Addition\n\nUse the `setGlobalContextProperty` or `setGlobalContext` API to add extra TAGs to all RUM events [Add custom tag](./docs/rum/custom-sdk/add-additional-tag.md).\n\n### Example\n\n```javascript\n// Add a single TAG using setGlobalContextProperty\nwindow.DATAFLUX_RUM \u0026\u0026\n  window.DATAFLUX_RUM.setGlobalContextProperty('userName', 'John Doe')\n\n// Add multiple TAGs using setGlobalContext\nwindow.DATAFLUX_RUM \u0026\u0026\n  window.DATAFLUX_RUM.setGlobalContext({\n    userAge: 28,\n    userGender: 'Male'\n  })\n```\n\nWith the above code, you can add `userName`, `userAge`, and `userGender` TAGs to all RUM events.\n\n## Tracking User Actions\n\n### Control Whether to Enable Action Collection\n\nControl whether to collect user click actions through the `trackUserInteractions` initialization parameter.\n\n### Customize Action Names\n\n- Customize Action names by adding the `data-guance-action-name` attribute or `data-custom-name` (depending on the `actionNameAttribute` configuration) to clickable elements.\n\n### Use `addAction` API to Customize Actions\n\n```javascript\n// Synchronous CDN loading\nwindow.DATAFLUX_RUM \u0026\u0026\n  window.DATAFLUX_RUM.addAction('cart', {\n    amount: 42,\n    nb_items: 2,\n    items: ['socks', 't-shirt']\n  })\n\n// Asynchronous CDN loading\nwindow.DATAFLUX_RUM.onReady(function () {\n  window.DATAFLUX_RUM.addAction('cart', {\n    amount: 42,\n    nb_items: 2,\n    items: ['socks', 't-shirt']\n  })\n})\n\n// NPM\nimport { datafluxRum } from '@cloudcare/browser-rum'\ndatafluxRum \u0026\u0026\n  datafluxRum.addAction('cart', {\n    amount: 42,\n    nb_items: 2,\n    items: ['socks', 't-shirt']\n  })\n```\n\n## Custom Error Addition\n\nUse the `addError` API to add custom Error Metrics data [Add custom Error](./docs/rum/custom-sdk/add-error.md).\n\n```javascript\n// Synchronous CDN loading\nconst error = new Error('Something wrong occurred.')\nwindow.DATAFLUX_RUM \u0026\u0026 DATAFLUX_RUM.addError(error, { pageStatus: 'beta' })\n\n// Asynchronous CDN loading\nwindow.DATAFLUX_RUM.onReady(function () {\n  const error = new Error('Something wrong occurred.')\n  window.DATAFLUX_RUM.addError(error, { pageStatus: 'beta' })\n})\n\n// NPM\nimport { datafluxRum } from '@cloudcare/browser-rum'\nconst error = new Error('Something wrong occurred.')\ndatafluxRum.addError(error, { pageStatus: 'beta' })\n```\n\n## Custom User Identification\n\nUse the `setUser` API to add identification attributes (such as ID, name, email) for the current user [Add custom user information](./docs/rum/custom-sdk/user-id.md).\n\n```javascript\n// Synchronous CDN loading\nwindow.DATAFLUX_RUM \u0026\u0026\n  window.DATAFLUX_RUM.setUser({\n    id: '1234',\n    name: 'John Doe',\n    email: 'john@doe.com'\n  })\n\n// Asynchronous CDN loading\nwindow.DATAFLUX_RUM.onReady(function () {\n  window.DATAFLUX_RUM.setUser({\n    id: '1234',\n    name: 'John Doe',\n    email: 'john@doe.com'\n  })\n})\n\n// NPM\nimport { datafluxRum } from '@cloudcare/browser-rum'\ndatafluxRum.setUser({ id: '1234', name: 'John Doe', email: 'john@doe.com' })\n```\n\n## Session Replay Configuration\n\n### Ensure SDK Version Support\n\nEnsure that the SDK version you are using supports session replay functionality (usually versions `\u003e 3.0.0`).\n\n### Enable Session Replay Recording\n\nAfter initializing the SDK, call the `startSessionReplayRecording()` method to enable session replay recording. You can choose to enable it under specific conditions, such as after user login [Enable session recording](./docs/replay.md).\n\n## Important Notes\n\n- Session replay does not support playing elements like iframes, videos, audio, and canvases.\n- Ensure static resources (such as fonts, images) remain accessible during replay, which may require setting up CORS policies.\n- For CSS styles and mouse hover events, ensure CSS rules can be accessed via the CSSStyleSheet interface.\n\n## Debugging and Optimization\n\n- Use the logging and monitoring tools provided by the SDK to debug and optimize your application performance.\n- Adjust parameters like `sessionSampleRate` and `sessionReplaySampleRate` based on business needs to optimize data collection.\n\nBy following these steps, you can successfully integrate the Guance RUM SDK into your web application and start collecting data and using session replay features to optimize user experience and performance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguancecloud%2Fdatakit-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguancecloud%2Fdatakit-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguancecloud%2Fdatakit-js/lists"}