Native Browser API Support

Overview

Native Browser API Support requires MoEngage Web SDK version 2.77.03 and later. Use a Native Browser API Support script version that is compatible with the MoEngage Web SDK version integrated in your application.

Integration

To enable Native Browser API Support, complete the following steps.

Step 1: Add the Native Browser API Support Script

Add the following script to your application. MoEngage recommends loading this script as early as possible, preferably in the <head> section of the page, before any application scripts or third-party libraries that may patch browser APIs.

HTML

<script src="https://cdn.moengage.com/release/{DATA_CENTER}/versions/latest/moe_webSdk_native_methods.min.latest.js"></script>

Replace {DATA_CENTER} with your MoEngage data center. To pin the script to a specific SDK version, replace latest in the URL with the latest version number.

The Native Browser API Support script must be loaded before any code that patches native browser APIs. If the script is loaded after the APIs are patched, it may capture the patched implementations instead of the original browser implementations.

Step 2: Enable Native Browser API Support

Set nativeMethodsUsed to true while initializing the MoEngage Web SDK.

JavaScript

Moengage = moe({
  appId: moeAppID,
  projectId: "your_projectId",
  nativeMethodsUsed: true
});

Loading the Native Browser API Support script without setting nativeMethodsUsed to true during initialization will not enable the Web SDK to use the preserved native browser APIs.

Angular Application Setup

Angular is one example of a framework where native browser APIs are commonly patched. Angular applications that use Zone.js patch browser APIs such as Promise, setTimeout, setInterval, and MutationObserver to track asynchronous operations and trigger change detection. For such applications, MoEngage recommends enabling Native Browser API Support using the following load order:

Native Browser API Support script
Zone.js
Angular application scripts
MoEngage Web SDK initialization with nativeMethodsUsed: true

Load the Native Browser API Support script in the <head> section, before Zone.js and Angular:

HTML

<head>
  <script src="https://cdn.moengage.com/release/{DATA_CENTER}/versions/latest/moe_webSdk_native_methods.min.latest.js"></script>

  <!-- Zone.js, Angular, and other application scripts should be loaded after this script -->
</head>

Initialize the MoEngage Web SDK with nativeMethodsUsed set to true.

JavaScript

Moengage = moe({
  appId: moeAppID,
  projectId: "your_projectId",
  nativeMethodsUsed: true
});

Load Order Requirements

Load scripts in the following order for Native Browser API Support to work as expected:

Native Browser API Support script
Framework or third-party scripts that may patch browser APIs
MoEngage Web SDK initialization with nativeMethodsUsed: true

If the Native Browser API Support script is loaded after a patching library, it may not capture the original browser implementations.

Behavior Without Native Browser API Support

If your application does not patch native browser APIs, there is no expected impact. However, if your application or a third-party library patches native browser APIs and Native Browser API Support is not enabled, the MoEngage Web SDK may use the patched implementations of those APIs. This may result in inconsistent or timing-related SDK behavior. Possible symptoms include:

SDK initialization taking longer than expected
SDK callbacks being delayed or not invoked as expected
In-app messages not rendering or triggering reliably
Push opt-in or subscription flows behaving inconsistently
Events not being queued, processed, or sent as expected
Behavior that occurs only in specific frameworks or environments
Differences in SDK behavior between a plain JavaScript environment and the actual application environment

This issue may not always produce a specific MoEngage error in the browser console. In many cases, developers may observe inconsistent SDK behavior instead of a clear JavaScript error.

When to Use Native Browser API Support

Native Browser API Support is recommended in the following cases:

Your application uses a framework or library that patches asynchronous browser APIs — for example, Angular applications using Zone.js. See Angular Application Setup.
SDK behavior is inconsistent only inside your application framework. See Behavior Without Native Browser API Support.
The SDK works as expected in a simple test page but behaves differently in your production application.
Browser console logs or stack traces show references to wrappers around timers, promises, or DOM observers.

How It Works

The Native Browser API Support script performs the following actions:

Captures the original browser implementations of supported APIs.
Stores these implementations before application or third-party code modifies them.
Allows the MoEngage Web SDK to use the preserved implementations internally when nativeMethodsUsed is enabled.

This reduces the impact of framework-level or third-party patching on MoEngage Web SDK functionality.

Troubleshooting

Inconsistent SDK Behavior After Enabling Native Browser API Support

Verify the following:

The Native Browser API Support script is loaded before any library that patches browser APIs. See Step 1.
nativeMethodsUsed is set to true during SDK initialization. See Step 2.
The script version is compatible with the Web SDK version.
The script is not blocked by Content Security Policy, ad blockers, or network restrictions.
The correct MoEngage data center and SDK version are used in the script URL.

Script Loaded but SDK Not Using Native Browser APIs

Ensure that the SDK is initialized with nativeMethodsUsed: true as described in Step 2. The support script alone does not enable the feature. The Web SDK uses preserved native browser APIs only when this configuration is enabled.

FAQ

Native Browser API Support Requirement for All Websites

No. Native Browser API Support is not required for all websites. It is intended for applications where native browser APIs are patched or overridden. For guidance on whether to enable this feature, see When to Use Native Browser API Support.

Impact on Application Behavior

No. This feature allows the MoEngage Web SDK to use preserved browser APIs internally. It does not modify application logic.

Browser Console Errors When the Feature Is Not Enabled

No. There may not be a specific browser console error. Developers may observe inconsistent SDK behavior instead. For details, see Behavior Without Native Browser API Support.

Loading the Support Script After a Patching Library

No. The support script must be loaded before any script that patches native browser APIs. If it is loaded after such scripts, it may capture already-patched implementations instead of the original browser implementations. For an example of the correct load order, see Angular Application Setup.

Enabling nativeMethodsUsed Without the Support Script

No. Enable nativeMethodsUsed only when the Native Browser API Support script is loaded correctly. See Step 1 and Step 2.

APIs Preserved by This Feature

The feature preserves supported native browser APIs used by the MoEngage Web SDK, including:

Promise
setTimeout
clearTimeout
setInterval
clearInterval
MutationObserver

Sample Implementation

HTML

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.moengage.com/release/{DATA_CENTER}/versions/latest/moe_webSdk_native_methods.min.latest.js"></script>

    <!-- Load framework and application scripts after this script -->
  </head>

  <body>
    <script>
      Moengage = moe({
        appId: moeAppID,
        projectId: "your_projectId",
        nativeMethodsUsed: true
      });
    </script>
  </body>
</html>

​Overview

​Integration

​Step 1: Add the Native Browser API Support Script

​Step 2: Enable Native Browser API Support

​Angular Application Setup

​Load Order Requirements

​Behavior Without Native Browser API Support

​When to Use Native Browser API Support

​How It Works

​Troubleshooting

​Inconsistent SDK Behavior After Enabling Native Browser API Support

​Script Loaded but SDK Not Using Native Browser APIs

​FAQ

​Sample Implementation

Overview

Integration

Step 1: Add the Native Browser API Support Script

Step 2: Enable Native Browser API Support

Angular Application Setup

Load Order Requirements

Behavior Without Native Browser API Support

When to Use Native Browser API Support

How It Works

Troubleshooting

Inconsistent SDK Behavior After Enabling Native Browser API Support

Script Loaded but SDK Not Using Native Browser APIs

FAQ

Sample Implementation