SDK integration-Enterprise Mobile Application Studio(EMAS)-阿里云帮助中心

This topic describes how to quickly integrate the software development kit (SDK) into your code to enable Web/H5 monitoring.

Preparations

You have created a project and an application. For more information, see Quick Start.

SDK integration

The SDK supports both CDN and NPM package connection types.

CDN connection

Step 1: Integrate the SDK

In the head tag of your HTML file, add a script tag to import the SDK resource file.

<script src="https://o.alicdn.com/alicloud-ams/alibabacloud-apm-h5-sdk/index.js"></script>

Note

The SDK uses a CDN overwrite publishing mechanism. This CDN resource always pulls the latest version of the SDK, so you do not need to perform manual updates.

Step 2: Configure and use the SDK

Mount in window mode

In this mode, the SDK is mounted under the EMAS namespace. EMAS.APM is the SDK constructor.

// SDK initialization
var apm = new window.EMAS.APM({
  appKey: 'appKey', // Assigned after you create an application in the EMAS console
  appSecret: 'appSecret', // Assigned after you create an application in the EMAS console
  appVersion: 'appVersion', // Application version number
  channel: 'channel', // Application channel number
  userNick: 'userNick', // User nickname
  userId: 'userId', // User ID
});

/**
*  Configure and start SDK features.
*  For plugin configuration details, see the SDK API documentation.
*/
var plugins = apm.start()

AMD mode

require(['@aliyun-emas/apm'], (APM) => {
  const apm = new APM({
    appKey: 'appKey', // Assigned after you create an application in the EMAS console
    appSecret: 'appSecret', // Assigned after you create an application in the EMAS console
    appVersion: 'appVersion', // Application version number
    channel: 'channel', // Application channel number
    userNick: 'userNick', // User nickname
    userId: 'userId', // User ID
  });

  /**
  *  Configure and start SDK features.
  *  For plugin configuration details, see the SDK API documentation.
  */
  const plugins = apm.start();


})

Note

The SDK uses the Universal Module Definition (UMD) specification. If an Asynchronous Module Definition (AMD) loader is present before the SDK resource is loaded, the SDK is not mounted on the window object. In this case, you must load the SDK using AMD.

NPM connection

Step 1: Integrate the SDK

npm install @alicloud-emas/apm

Note

If you use the NPM connection type, you must manually update the SDK version and publish your application. For more information about SDK version updates, see SDK Release Notes.

Step 2: Configure and use the SDK

import APM from '@alicloud-emas/apm';

// SDK initialization
const apm = new APM({
  appKey: 'appKey', // Assigned after you create an application in the EMAS console
  appSecret: 'appSecret', // Assigned after you create an application in the EMAS console
  appVersion: 'appVersion', // Application version number
  channel: 'channel', // Application channel number
  userNick: 'userNick', // User nickname
  userId: 'userId', // User ID
});

/**
*  Configure and start SDK features.
*  For plugin configuration details, see the SDK API documentation.
*/
const plugins = apm.start()

Note

For information about SDK and plugin configuration items, see SDK API.

Verify reported content

After the integration is complete, run the project. The integration is successful if a POST request to apm-gateway.aliyuncs.com/log/upload with a status of 200 appears in the Network tab of your browser.
Go to the console to view the reported page view (PV) and other data.

SPA application integration

When you integrate the SDK with a Single-Page Application (SPA), check whether page view (PV) data reporting needs to listen for the application's internal routing status.

Note

The SDK provides listeners for History and Hash routing. This feature is disabled by default and must be enabled manually.

History routing mode

// Initialize the SDK...

// Start the SDK and configure the PV plugin to enable routing listeners.
// If your SPA uses History routing, enable the History routing listener. The SDK then automatically reports PV data when you switch between subpages.
apm.start({
  pv: {
    enableHistory: true,
  }
})

Hash routing mode

// Initialize the SDK...

// Start the SDK and configure the PV plugin to enable routing listeners.
// If your SPA uses Hash routing, enable the Hash routing listener. The SDK then automatically reports PV data when you switch between subpages.
apm.start({
  pv: {
    enableHash: true,
  }
})

Manual reporting

If automatic route listening does not meet your requirements, you can use the manual reporting mode.

// Initialize the SDK...

// Start the SDK and get the PV plugin.
const {pv} = apm.start({
  pv: {
    autoPV: false, // To report PV data completely manually, you must disable autoPV.
  }
})

// Manually report PV data.
pv && pv.sendPV()