Device SDK integration for Alipay mini program - Fraud Detection

Integrate the Fraud Detection device SDK into your Alipay mini program to collect device fingerprints and detect device spoofing, batch registration, and malicious logon in registration, logon, and marketing scenarios.

Note

This guide covers frontend SDK integration only. After completing these steps, call the Fraud Detection API operations from your backend to evaluate device risk. See What's next for backend API references.

Prerequisites

Before you begin, make sure you have:

An Alipay mini program. See the Alipay mini program developer guide for setup instructions.
An AppKey from the Fraud Detection console.

How it works

Import the SDK into your mini program's index page and mount the AliyunFP object globally.
Add the required feilin-view node to your page's axml template.
Call AliyunFP.init() in onReady to start collecting device data.
Call AliyunFP.getToken() when a business event occurs (such as logon, registration, or ordering) to retrieve a deviceToken.
Pass the deviceToken to your backend, which calls the Fraud Detection API for device risk evaluation.

Integrate the SDK

Step 1: Download and import the SDK

Download the Alipay mini program SDK. Import it in your mini program's first-screen index page and mount the AliyunFP object globally so other pages can access it.

import * as AliyunFP from './feilin.alipay.xxx.js';
const app = getApp();
app.AliyunFP = AliyunFP;

Step 2: Add the required view node

Before calling any SDK method, add the feilin-view node to your page's axml template. The SDK uses this node internally for device data collection.

<view>
  <view> Business UI layout </view>

  <view id="feilin-view" style="position:fixed;top:99999rpx;">
    <canvas id="feilin-canvas" type="2d" style="width:150px;height:150px;"></canvas>
    <canvas id="feilin-webgl" type="webgl" style="width:150px;height:150px;"></canvas>
  </view>
</view>

Step 3: Initialize the SDK

Important

Initialize the SDK in onReady, as early in the page lifecycle as possible. Allow at least 1 second between AliyunFP.init() and AliyunFP.getToken().

Call AliyunFP.init() with your configuration parameters:

Page({
  onReady() {
    AliyunFP.init(
      {
        appKey: '<your-app-key>',
        appName: '<your-mini-program-name>',
        openId: '<alipay-user-id>',        // Optional but recommended
        endpoints: [
          'https://cloudauth-device.aliyuncs.com',
          'https://cn-shanghai.device.saf.aliyuncs.com'
        ],
      },
      (initStatus, deviceToken) => {
        console.log("initStatus:" + initStatus + "  deviceToken:" + deviceToken);
      }
    );
  }
});

Parameters

Parameter	Required	Default	Description
`appKey`	Yes	—	Your application key from the Fraud Detection console
`appName`	Yes	—	Your mini program name, defined by you
`openId`	No (recommended)	—	Alipay mini program user ID
`endpoints`	No	Chinese mainland endpoints	Service endpoint URLs

Default endpoints

If endpoints is not set, the SDK uses the Chinese mainland endpoints. Add these domains to your mini program backend whitelist to make sure the SDK can reach the service.

Region	Endpoints
Chinese mainland (default)	`https://cloudauth-device.aliyuncs.com` `https://cn-shanghai.device.saf.aliyuncs.com`
International / Hong Kong (China)	`https://cloudauth-device.ap-southeast-1.aliyuncs.com` `https://ap-southeast-1.device.saf.aliyuncs.com`

Step 4: Get the device token

Retrieve the deviceToken to pass to your backend. Two approaches are available:

From the `init` callback (recommended): The callback in Step 3 returns deviceToken directly after initialization completes.
On demand: Call AliyunFP.getToken() immediately before a business event (such as logon, registration, or ordering). Wait at least 1 second after init before calling getToken().

const deviceToken = AliyunFP.getToken();

Integration example

The following example shows a complete logon flow: the SDK initializes in onReady, and the deviceToken is retrieved and sent to the backend when the user taps Log on.

Page structure (axml)

<view>
  <view class="page-description">
    {{ message }}
  </view>

  <button type="primary" onTap="onLogin">
    Log on
  </button>

  <view id="feilin-view" style="position:fixed;top:99999rpx;">
    <canvas id="feilin-canvas" type="2d" style="width:150px;height:150px;"></canvas>
    <canvas id="feilin-webgl" type="webgl" style="width:150px;height:150px;"></canvas>
  </view>
</view>

Logic implementation (js)

import * as AliyunFP from './feilin.alipay.xxx.js';
const app = getApp();
app.AliyunFP = AliyunFP;

Page({
  onReady() {
    AliyunFP.init({
      appKey: '<your-app-key>',
      appName: '<your-mini-program-name>',
      openId: '<alipay-user-id>',
      endpoints: [
        'https://cloudauth-device.aliyuncs.com',
        'https://cn-shanghai.device.saf.aliyuncs.com'
      ]
    }, (initStatus, deviceToken) => {
      console.log("initStatus:" + initStatus + "  deviceToken:" + deviceToken);
    });
  },

  onLogin() {
    // Retrieve a fresh device token when the user initiates a business action.
    const deviceToken = AliyunFP.getToken();

    // Include deviceToken in your backend request.
    // Your backend uses it to call the Fraud Detection API for risk evaluation.
    const data = {
      deviceToken: deviceToken,
      // other business parameters
    };
    // Send backend request...
  }
});

Usage notes

Security: Make sure data transmitted in Fraud Detection API calls is secure to prevent data breach or tampering.
Compatibility: The SDK may behave differently across Alipay mini program versions. Monitor Alipay release notes and test after updates.
Performance: The SDK collects and processes device data locally. Run performance testing in your target environment to verify the impact on app responsiveness.

What's next

After integrating the SDK, call the Fraud Detection API operations from your backend using the deviceToken along with other event parameters. Choose the API reference for your use case: