# Mini-Program Traceability Feature

# Feature Overview

The Mini-Program Traceability feature is a professional user behavior recording function, primarily used in:

  • Internet insurance sales scenarios
  • Online financial product sales
  • Other financial scenarios requiring compliance audit trails

This feature can:

  • High-performance recording of user operation trails
  • Accurately restore transaction scenarios
  • Meet financial regulatory compliance requirements
  • Provide complete traceability management capabilities

# Mini-Program Integration

# 1. Enable Feature

Add the following configuration in the Mini-Program's app.ext.json file:

{
    "trace": {
        "enable": true
    }
}

# 2. Runtime Control

Provides flexible recording control interfaces:

// Start recording session
ft.setTraceEnable({
    enable: true
})

// Stop current recording session
ft.setTraceEnable({
    enable: false
})

# 3. Privacy Protection

To protect user privacy and sensitive information, two privacy protection mechanisms are provided:

# 3.1 Content Masking

Mask sensitive content (such as ID numbers, bank card numbers, etc.):

  • Images: Will be replaced with skeleton images
  • Text: Will be replaced with asterisks (*)

Usage: Add the trace-mask class name to elements requiring masking

<!-- Masking example -->
<view class="trace-mask">
    <text>6222************1234</text>
    <image src="/path/to/idcard.png" />
</view>

# 3.2 Content Exclusion

Completely exclude specific elements from recording:

  • Excluded elements will not be collected
  • Suitable for highly sensitive information (such as password input fields)

Usage: Add the trace-exclude class name to elements requiring exclusion

<!-- Exclusion example -->
<view class="trace-exclude">
    <input type="password" placeholder="Please enter password" />
</view>

# HarmonyOS Integration

# 1. User Authorization Management

# Request User Authorization

When a Mini-Program starts recording, the SDK triggers the requestUserAuthorization interface of the Mini-Program traceability proxy. This interface:

  • Returns true by default
  • Supports custom implementation, such as adding user authorization dialogs
  • Stops recording when false is returned

Example Code: Custom Authorization Dialog

import { FinAppProxyHandlerManager, IFinAppConfig, IFinProxyHandlerItem } from '@finclip/sdk';
import { promptAction } from '@kit.ArkUI';

class AppletTraceHandler extends IFinProxyHandlerItem.AppletTraceHandler {
  requestUserAuthorization(): Promise<boolean> {
    return new Promise((resolve, reject) => {
      promptAction.showDialog({
        title: 'Enable Recording',
        message: 'Enabling recording will track your operations for compliance traceability',  // Added more detailed description
        buttons: [
          {
            text: 'Confirm',
            color: '#409EFF'
          },
          {
            text: 'Cancel',
            color: '#000000'
          }
        ]
      }).then(data => {
        resolve(data.index !== 1)
      })
    })
  }
}

// Register traceability proxy
FinAppProxyHandlerManager.appletTraceHandler = new AppletTraceHandler()

# 2. Recording File Management

# Get Recording File List

Get all recording file lists for the current user under the specified Mini-Program.

/**
 * @param appId - Mini-Program ID
 * @param apiServer - API server address
 * @returns Promise<Array<String>> Recording file list
 */
const files = await client.getAppletTraceLogs(appId, apiServer)

# Delete Recording File

Supports deleting specified recording files.

/**
 * @param filepath - Recording file path
 * @returns Promise<void>
 */
await client.deleteAppletTraceLogFile(filepath)

# Upload Recording File

Provides two upload methods:

  1. Upload to FinClip Management Console
  2. Upload to custom server
/**
 * Upload recording file to FinClip Management Console
 * @param appId - Mini-Program ID
 * @param apiServer - API server address
 * @param filepath - Recording file path
 * @returns Promise<void>
 */
await client.reportAppletTraceLog(appId, apiServer, filepath)

# iOS Integration

# 1. User Authorization Management

# Request User Authorization

When a Mini-Program starts recording, the SDK triggers the Mini-Program traceability proxy's authorization request method: requestUserAuthorization.

  • If the traceability proxy is not set or the method is not implemented, it defaults to granting authorization
  • Supports custom implementation, such as adding user authorization dialogs
  • Callback result enableTrace: YES, starts recording
  • Callback result enableTrace: NO, does not record

Example Code: Custom Authorization Dialog

// Set delegate
[FATClient sharedClient].appletTraceDelegate = self;


// Implement delegate method
#pragma mark - FATAppletTraceDelegate
/// Request user authorization to enable traceability feature
/// - Parameter completion: Completion callback enableTrace: true represents agreeing to enable traceability feature
- (void)requestUserAuthorization:(void (^)(BOOL enableTrace))completion {
    UIAlertController *vc = [UIAlertController alertControllerWithTitle:@"Authorization Reminder" message:@"Agree to enable traceability feature?" preferredStyle:UIAlertControllerStyleAlert];
    [vc addAction:[UIAlertAction actionWithTitle:@"Agree" style:UIAlertActionStyleDefault handler:^(UIAlertAction * _Nonnull action) {
        completion(YES);
    }]];
    [vc addAction:[UIAlertAction actionWithTitle:@"Disagree" style:UIAlertActionStyleCancel handler:^(UIAlertAction * _Nonnull action) {
        completion(NO);
    }]];
    UIViewController *topVc = [[UIApplication sharedApplication] fat_topViewController];
    [topVc presentViewController:vc animated:YES completion:nil];
}

