# 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
trueby default - Supports custom implementation, such as adding user authorization dialogs
- Stops recording when
falseis 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:
- Upload to FinClip Management Console
- 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:
- Upload to FinClip Management Console
- 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:
- Upload to FinClip Management Console
- 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)