> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Web SDK Integration
> Integrate the MoEngage Web SDK on your website using script-based or manual initialization methods.
## Overview
You can integrate the Web SDK for any of the supported frameworks (CDN, NPM, GTM, SPA, AMP, Flutter, and Shopify) using one of the following two methods:
* **Script-based Initialization (Recommended):** Use the form-based interface to generate a validated code snippet or access module-specific configurations. For more information, refer to [Script-based Initialization (Recommended)](#script-based-initialization).
* **Manual Integration:** Manually configure the SDK parameters and initialization code. For more information, refer to [Option 2: Manual Integration](#manual-approach).
You must have your **Workspace ID (App ID)** and **Data Center**. You can retrieve these details by navigating to `Settings > App > General` on the Dashboard.
## Option 1: Script-based Initialization (Recommended)
To ensure a reliable and streamlined setup, we recommend using the **Script-based initialization** method. This method generates a validated JavaScript snippet, eliminating potential syntax errors and automatically including required flags based on the application type.
* **Workspace Details:** Ensure you have your **Workspace ID (App ID)** and **Data Center** (found in `Settings > App > General` on the Dashboard).
* **Service Worker (For Web Push):** If enabling Web Push, create a file named `serviceworker.js` in your **root directory**.
* **Whitelisting (CSP):** If your site uses a Content Security Policy, whitelist the necessary MoEngage URLs. For more information, refer [here](/developer-guide/web-sdk/web-sdk-integration/basic-integration/web-sdk-integration#Whitelisting-URLs).
Follow these steps to generate your initialization script:
1. Navigate to the [Web SDK Initialization Website.](https://app-cdn.moengage.com/sdk/integration/config/index.html)
2. Configure the values based on your application requirements. Refer to the [Configuration Parameters](#Configuration-Parameters) table below for detailed descriptions of each field.
3. Click **Generate Code** at the bottom of the form to create your validated JavaScript snippet.
4. Implement the Generated Code: Copy the code snippets displayed by the tool and paste them into your project as follows:
* **Update Service Worker (If Web Push Enabled):** Add the generated `importScripts(...)` line to the top of your `serviceworker.js` file.
* **HTML File Changes (If Web Personalization Enabled):** Add the generated `` tags and the Personalization `
```
```javascript With Portfolio wrap theme={null}
```
#### PRODUCTION or LIVE Integration
To integrate into the production or live environment:
1. Insert the following code in the `` tag of every page that requires tracking.
2. Replace "APP ID" available in the settings page of MoEngage Dashboard.\
Navigate to `Dashboard --> Settings --> App --> General` and copy the APP ID.
3. Replace the value of sdkVersion with the version of Web SDK you intend to use. It is recommended to use the format x (major)
4. Replace "DC" with the data center form the above table
5. If you have [*Portfolio*](https://www.moengage.com/docs/user-guide/settings/account/portfolio/portfolio) enabled for your workspace, you need to pass the `projectId` key and the projectID of you project as value.
```javascript Without Portfolio wrap theme={null}
```
```javascript With Portfolio wrap theme={null}
```
#### Upgrading the SDK
When you reference the MoEngage Web SDK from our content delivery network, for example, `https://cdn.moengage.com/release/{DC}/versions/{sdkVersion}/moe_webSdk.min.latest.js` where `sdkVersion = x` (using `sdkVersion = x`, i.e. fixing version only till major release is our default integration recommendation), your users will receive new features and bug fixes automatically when they refresh your site.
However, when we release major changes, we require you to upgrade the MoEngage Web SDK manually to ensure that nothing in your integration will be impacted by breaking changes.
You can keep up-to-date with our latest release following our [changelog](/release-notes/sdks/web) for a full accounting of our Web SDK release history. To upgrade the MoEngage Web SDK:
* Update the MoEngage library version by changing value of `sdkVersion` in the integration script.
* If you have web push integrated, update version in the serviceworker cdn url in the service worker file on your site - by default, this is located at `/serviceworker.js` at your site’s root directory, but the location may be customized in some integrations. `importScripts("https://cdn.moengage.com/release/{DC}/versions/[old-version-number]/serviceworker_cdn.min.latest.js");`
* If you have web personalisation integrated, update the version in the web personalisation script- `https://cdn.moengage.com/release/{DC}/versions/[old-version-number]/moe_webSdk_webp.min.latest.js?appId={workspace-id}`
These 3 integrations must be updated with the same version number for proper functionality. In case you are using NPM, use the version number of @moengage/web-sdk dependency that is in your package.json file.
### Method 2: Using NPM
If your site uses NPM or Yarn package managers, you can add the [Moengage NPM package](https://www.npmjs.com/package/@moengage/web-sdk) as a dependency.
```auto Add MoEngage NPM Package theme={null}
npm install --save @moengage/web-sdk
# or, using yarn:
# yarn add @moengage/web-sdk
```
Once installed, you can `import` or `require` the library in the typical fashion:
```javascript JavaScript wrap theme={null}
import moengage from "@moengage/web-sdk";
// or, using `require`
const moengage = require("@moengage/web-sdk");
```
Then, initialize it by passing the configurations in all the pages before using it:
```javascript JavaScript wrap theme={null}
moengage.initialize({
appId: 'XXXXXXXXXXXXXXXX',
env: 'LIVE',
logLevel: 0
});
```
You can pass any configuration here. For example,
* if you have [*Portfolio*](https://www.moengage.com/docs/user-guide/settings/account/portfolio/portfolio) enabled for your workspace, you need to pass the `projectId` key.
* if you want to change the integration settings for specialized projects, then pass it as shown in the following snippet:
```javascript JavaScript wrap theme={null}
moengage.initialize({
appId: 'XXXXXXXXXXXXXXXX',
projectId: 'your_projectId',
env: 'LIVE',
logLevel: 0
});
```
After that, you can use any method of the Moengage SDK, as shown in the snippet below:
```javascript JavaScript wrap theme={null}
moengage.add_email('abc@xyz.com')
```
If you wish to always use the latest version of the Web SDK (instead of the version of @moengage/web-sdk mentioned in your package manager), pass the property `useLatest` with value set to `true` in the configuration:
`moengage.initialize({appId: 'XXXXXXXXXXXXXXXX', useLatest: true});`
Use the version of Web SDK that you intend by altering the version of @moengage/web-sdk dependency in your package manager. More information on how to use specific version or range of versions can be found [here](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies).
## Whitelisting URLs
Optional step for all web modules
If your website is configured to block the external endpoints, then all the network calls to MoEngage fails.\
Ensure that you whitelist the following endpoints for smooth integration.
**script-src:**
* [https://cdn.moengage.com/](https://cdn.moengage.com/)
* [https://app-cdn.moengage.com/](https://app-cdn.moengage.com)
**image-src:**
* [https://moe-email-campaigns.s3.amazonaws.com/](https://moe-email-campaigns.s3.amazonaws.com/)
* [https://image.moengage.com/](https://image.moengage.com/)
* [https://image-eu.moengage.com/](https://image-eu.moengage.com/)
* [https://image-ap1.moengage.com/](https://image-ap1.moengage.com/)
* [https://image-04.moengage.com/](https://image-04.moengage.com/)
* [https://image-06.moengage.com/](https://image-06.moengage.com/)
* [https://image.moengage.com/all-campaign-images-moe-dc-100/](https://image.moengage.com/all-campaign-images-moe-dc-100/)
**connect-src:**
* [https://sdk-01.moengage.com/](https://sdk-01.moengage.com/)
* [https://sdk-02.moengage.com/](https://sdk-02.moengage.com/)
* [https://sdk-03.moengage.com/](https://sdk-03.moengage.com/)
* [https://sdk-04.moengage.com/](https://sdk-04.moengage.com/)
* [https://sdk-06.moengage.com/](https://sdk-06.moengage.com/)
**frame-src:**
* [https://cdn.moengage.com/](https://cdn.moengage.com/)
**style-src:**
* [https://cdn.moengage.com/](https://cdn.moengage.com/)
* [https://app-cdn.moengage.com/](https://app-cdn.moengage.com)
* [https://fonts.bunny.net/](https://fonts.bunny.net/)
**font-src:**
* [https://fonts.bunny.net/](https://fonts.bunny.net/)
You will get the error ***`Refused to connect to https://\*\*\*.moengage.com/\*\*\*\* because it violates the following Content Security Policy directive.`*** if you do not whitelist the URLs.
For more information, refer to [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).
## Troubleshooting
### Not able to debug SDK in the environment.
Check that the `logLevel` is set to `1` (or `2` for verbose) while initializing the MoEngage SDK.
### How to see SDK logs in Live environment?
Configure the `logLevel` to 1 while initializing the MoEngage SDK.
### What is the difference between TEST & LIVE environment?
MoEngage provides a staging environment referred to as the **TEST environment**. The **LIVE environment** contains data about your actual users/customers from your production website.
MoEngage Web SDK uses the `env` parameter to route data correctly:
* `env: 'TEST'`: Routes data to your Test dashboard.
* `env: 'LIVE'`: Routes data to your production dashboard.
You can independently control log verbosity using the `logLevel` parameter regardless of the environment selected.