# 2. Recording File Management

# Get Recording File List

Get all recording file lists for the current user under the specified Mini-Program.

/// Get all Mini-Program traceability log file paths
/// - Parameters:
///   - apiServer: Server address
///   - appletId: Mini-Program ID
///
- (NSArray<NSString *> *)getAppletTraceLogs:(NSString *)apiServer appletId:(NSString *)appletId;


NSArray<NSString *> *logsFile = [[FATClient sharedClient].appletTraceManager getAppletTraceLogs:apiServer appletId:appletId];

# Delete Recording File

Supports deleting specified recording files.

/// Delete traceability log file based on file path
/// - Parameter filePath: Traceability log file path
/// - Parameter complete: Completion callback
///
- (void)deleteAppletTraceLogFile:(NSString *)filePath complete:(void(^)(void))complete;

[[FATClient sharedClient].appletTraceManager deleteAppletTraceLogFile:path complete:^{
    
}];

# Delete All Recording Files

Supports deleting all recording files.

/// Clear all Mini-Program traceability log files
/// - Parameter complete: Completion callback
- (void)deleteAllAppletTraceLogFiles:(void(^)(void))complete;

[[FATClient sharedClient].appletTraceManager deleteAllAppletTraceLogFiles:^{
    
}];

# Upload Recording File

Provides two upload methods:

  1. Upload to FinClip Management Console
  2. Upload to custom server
/// Report traceability log to FinClip Management Console
/// - Parameters:
///   - filePath: Log file path
///   - apiServer: ApiServer
///   - appletId: Mini-Program ID
///   - success: Success callback
///   - failure: Failure callback
///
- (void)reportAppletTraceLog:(NSString *)filePath apiServer:(NSString *)apiServer appletId:(NSString *)appletId success:(void(^)(void))success failure:(void(^)(NSString *errorMessage))failure;

[[FATClient sharedClient].appletTraceManager reportAppletTraceLog:path apiServer:apiServer appletId: appletId success:^{
    
} failure:^(NSString * _Nonnull errorMessage) {
   
}];

# Android Integration

# 1. User Authorization Management

# Request User Authorization

When a Mini-Program starts recording, the SDK triggers the Mini-Program traceability proxy's authorization request method: requestUserAuthorization.
Returns result through callback's allowAuthorization(boolean) method:

  • If the traceability proxy is not set or the method is not implemented, it defaults to granting authorization
  • Supports custom implementation, such as adding user authorization dialogs
  • allowAuthorization(true), starts recording
  • allowAuthorization(false), does not record

Example Code: Custom Authorization Dialog

// Mini-Program process
FinAppProcessClient.appletTraceHandler = object : AppletTraceHandler() {
    override fun requestUserAuthorization(
        context: Context,
        appId: String,
        callback: Callback
    ) {
        AlertDialog.Builder(context).apply {
            setTitle("Authorization Reminder")
            setMessage("Agree to enable traceability feature?")
            setPositiveButton("Agree") { dialog, _ ->
                callback.allowAuthorization(true)
                dialog.dismiss()
            }
            setNegativeButton("Disagree") { dialog, _ ->
                callback.allowAuthorization(false)
                dialog.dismiss()
            }
            create().show()
        }
    }
}

# 2. Recording File Management

# Get Recording File List

Get all recording file lists for the current user under the specified Mini-Program.

fun getAppletTraceLogs(
    context: Context,
    apiServer: String,
    appId: String,
    callback: FinCallback<List<String>>
)

FinAppClient.appletTraceManager.getAppletTraceLogs(context, apiServer, appId, callback)

# Delete Recording File

Supports deleting specified recording files.

fun deleteAppletTraceLogFile(context: Context, filePath: String): Boolean

FinAppClient.appletTraceManager.deleteAppletTraceLogFile(context, filePath)

# Delete All Recording Files

Supports deleting all recording files.

fun deleteAllAppletTraceLogFiles(context: Context, callback: FinCallback<Any?>)

FinAppClient.appletTraceManager.deleteAllAppletTraceLogFiles(context, callback)

# Upload Recording File

Provides two upload methods:

  1. Upload to FinClip Management Console
  2. Upload to custom server
fun reportAppletTraceLog(
    context: Context,
    apiServer: String,
    appId: String,
    filePath: String,
    callback: FinCallback<Any?>
)

FinAppClient.appletTraceManager.reportAppletTraceLog(context, apiServer, appId, filePath, callback)
© FinClip with ❤ , Since 2017