# Extension SDK
The Extension SDK is a supplement to the Core SDK, so using the Extension SDK also requires depending on the Core SDK.
To ensure the security and stability of the SDK, APIs that require permissions are placed in the Extension SDK as much as possible. FinClip splits the SDK into a Core SDK and an Extension SDK, where the latter is a supplement to the former. Therefore, using the Extension SDK also requires depending on the Core SDK.
Some APIs involving permissions are separated into various Extension SDKs. You can integrate the corresponding Extension SDKs based on your actual situation.
Please Note
Note: Using the Extension SDK requires ensuring the version number is consistent with the Core SDK to avoid unknown issues.
Please Note
Note: Starting from version 1.3.3, to ensure SDK compliance, each Extension SDK declares its corresponding permissions. If the certificate does not have the relevant permissions, an error will occur during integration.
Note
The Extension SDK initialization needs to be called before the Core SDK initialization; otherwise, unknown issues may occur in some scenarios.
Note
Starting from version 1.5.7, if you need to use the third-party map Extension SDK, you must first integrate the Extension SDK, then initialize the Extension SDK, and then initialize the third-party map Extension SDK. Otherwise, the system map in the Extension SDK will be used.
# 1 Extension SDK
@finclip/ext-sdk is the Extension SDK. Starting from version 1.5.7, APIs and features involving sensitive permissions and third-party libraries have been migrated to the Extension SDK.
Permissions involved:
ohos.permission.LOCATION,ohos.permission.LOCATION_IN_BACKGROUND,ohos.permission.APPROXIMATELY_LOCATION,ohos.permission.KEEP_BACKGROUND_RUNNING,ohos.permission.NFC_TAG,ohos.permission.ACCELEROMETER,ohos.permission.GYROSCOPE,ohos.permission.VIBRATE,ohos.permission.MICROPHONE
# 1.1 Integrating the Extension SDK
Add @finclip/ext-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/ext-sdk": "latest"
}
# 1.2 Registering the Extension SDK
import { FinAppletExt } from '@finclip/ext-sdk';
// ExtSDK initialization
FinAppletExt.init()
# 1.3 Extension SDK API Overview
| API Name | API Description |
|---|---|
| Location | A series of APIs |
| System Map | Map component |
| startRecord | Start recording |
| stopRecord | Stop recording |
| RecorderManager | Global unique recording manager |
| backgroundAudio | Background audio API |
| Device - Accelerometer | A series of APIs |
| Device - Compass | A series of APIs |
| Device - Gyroscope | A series of APIs |
| Device - Device Orientation | A series of APIs |
| Device - NFC | A series of APIs |
| Device - Vibration | A series of APIs |
| compressVideo | Compress video |
| FileSystemManager.readCompressedFile | Read local file content of a specified compression type |
| FileSystemManager.readCompressedFileSync | Synchronously read local file content of a specified compression type |
# 2 Bluetooth Extension SDK
@finclip/bluetooth-sdk is the Bluetooth Extension SDK.
Permissions involved:
ohos.permission.ACCESS_BLUETOOTH
# 2.1 Integrating the Bluetooth Extension SDK
Add @finclip/bluetooth-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/bluetooth-sdk": "latest"
}
# 2.2 Registering the Bluetooth Extension SDK
import { FinAppletBluetooth } from '@finclip/bluetooth-sdk';
// BluetoothSDK initialization
FinAppletBluetooth.init()
# 2.3 Bluetooth SDK API Overview
| API Name | API Description |
|---|---|
| Bluetooth - General | A series of APIs |
| Bluetooth - Low Energy Central | A series of APIs |
| Bluetooth - Beacon | Not supported on HarmonyOS |
# 3 Contacts Extension SDK
@finclip/contact-sdk is the Contacts Extension SDK.
Permissions involved:
ohos.permission.WRITE_CONTACTS,ohos.permission.READ_CONTACTS
# 3.1 Integrating the Contacts Extension SDK
Add @finclip/contact-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/contact-sdk": "latest"
}
# 3.2 Registering the Contacts Extension SDK
import { FinAppletContact } from '@finclip/contact-sdk';
// ContactSDK initialization
FinAppletContact.init()
# 3.3 Contacts SDK API Overview
| API Name | API Description |
|---|---|
| addPhoneContact | Add a contact to the phone's address book. |
| chooseContact | Launch the phone's address book to select a contact. |
# 4 Clipboard Extension SDK
@finclip/clipboard-sdk is the Clipboard Extension SDK.
Permissions involved:
ohos.permission.READ_PASTEBOARD
# 4.1 Integrating the Clipboard Extension SDK
Add @finclip/clipboard-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/clipboard-sdk": "latest"
}
# 4.2 Registering the Clipboard Extension SDK
import { FinAppletClipboard } from '@finclip/clipboard-sdk';
// ClipboardSDK initialization
FinAppletClipboard.init()
Note
Since the clipboard permission is quite sensitive and the APIs are relatively niche, you can also add the two clipboard-related APIs by registering custom APIs.
The injected source code is as follows:
import { AbstractAPIManager, FinAppClient, IApiManager, PermissionHelper } from '@finclip/sdk-core';
import { pasteboard } from '@kit.BasicServicesKit';
namespace IClipboardAPI {
export interface IClipboardData {
data: string
}
}
function getClipboardData(args: IApiManager.IInvokeArgs, apiManager: AbstractAPIManager) {
const callback = args.callback
const context = apiManager.UIContext
PermissionHelper.requestPermissions(context, ['ohos.permission.READ_PASTEBOARD'], () => {
const systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getData().then((pasteData) => {
const text = pasteData.getPrimaryText();
const res: IApiManager.IInvokeBaseResponse = {
errMsg: 'getClipboardData:ok',
data: text
}
callback.onSuccess(res)
}).catch((err: Error) => {
callback.onFail({ errMsg: err.message })
});
}, (index: number) => {
// User denied authorization
callback.onFail({ errMsg: PermissionHelper.authDenyMsg })
})
}
function setClipboardData(args: IApiManager.IInvokeArgs, apiManager: AbstractAPIManager) {
const callback = args.callback
const params = args.params as IClipboardAPI.IClipboardData
const text: string = params.data
const pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, text);
const systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();
const res: IApiManager.IInvokeBaseResponse = {
errMsg: 'setClipboardData:ok'
}
systemPasteboard.setData(pasteData).then(() => {
callback.onSuccess(res)
}).catch((err: Error) => {
callback.onFail({ errMsg: err.message })
});
}
FinAppClient.getInstance()?.registerCustomApi('getClipboardData', getClipboardData)
FinAppClient.getInstance()?.registerCustomApi('setClipboardData', setClipboardData)
# 4.3 Clipboard SDK API Overview
| API Name | API Description |
|---|---|
| setClipboardData | Set clipboard content |
| getClipboardData | Get clipboard content |
# 5 Calendar Extension SDK
@finclip/calendar-sdk is the Calendar Extension SDK.
Permissions involved:
ohos.permission.READ_CALENDAR,ohos.permission.WRITE_CALENDAR
# 5.1 Integrating the Calendar Extension SDK
Add @finclip/calendar-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/calendar-sdk": "latest"
}
# 5.2 Registering the Calendar Extension SDK
import { FinAppletCalendar } from '@finclip/calendar-sdk';
// CalendarSDK initialization
FinAppletCalendar.init()
# 5.3 Calendar SDK API Overview
| API Name | API Description |
|---|---|
| addPhoneCalendar | Add a normal calendar event |
| addPhoneRepeatCalendar | Add a recurring calendar event |
# 6 Baidu Map Extension SDK
@finclip/baidu-map-sdk is the Baidu Map Extension SDK.
For preparation of using Baidu Maps, please refer to the documentation: Baidu Maps (opens new window)
Involved permissions:
ohos.permission.LOCATION,ohos.permission.LOCATION_IN_BACKGROUND,ohos.permission.APPROXIMATELY_LOCATION
# 6.1 Integrating the Baidu Map Extension SDK
Add @finclip/baidu-map-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/baidu-map-sdk": "latest"
}
# 6.2 Registering the Baidu Map Extension SDK
# 6.2.1 Quick Start
import { FinAppletBaiduMap } from '@finclip/baidu-map-sdk';
// This will initialize the Baidu Map SDK and register the map component
FinAppletBaiduMap.init('api_key') // Pass the API key obtained from the open platform
# 6.2.2 Register Component Only
import { FinAppletBaiduMap } from '@finclip/baidu-map-sdk';
// If the Baidu Map has already been initialized in the project, you can register only the map component
FinAppletBaiduMap.registerComponent()
# 6.3 Modifying the Coordinate System
The CoordType provided by the Map SDK is exported from @bdmap/base. For specific definitions, please refer to the Baidu Map Documentation (opens new window)
import { FinAppletBaiduMap, CoordType } from '@finclip/baidu-map-sdk';
// You can use the API to modify the Baidu Map coordinate system
FinAppletBaiduMap.setBDMapCoordinateType(CoordType.GCJ02)
# 6.4 Baidu Map SDK Related API Overview
| API Name | API Description |
|---|---|
| Map Component | View Component |
| MapContext | A series of APIs |
| openLocation | View Location |
| chooseLocation | Choose Location |
| choosePoi | Open POI List to Choose Location |
# 7 Album Extension SDK
@finclip/album-sdk is the Album Extension SDK.
Involved permissions:
ohos.permission.WRITE_IMAGEVIDEO
# 7.1 Integrating the Album Extension SDK
Add @finclip/album-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/album-sdk": "latest"
}
# 7.2 Registering the Album Extension SDK
import { FinAppletAlbum } from '@finclip/album-sdk';
// AlbumSDK initialization
FinAppletAlbum.init()
# 7.3 Album SDK Related API Overview
Note
The Album Extension SDK uses ACL permissions to implement ACLPermissionHandler.saveMediaToPhotosAlbum. If you have already implemented this proxy method yourself, please do not use this SDK, as it will override the implementation.
The injected source code is as follows:
import { common, Permissions } from '@kit.AbilityKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { CommonUtils, FinAppProxyHandlerManager, IFinProxyHandlerItem, PermissionHelper } from '@finclip/sdk-core';
import { fileIo as fs } from '@kit.CoreFileKit';
export class ACLPermissionHandler extends IFinProxyHandlerItem.ACLPermissionHandler {
/**
* Method to save an image or video to the album, requires the 'ohos.permission.WRITE_IMAGEVIDEO' permission by default
* @param type The type of media to save
* @param realPath The full path of the file
* @param context
* @returns No return value on success; if it fails, reject with the corresponding error message, e.g., reject('auth deny')
*/
public saveMediaToPhotosAlbum(type: 'image' | 'video', realPath: string,
context: common.UIAbilityContext): Promise<void> {
return new Promise((resolve, reject) => {
const defaultExt = type === 'image' ? 'jpg' : 'mp4'
const accessType = type === 'image' ? photoAccessHelper.PhotoType.IMAGE : photoAccessHelper.PhotoType.VIDEO
const permissions: Array<Permissions> = ['ohos.permission.WRITE_IMAGEVIDEO']
PermissionHelper.requestPermissions(context, permissions, async () => {
try {
const helper = photoAccessHelper.getPhotoAccessHelper(context);
const ext = CommonUtils.getFileExtension(realPath) || defaultExt
const uri = await helper.createAsset(accessType, ext);
const file = await fs.open(uri, fs.OpenMode.READ_WRITE | fs.OpenMode.APPEND)
const readStream = await fs.createStream(realPath, 'r+')
const arrayBuffer = new ArrayBuffer(4096)
let len = await readStream.read(arrayBuffer);
while (len) {
await fs.write(file.fd, arrayBuffer)
len = await readStream.read(arrayBuffer);
}
await readStream.close()
await fs.close(file)
resolve()
} catch (err) {
reject(err.message)
}
}, (index: number) => {
reject(PermissionHelper.authDenyMsg)
})
})
}
}
FinAppProxyHandlerManager.ACLPermissionHandler = new ACLPermissionHandler()
# 8 Live SDK
@finclip/live-sdk is the Live Extension SDK.
Involved permissions:
ohos.permission.MICROPHONE,ohos.permission.MICROPHONE,ohos.permission.CAMERA,ohos.permission.INTERNET
# 8.1 Integrating the Live Extension SDK
Add @finclip/live-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/live-sdk": "latest"
}
# 8.2 Registering the Live Extension SDK
import { FinAppletLive } from '@finclip/live-sdk';
FinAppletLive.init()
# 8.3 LiveSDK (live-player) Related API Overview
| API Name | API Description |
|---|---|
| play | Play |
| stop | Stop |
| pause | Pause |
| resume | Resume |
| mute | Mute |
# 8.4 LiveSDK (live-pusher) Related API Overview
| API Name | API Description |
|---|---|
| start | Start streaming |
| stop | Stop streaming and stop camera preview |
| pause | Pause streaming |
| resume | Resume streaming |
| startPreview | Start camera preview |
| stopPreview | Stop camera preview |
| switchCamera | Switch between front and rear cameras |
# 8.4.1 Sensitive Permissions Involved in LiveSDK
| Permission | Related Interfaces/Components |
|---|---|
| Camera | Permission is requested upon initialization |
| Record Audio | Permission is requested upon initialization |
# 9 Share SDK
@finclip/share-sdk is the Share Extension SDK. When using the Share Extension SDK, you need to set hideShareAppletMenu in uiConfig to false so that the share button will be displayed in the more menu.
# 9.1 Integrating the Share Extension SDK
Add @finclip/share-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/share-sdk": "latest"
}
# 9.2 Registering the Share Extension SDK
import { FinAppletShare } from '@finclip/share-sdk';
/**
* Initialize the Share SDK
* @param wxAppId The AppID applied for on the WeChat Open Platform, or an instance of WXApi
* @param scheme The scheme of the share link, used to launch the app when accessing the link, needs to be configured in the app
*/
FinAppletShare.init('wxAppId','scheme')
# 9.3 Configuring Custom Links
# 9.3.1 Custom Share Landing Page Link
/**
* Set custom share link
* @param {function} cb - Custom share link callback function
* @param {Object} cb.appInfo - Mini-Program information
* @returns {string} cb.return - Custom share link
* */
FinAppletShare.onCustomShareUrl = async (appInfo) => {
return `https://example.com/share`
};
# 9.3.2 Custom Download URL in Share Link
/**
* Set custom APP download link
* @param {function} cb - Custom APP download link callback function
* @param {Object} cb.appInfo - Mini-Program information
* @returns {string} cb.return - Custom APP download link
* */
FinAppletShare.onCustomAppDownloadLink = async (appInfo) => {
return `https://example.com/download`
};
# 9.4 Project Configuration
# 9.4.1 Configuring the Scheme
You can refer to the official documentation (opens new window) to configure the corresponding scheme, and then pass it to the Share SDK.
# 9.4.2 Parsing Links to Launch the Mini-Program
Due to the HarmonyOS system mechanism, the SDK cannot handle launch requests. You can refer to the following code to parse the link and call the open Mini-Program API to launch the Mini-Program.
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(0x0000, TAG, '%{public}s', `Ability onCreate`);
}
onDestroy(): void {
hilog.info(0x0000, TAG, '%{public}s', 'Ability onDestroy');
}
onWindowStageCreate(windowStage: window.WindowStage): void {
// Main window is created, set main page for this ability
hilog.info(0x0000, TAG, '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', storage,(err, data) => {
if (err.code) {
hilog.error(0x0000, TAG, 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
return;
}
hilog.info(0x0000, TAG, 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
});
}
onWindowStageDestroy(): void {
// Main window is destroyed, release UI related resources
hilog.info(0x0000, TAG, '%{public}s', 'Ability onWindowStageDestroy');
}
onForeground(): void {
// Ability has brought to foreground
hilog.info(0x0000, TAG, '%{public}s', 'Ability onForeground');
}
onBackground(): void {
// Ability has back to background
hilog.info(0x0000, TAG, '%{public}s', 'Ability onBackground');
}
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// Receive the parameters passed by UIAbility from the caller
this.processStartUri(want)
hilog.info(0x0000, TAG, '%{public}s', 'Ability onNewWant');
}
processStartUri(want:Want) {
const startUri = want.uri
if (startUri) {
// Parse the appid from the path
const url = new uri.URI(startUri)
const pathSegments = url.path.split('/')
const appId = pathSegments[pathSegments.length - 1]
// Parse query parameters
const query = url.getQueryValue('query') || ''
const path = url.getQueryValue('path') || ''
const scene = url.getQueryValue('scene') || '0'
const shareDepth = url.getQueryValue('shareDepth') || '0'
// Configure the corresponding apiServer
const apiServer = 'your apiServer'
if (apiServer) {
FinAppClient.getInstance()?.startApplet({
appId,
apiServer,
startParams: {
path,
query,
shareDepth: Number(shareDepth),
scene: Number(scene)
}
})
}
}
}
}
# 10 AMap Extension SDK
@finclip/gd-map-sdk is the AMap Extension SDK. If you use the AMap Extension SDK, all location-related APIs will use AMap for positioning.
For preparation on using AMap, please refer to the documentation: AMap (opens new window)
Involved permissions:
ohos.permission.LOCATION,ohos.permission.LOCATION_IN_BACKGROUND,ohos.permission.APPROXIMATELY_LOCATION,ohos.permission.KEEP_BACKGROUND_RUNNING
# 10.1 Integrating the AMap Extension SDK
Add @finclip/gd-map-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/gd-map-sdk": "latest"
}
# 10.2 Registering the AMap Extension SDK
# 10.2.1 Updating the Privacy Agreement Status
If you have already updated the AMap privacy agreement, you can skip this step.
import { FinAppletGDMap, AMapPrivacyAgreeStatus, AMapPrivacyInfoStatus, AMapPrivacyShowStatus } from '@finclip/gd-map-sdk';
FinAppletGDMap.updateLocationPrivacyShow(
AMapPrivacyShowStatus.DidShow,
AMapPrivacyInfoStatus.DidContain,
this.context)
FinAppletGDMap.updateLocationPrivacyAgree(
AMapPrivacyAgreeStatus.DidAgree,
this.context
);
// Search SDK privacy policy
FinAppletGDMap.updateSearchPrivacyShow(
AMapPrivacyShowStatus.DidShow,
AMapPrivacyInfoStatus.DidContain,
this.context
);
FinAppletGDMap.updateSearchPrivacyAgree(
AMapPrivacyAgreeStatus.DidAgree,
this.context
);
# 10.2.2 Quick Start
import { FinAppletGDMap} from '@finclip/gd-map-sdk';
// This will initialize the AMap SDK and register the map component
FinAppletGDMap.init('api_key')
# 10.2.3 Registering Only the Component
import { FinAppletGDMap } from '@finclip/gd-map-sdk';
// If the AMap has already been initialized in the project, you can register only the map component
FinAppletGDMap.registerComponent()
# 10.3 Overview of AMap SDK Related APIs
| API Name | API Description |
|---|---|
| Map Component | View Component |
| MapContext | A series of APIs |
| getLocation | Get the current geographic location |
| startLocationUpdate | Start receiving location messages when the Mini-Program enters the foreground |
| startLocationUpdateBackground | Start receiving location messages when the Mini-Program is in the foreground or background |
| openLocation | View a location |
| chooseLocation | Select a location |
| choosePoi | Open the POI list to select a location |
# 11 XLog Extension SDK
@finclip/xlog-sdk is the XLog Extension SDK.
Note
Starting from version 1.4.3, the core SDK will no longer include the functionality to persist logs locally.
If you need to persist logs, you can choose to integrate the XLog SDK and enable the corresponding configuration item for the LogHandler.
# 11.1 Integrating the XLog Extension SDK
Add @finclip/xlog-sdk to dependencies
"dependencies": {
"@finclip/sdk": "latest",
"@finclip/xlog-sdk": "latest"
}
# 11.2 Registering the XLog Extension SDK
Note
The XLog SDK initialization must be called before the core SDK initialization; otherwise, the XLog-related configuration cannot be obtained.
import { FinAppletXLog } from '@finclip/xlog-sdk';
// XLog SDK initialization
FinAppletXLog.init()