diff --git a/.github/workflows/deploy-npm.yml b/.github/workflows/deploy-npm.yml index 1f59892fa..fbe84bdf0 100644 --- a/.github/workflows/deploy-npm.yml +++ b/.github/workflows/deploy-npm.yml @@ -98,9 +98,18 @@ jobs: new_npm_version_sw=$(npm show @rudderstack/analytics-js-service-worker version 2>/dev/null || echo "not found") echo "NEW_NPM_VERSION_SW=$new_npm_version_sw" >> $GITHUB_ENV + - name: Debug environment variables + continue-on-error: true + run: | + echo "CURRENT_NPM_VERSION=${{ env.CURRENT_NPM_VERSION }}" + echo "NEW_NPM_VERSION=${{ env.NEW_NPM_VERSION }}" + echo "CURRENT_NPM_VERSION_SW=${{ env.CURRENT_NPM_VERSION_SW }}" + echo "NEW_NPM_VERSION_SW=${{ env.NEW_NPM_VERSION_SW }}" + - name: Send message to Slack channel - if: ${{ env.CURRENT_NPM_VERSION != env.NEW_NPM_VERSION && env.NEW_NPM_VERSION != 'not found'}} + if: env.CURRENT_NPM_VERSION != env.NEW_NPM_VERSION && env.NEW_NPM_VERSION != 'not found' id: slack + continue-on-error: true uses: slackapi/slack-github-action@v1.26.0 env: SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} @@ -148,8 +157,9 @@ jobs: } - name: Send message to Slack channel for Service Worker - if: ${{ env.CURRENT_NPM_VERSION_SW != env.NEW_NPM_VERSION_SW && env.NEW_NPM_VERSION_SW != 'not found'}} + if: env.CURRENT_NPM_VERSION_SW != env.NEW_NPM_VERSION_SW && env.NEW_NPM_VERSION_SW != 'not found' id: slackSw + continue-on-error: true uses: slackapi/slack-github-action@v1.26.0 env: SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} diff --git a/.github/workflows/deploy-sanity-suite.yml b/.github/workflows/deploy-sanity-suite.yml index 92df0d7f5..3b6b0a7a5 100644 --- a/.github/workflows/deploy-sanity-suite.yml +++ b/.github/workflows/deploy-sanity-suite.yml @@ -141,6 +141,7 @@ jobs: - name: Send message to Slack channel id: slack uses: slackapi/slack-github-action@v1.26.0 + continue-on-error: true env: SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} PROJECT_NAME: 'Sanity suite - ${{ inputs.environment }}' diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 454691d6b..6db4fbb54 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -171,13 +171,14 @@ jobs: - name: Send message to Slack channel id: slack + continue-on-error: true uses: slackapi/slack-github-action@v1.26.0 env: SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} - PROJECT_NAME: 'JS SDK Browser Package${{ inputs.action_type }} - ${{ inputs.environment }}' - CDN_URL: 'https://cdn.rudderlabs.com/${{ inputs.s3_dir_path }}/modern/rsa.min.js' + PROJECT_NAME: ${{ format('JS SDK Browser Package {0} - {1}', inputs.action_type, inputs.environment) }} + CDN_URL: ${{ format('https://cdn.rudderlabs.com/{0}/modern/rsa.min.js', inputs.s3_dir_path) }} RELEASES_URL: 'https://github.com/rudderlabs/rudder-sdk-js/releases/tag/@rudderstack/analytics-js@' - LINK_TEXT: ${{ inputs.environment == 'development' && 'Development' || ((inputs.environment == 'staging' && format('v{0} - Staging', env.CURRENT_VERSION_VALUE)) || format('v{0}', env.CURRENT_VERSION_VALUE)) }} + LINK_TEXT: ${{ (inputs.environment == 'development' && 'Development') || (inputs.environment == 'staging' && format('v{0} - Staging', env.CURRENT_VERSION_VALUE)) || format('v{0}', env.CURRENT_VERSION_VALUE) }} with: channel-id: ${{ secrets.SLACK_RELEASE_CHANNEL_ID }} payload: | @@ -206,9 +207,9 @@ jobs: "alt_text": "JavaScript Icon" } } - ${{ inputs.environment == 'production' && format(',{"type": "context", "elements": [{"type": "mrkdwn", "text": "For more details, check the full release notes <{0}{1}|here>."}]}', env.RELEASES_URL, env.CURRENT_VERSION_VALUE) || '' }} + ${{ inputs.environment == 'production' && format(',{{"type": "context", "elements": [{{"type": "mrkdwn", "text": "For more details, check the full release notes <{0}{1}|here>."}}]}}', env.RELEASES_URL, env.CURRENT_VERSION_VALUE) || '' }} ] - } + } # Below steps are for v1.1 SDK (legacy) diff --git a/.github/workflows/draft-new-release.yml b/.github/workflows/draft-new-release.yml index bdf523f58..85da00d5e 100644 --- a/.github/workflows/draft-new-release.yml +++ b/.github/workflows/draft-new-release.yml @@ -100,4 +100,3 @@ jobs: github_token: ${{ secrets.PAT }} pr_title: 'chore(release): pull ${{ steps.create-release.outputs.branch_name }} into main' pr_body: ':crown: *An automated PR*' - pr_reviewer: 'MoumitaM,saikumarrs' diff --git a/.github/workflows/publish-new-release.yml b/.github/workflows/publish-new-release.yml index 47ea755cf..a3f9458aa 100644 --- a/.github/workflows/publish-new-release.yml +++ b/.github/workflows/publish-new-release.yml @@ -98,7 +98,6 @@ jobs: github_token: ${{ secrets.PAT }} pr_title: 'chore(release): pull main into develop post release v${{ steps.extract-version.outputs.release_version }}' pr_body: ':crown: *An automated PR*' - pr_reviewer: 'MoumitaM,saikumarrs' - name: Delete hotfix release branch uses: koj-co/delete-merged-action@master @@ -118,6 +117,7 @@ jobs: - name: Send message to Slack channel id: slack + continue-on-error: true uses: slackapi/slack-github-action@v1.26.0 env: SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} diff --git a/.gitignore b/.gitignore index 208b7ffa8..b58ba7f42 100644 --- a/.gitignore +++ b/.gitignore @@ -84,3 +84,4 @@ tsconfig.build.tsbuildinfo *.zip .nx/cache +.nx/workspace-data diff --git a/.prettierignore b/.prettierignore index 6c87b6039..2d30234d3 100644 --- a/.prettierignore +++ b/.prettierignore @@ -14,4 +14,5 @@ examples/chrome-extension/**/foreground.js examples/**/index.html **/public/index.html -/.nx/cache \ No newline at end of file +/.nx/cache +/.nx/workspace-data \ No newline at end of file diff --git a/README.md b/README.md index 830b05cd9..8b18ad56f 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ The JavaScript SDK lets you track customer event data from your website and send - [**Usage in Chrome Extensions**](#usage-in-chrome-extensions) - [**Usage in Serverless Runtimes**](#usage-in-serverless-runtimes) -| **IMPORTANT**: The service worker export has been deprecated from the RudderStack JavaScript SDK npm package and moved to a new package.
If you still wish to use it for your project, see [**@rudderstack/analytics-js-service-worker package**](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker). | +| **IMPORTANT**: The service worker export has been deprecated from the RudderStack JavaScript SDK NPM package and moved to a new package.
If you still wish to use it for your project, see [**@rudderstack/analytics-js-service-worker package**](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker). | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ## Installing the JavaScript SDK @@ -47,53 +47,59 @@ The JavaScript SDK lets you track customer event data from your website and send | For detailed installation steps, see the [JavaScript SDK documentation](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/installation/). | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +### Using CDN + To integrate the JavaScript SDK with your website, place the following code snippet in the `` section of your website. ```javascript ```
-> The above snippet lets you integrate the SDK with your website and load it asynchronously to keep your page load time unaffected. +> The above snippet lets you integrate the SDK with your website and load it asynchronously to avoid impacting the performance of your webpages. To load SDK script on to your page synchronously, see the [**JavaScript SDK documentation**](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/installation/#synchronous-loading). -> **IMPORTANT**: The implicit `page` call at the end of the snippet (present in the previous JavaScript SDK versions) is removed in the latest SDK v3. You need to make a `page` call explicitly, if required, as shown below: +> **IMPORTANT**: The implicit `page` call at the end of the snippet (present in the previous JavaScript SDK versions) is removed in the latest SDK (v3). You need to make a `page` call explicitly, if required, as shown below: ```javascript rudderanalytics.page(); ``` -### NPM installation +### Using NPM Although we recommend using the CDN installation method to use the JavaScript SDK with your website, you can also use this [**NPM module**](https://www.npmjs.com/package/@rudderstack/analytics-js) to package RudderStack directly into your project. -To install the SDK via npm, run the following command: +To install the SDK via NPM, run the following command: ```bash npm install @rudderstack/analytics-js --save ``` **Note that this NPM module is only meant to be used for a browser installation**. If you want to integrate RudderStack with your Node.js application, see the [**RudderStack Node.js documentation**](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-node-sdk/). -

**IMPORTANT**: Since the module exports the [**related APIs**](#exported-apis) on an already-defined object combined with the Node.js module caching, you should run the following code snippet only once and use the exported object throughout your project: @@ -102,10 +108,10 @@ npm install @rudderstack/analytics-js --save ```javascript import { RudderAnalytics } from '@rudderstack/analytics-js'; -const rudderAnalytics = new RudderAnalytics(); -rudderAnalytics.load(WRITE_KEY, DATA_PLANE_URL, {}); +const rudderanalytics = new RudderAnalytics(); +rudderAnalytics.load(, , {}); -export { rudderAnalytics }; +export { rudderanalytics }; ``` - **For CJS using the `require` method**: @@ -114,85 +120,40 @@ export { rudderAnalytics }; var RudderAnalytics = require('@rudderstack/analytics-js'); const rudderAnalytics = new RudderAnalytics(); -rudderAnalytics.load(WRITE_KEY, DATA_PLANE_URL, {}); +rudderAnalytics.load(, , {}); exports.rudderanalytics = rudderAnalytics; ``` ### Sample implementations -See the following projects for a detailed walkthrough of the above steps: - -- [**Sample Angular project**](https://github.com/rudderlabs/rudder-analytics-angular) -- [**Sample React project**](https://github.com/rudderlabs/rudder-analytics-react) - -### Exported APIs - -The APIs exported by the module are: - -- `load` -- `ready` -- `identify` -- `page` -- `track` -- `group` -- `alias` -- `reset` -- `setAnonymousId` -- `startSession` -- `endSession` - -See [JavaScript SDK installation workflow](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/installation/#installation-workflow) for more information on these methods. +See the following applications for a detailed walkthrough of the above steps: -### Supported browser versions +- [**Sample Angular application**](https://github.com/rudderlabs/rudder-sdk-js/tree/main/examples/angular/) +- [**Sample React application**](https://github.com/rudderlabs/rudder-sdk-js/tree/main/examples/reactjs/) -| **Browser** | **Supported Versions** | -| :-------------- | :--------------------- | -| **Browser** | **Supported Versions** | -| :-------------- | :--------------------- | -| Safari | v7 and above | -| IE | v11 and above | -| Edge | v80 and above | -| Mozilla Firefox | v47 and above | -| Chrome | v54 and above | -| Opera | v43 and above | - -> You can try adding the browser [polyfills](https://developer.mozilla.org/en-US/docs/Glossary/Polyfill) to your application if the SDK does not work on your browser. +See the `examples` directory in this repository for more sample applications for different frameworks. ## Migrating SDK from an older version -If you are migrating the JavaScript SDK from an older version (<=v1.1), see the [Migration Guide](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/migration-guide/) for details. +If you are migrating the JavaScript SDK from an older version (<= v1.1), see the [Migration Guide](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/migration-guide/) for details. ## Loading the SDK -| For detailed information on the `load()` method, see the [**JavaScript SDK documentation**](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk/). | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| For detailed information on the `load` API, see the [**JavaScript SDK documentation**](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk/). | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -You can load the JavaScript SDK using the `load` API method to track and send events from your website to RudderStack. Make sure to replace the "write key" and data plane URL with their actual values. +You can load the JavaScript SDK using the `load` API to track and send events from your website to RudderStack. Make sure to replace the write key and data plane URL with their actual values. ```javascript rudderanalytics.load(, , [loadOptions]); ``` -You can use the [`loadOptions`](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk/#loading-options) object in the above `load` call to define various options while loading the SDK. - -For destinations where you don't want the SDK to load the third-party scripts separately, modify the `load` call as shown: - -```javascript -rudderanalytics.load( , , { - loadIntegration: false -}) -``` - -A few important things to note: - -- The SDK expects the destination global queue or function for pushing the events is already present for the particular destinations. -- Currently, `loadIntegration` is supported only for Amplitude and Google Analytics. -- The JavaScript SDK expects `window.amplitude` and `window.ga` to be already defined by the user separately for the sending the events to these destinations. +You can use the [`loadOptions`](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk/#loading-options) object in the above `load` call to define various [options](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk/#loading-options) while loading the SDK. ## Identifying users -The [`identify`](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#identify) call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc. +The [`identify`](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#identify) API lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc. A sample `identify` call is shown below: @@ -215,22 +176,22 @@ rudderanalytics.identify( }, }, () => { - console.log('identify call'); + console.log('Identify call is successful.'); }, ); ``` -In the above example, the JavaScript SDK captures the user information like `userId`, `firstName`, `lastName`, `email`, and `phone`, along with the [**contextual information**](https://www.rudderstack.com/docs/event-spec/standard-events/common-fields/#contextual-fields). +In the above example, the JavaScript SDK captures the user information like `userId`, `firstName`, `lastName`, `email`, and `phone`, along with the default [**contextual information**](https://www.rudderstack.com/docs/event-spec/standard-events/common-fields/#contextual-fields). -> There is no need to call `identify()` for anonymous visitors to your website. Such visitors are automatically assigned an `anonymousId`. +> There is no need to call `identify` API for anonymous visitors to your website. Such visitors are automatically assigned an `anonymousId`. -See the [**JavaScript SDK documentation**](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#identify) for more information on how to use the `identify` call. +See the [**JavaScript SDK documentation**](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#identify) for more information on how to use the `identify` API. ## Tracking user actions -The [`track`](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#track) call lets you capture the user events along with any associated properties. +The [`track`](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#track) API lets you capture the user events along with any associated properties. -A sample `track` call is shown below: +A sample `track` API is shown below: ```javascript rudderanalytics.track( @@ -241,27 +202,47 @@ rudderanalytics.track( user_actual_id: 12345, }, () => { - console.log('track call'); + console.log('Track call is successful.'); }, ); ``` -In the above example, the `track` method tracks the user event ‘**Order Completed**’ and information like the `revenue`, `currency`, etc. +In the above example, the `track` API tracks the user event `Order Completed` and information like the `revenue`, `currency`, etc. -> You can use the `track` method to track various success metrics for your website like user signups, item purchases, article bookmarks, and more. +> You can use the `track` API to track various success metrics for your website like user signups, item purchases, article bookmarks, and more. -## The `ready` API +## Ready state -There are cases when you may want to tap into the features provided by the end-destination SDKs to enhance tracking and other functionalities. The JavaScript SDK exposes a `ready` API with a `callback` parameter that fires when the SDK is done initializing itself and the other third-party native SDK destinations. +There are cases when you may want to tap into the features provided by the end-destination SDKs to enhance tracking and other functionalities. The JavaScript SDK exposes a [`ready`](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#ready-api) API with a `callback` parameter that fires when the SDK is done initializing itself and the device-mode destinations. An example is shown in the following snippet: ```javascript rudderanalytics.ready(() => { - console.log('we are all set!!!'); + console.log('We are all set!!!'); }); ``` +### Loaded state + +Alternatively, if you just want to wait for the SDK to load, you can use the [`onLoaded`](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk/#onloaded) load API option to configure a callback function. + +The configured callback function is executed when the SDK has loaded successfully but before all the device-mode destinations are initialized. + +This is especially helpful to query information from the SDK after it has loaded to use it elsewhere. For example, you can retrieve the anonymous ID generated by the SDK after it has loaded. + +An example is shown in the following snippet: + +```javascript +rudderanalytics.load(, , { + onLoaded: () => { + console.log('SDK has loaded.'); + console.log('Anonymous ID:', rudderanalytics.getAnonymousId()); + }, +}); + +``` + > For more information on the other supported methods, see the [**JavaScript SDK APIs**](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/). ## [](https://github.com/rudderlabs/rudder-sdk-js/blob/main/README.md#self-hosted-control-plane)Self-hosted control plane @@ -279,35 +260,29 @@ rudderanalytics.load(, , { More information on obtaining the `CONTROL_PLANE_URL` can be found [**here**](https://www.rudderstack.com/docs/get-started/rudderstack-open-source/control-plane-lite/#using-sdk-sources-set-up-in-self-hosted-control-plane). -## Adding your own integrations - -You can start adding integrations of your choice for sending the data through their respective web (JavaScript) SDKs. - ## How to build the SDK - Look for run scripts in the `package.json` file for getting the browser minified and non-minified builds. The builds are updated in the `dist` folder of the directory. Among the others, some of the important ones are: - - `npm run build:browser`: This outputs **dist/cdn/legacy/rudder-analytics.min.js**. - - `npm run build:npm`: This outputs **dist/npm** folder that contains the npm package contents. - - `npm run build:integration:all`: This outputs **dist/cdn/legacy** folder that contains the integrations. + - `npm run build:browser`: This outputs the **dist/cdn/legacy/rsa.min.js**. + - `npm run build:npm`: This outputs the **dist/npm** folder that contains the NPM package contents. + - `npm run build:integration:all`: This outputs the **dist/cdn/legacy** folder that contains the integrations. -> We use **rollup** to build our SDKs. The configuration for it is present in `rollup-configs` folder. +> We use **rollup** to build our SDKs. The configuration for it is present in the `rollup-configs` directory. - For adding or removing integrations, modify the imports in `index.js` under the `src/integrations` folder. ## Usage in Chrome extensions -You can use the JavaScript SDK in Chrome Extensions with manifest v3, both as a content script (via the JavaScript SDK package) -or as a background script service worker (via the [service worker package](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker)). +You can use the JavaScript SDK in Chrome Extensions with manifest v3, both as a content script (via the JavaScript SDK package) or as a background script service worker (via the [service worker package](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker)). -For examples and specific details, see [Chrome Extensions Usage](https://github.com/rudderlabs/rudder-sdk-js/blob/main/examples/chrome-extension/USAGE.md). +For more details, see [Chrome Extensions Usage](https://github.com/rudderlabs/rudder-sdk-js/blob/main/examples/chrome-extension/USAGE.md). ## Usage in Serverless runtimes -RudderStack JS SDK [service worker](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker) can be used -in serverless runtimes like Cloudflare Workers or Vercel Edge functions. +RudderStack JS SDK [service worker](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker) can be used in serverless runtimes like Cloudflare Workers or Vercel Edge functions. -For examples and specific details look into: +For more details, see: - [Vercel Edge Usage](https://github.com/rudderlabs/rudder-sdk-js/blob/main/examples/serverless/USAGE.md) - [Cloudflare Worker Usage](https://github.com/rudderlabs/rudder-sdk-js/blob/main/examples/serverless/USAGE.md) diff --git a/examples/angular/sample-app/src/index.html b/examples/angular/sample-app/src/index.html index a7f0a86d5..bf0494e29 100644 --- a/examples/angular/sample-app/src/index.html +++ b/examples/angular/sample-app/src/index.html @@ -9,7 +9,7 @@