# Widget Integration
Widgets are a capability provided by the FinClip SDK, so only the FinClip SDK needs to be integrated.
# 1. Integration Guide
- For FinClip iOS SDK integration, refer to: iOS Integration
- For FinClip Android SDK integration, refer to: Android Integration
- For FinClip Harmony SDK integration, refer to: Harmony Integration
# 2. Demo Examples
- iOS Widget Demo (opens new window)
- Android Widget Demo (opens new window)
- Harmony Widget Demo (opens new window)
# 3. Version Notes
- Both iOS SDK and Android SDK support the widget feature starting from version 2.44.1 and later.
# 4. Opening a Widget
# 4.1 iOS
Use the API methods provided by the widgetManager object of the FATClient class to create widgets of different version types, and use different requests to create widgets for different scenarios.
Tips
- Use
weakSelfin the completion callback when opening a widget to avoid circular references.
# 4.1.1 Open the Official Server-Side Widget
/// Create a widget
/// - Parameters:
/// - request: Request parameters
/// - parentViewController: The view controller where the widget is located. If not provided, some APIs may not be usable.
/// - completion: Creation result. If creation fails, widgetView is nil.
- (void)createWidget:(FATWidgetRequest *)request parentViewController:(UIViewController *)parentViewController completion:(void (^)(FATWidgetView *_Nullable widgetView, FATError *error))completion;
Example Code:
FATWidgetRequest *widgetRequest = [[FATWidgetRequest alloc]init];
widgetRequest.widgetId = @"65e82e0778df2c00015c21a4";
widgetRequest.widgetServer = @"https://api.finclip.com";
[self showLoading];
__weak typeof(self) weakSelf = self;
[[FATClient sharedClient].widgetManager createWidget:widgetRequest parentViewController:self completion:^(FATWidgetView * _Nullable widgetView, FATError * _Nonnull error) {
[weakSelf hideLoading];
if (!error) {
if (widgetView) {
[weakSelf showWidgetView:widgetView];
}
}else {
[weakSelf handleOpenWidgetFail:error];
}
}];
# 4.1.2 Open a Widget via QR Code
/// Create a widget via QR code
/// - Parameters:
/// - request: Request parameters
/// - parentViewController: The view controller where the widget is located. If not provided, some APIs may not be usable.
/// - completion: Creation result. If creation fails, widgetView is nil.
- (void)createWidgetWithQRCode:(FATWidgetQRCodeRequest *)request parentViewController:(UIViewController *)parentViewController completion:(void (^)(FATWidgetView *_Nullable widgetView, FATError *error))completion;
# 4.1.3 Open a Local Widget
/// Open a local widget
/// - Parameters:
/// - request: Request parameters
/// - parentViewController: The view controller where the widget is located. If not provided, some APIs may not be usable.
/// - completion: Creation result. If creation fails, widgetView is nil.
- (void)createLocalWidget:(FATWidgetRequest *)request parentViewController:(UIViewController *)parentViewController completion:(void (^)(FATWidgetView *_Nullable widgetView, FATError *error))completion;
# 4.1.4 Multi-Instance Widgets
Supports creating multiple widget views with the same widgetId.
FATWidgetRequest has two new parameters: enableMultiWidget and widgetRunId. The combination of widgetId + widgetRunId serves as the unique identifier for the widget. If widgetRunId is not provided, the SDK will generate one internally.
When enableMultiWidget is set to YES, each call to the widget opening method will create a new widget view. If widgetRunId is also provided, the SDK will check among the already created widgets in memory to see if a widget with the same widgetId and widgetRunId has been opened. If not found, a new widget view is created; if found, the previously created widget view is returned.
FATWidgetRequest *widgetRequest = [[FATWidgetRequest alloc]init];
widgetRequest.widgetId = @"65e82e0778df2c00015c21a4";
widgetRequest.widgetServer = @"https://api.finclip.com";
widgetRequest.widgetRunId = @"123456";
widgetRequest.enableMultiWidget = YES;
[self showLoading];
__weak typeof(self) weakSelf = self;
[[FATClient sharedClient].widgetManager createWidget:widgetRequest parentViewController:self completion:^(FATWidgetView * _Nullable widgetView, FATError * _Nonnull error) {
[weakSelf hideLoading];
if (!error) {
if (widgetView) {
[weakSelf showWidgetView:widgetView];
}
}else {
[weakSelf handleOpenWidgetFail:error];
}
}];
# 4.1.5 Dynamically Set Widget Width and Height
Changes in widget width and height trigger the following delegate method. The Host-App can use this delegate method to get the widget's width and height changes.
/// Widget content width/height update. The Host-App can decide whether to update the widget's area based on business needs (the SDK will not automatically set the widget's width/height to the content's width/height).
/// - Parameter widgetView: The widget view
/// - Parameter size: The widget's content width and height
- (void)onWidgetView:(FATWidgetView *)widgetView contentSizeUpdate:(CGSize)size;
# 4.2 Android
# 4.2.1 Open the Official Server-Side Widget
/**
* Open a widget
*
* @param activity The activity to which the widget will be added
* @param request Parameter encapsulation
*/
fun startComponent(
activity: FragmentActivity,
request: IFinAppletRequest,
callback: ComponentCallback
)
Use the RemoteFinAppletRequest type for the request.
Example Code:
// Show loading before opening the widget
showLoading()
// Construct the request object
val request = IFinAppletRequest.Companion.fromAppId("https://api.finclip.com", "661ce3fb9876dc000158c94f")
// Other startup parameters can be set via the request
// ...
FinAppClient.appletApiManager.startComponent(
this,
request,
object : ComponentCallback {
override fun onSuccess(result: String?) {
// Widget loaded successfully
}
override fun onError(code: Int, error: String?) {
// Widget loading failed, hide loading, show error message.
hideLoading()
showError(code, error.orEmpty())
}
override fun onComponentCreated(componentHolder: ComponentHolder) {
// Widget created successfully, add the widget view to the host Activity's view
componentContainer.addView(
componentHolder.view,
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
this@ComponentActivity.componentHolder = componentHolder
}
override fun onContentLoaded() {
// Widget content loaded, hide loading
hideLoading()
}
}
)
# 4.2.2 Open a Widget via QR Code
/**
* Open a widget
*
* @param activity The activity to which the widget will be added
* @param request Parameter encapsulation
*/
fun startComponent(
activity: FragmentActivity,
request: IFinAppletRequest,
callback: ComponentCallback
)
Use the QrCodeFinAppletRequest type for the request.
Example Code:
val request = IFinAppletRequest.Companion.fromQrCode(qrCode)
FinAppClient.appletApiManager.startComponent(
this,
request,
object : ComponentCallback {
override fun onSuccess(result: String?) {
// Widget loaded successfully
}
override fun onError(code: Int, error: String?) {
// Widget loading failed, hide loading, show error message.
hideLoading()
showError(code, error.orEmpty())
}
override fun onComponentCreated(componentHolder: ComponentHolder) {
// Widget created successfully, add the widget view to the host Activity's view
componentContainer.addView(
componentHolder.view,
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
this@ComponentActivity.componentHolder = componentHolder
}
override fun onContentLoaded() {
// Widget content loaded, hide loading
hideLoading()
}
}
)
# 4.2.3 Open a Local Widget
/**
* Open a widget
*
* @param activity The activity to which the widget will be added
* @param request Parameter encapsulation
*/
fun startComponent(
activity: FragmentActivity,
request: IFinAppletRequest,
callback: ComponentCallback
)
Use the LocalFinAppletRequest or LocalInterfaceFinAppletRequest type for the request.
Example Code:
val request = IFinAppletRequest.Companion.fromLocalInterface("https://abc.com","661ce3fb9876dc000158c94f")
FinAppClient.appletApiManager.startComponent(
this,
request,
object : ComponentCallback {
override fun onSuccess(result: String?) {
// Widget loaded successfully
}
override fun onError(code: Int, error: String?) {
// Widget loading failed, hide loading, show error message.
hideLoading()
showError(code, error.orEmpty())
}
override fun onComponentCreated(componentHolder: ComponentHolder) {
// Widget created successfully, add the widget view to the host Activity's view
componentContainer.addView(
componentHolder.view,
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
this@ComponentActivity.componentHolder = componentHolder
}
override fun onContentLoaded() {
// Widget content loaded, hide loading
hideLoading()
}
}
)
# 4.2.4 Dynamically Setting Widget Width and Height
/**
* Open Widget
*
* @param activity The activity to which the widget will be added
* @param request Parameter encapsulation
*/
fun startComponent(
activity: FragmentActivity,
request: IFinAppletRequest,
callback: ComponentCallback
)
val request = IFinAppletRequest.Companion.fromAppId("https://api.finclip.com", "661ce3fb9876dc000158c94f")
FinAppClient.appletApiManager.startComponent(
this,
request,
object : ComponentCallback {
override fun onSuccess(result: String?) {
// Widget loaded successfully
}
override fun onError(code: Int, error: String?) {
// Widget loading failed, hide Loading, display error message.
hideLoading()
showError(code, error.orEmpty())
}
override fun onComponentCreated(componentHolder: ComponentHolder) {
// Widget created successfully, add the widget view to the host Activity view
componentContainer.addView(
componentHolder.view,
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
// Save the componentHolder variable
this@ComponentActivity.componentHolder = componentHolder
}
// Callback for dynamically setting widget width and height
// This method is triggered when the setWindowSize method is called within the Mini-Program code
// Example: wx.setWindowSize({width: 200, height: 200})
override fun onContentSizeChanged(width: Int, height: Int) {
val componentView = componentHolder?.view
componentView?.layoutParams?.apply {
this.width = width
this.height = height
componentView.layoutParams = this
}
}
override fun onContentLoaded() {
// Widget content loaded, hide Loading
hideLoading()
}
}
)
# 4.2.5 Multi-Instance Widgets
val request = IFinAppletRequest.Companion.fromAppId("https://api.finclip.com", "661ce3fb9876dc000158c94f")
// Set property to allow multi-instance widgets
request.enableMultiComponent = true
// When starting the widget, allow opening the same appid repeatedly
FinAppClient.appletApiManager.startComponent(
this,
request,
object : ComponentCallback {
override fun onComponentCreated(componentHolder: ComponentHolder) {
// Multi-instance widget created successfully, dynamically add the view to the layout
val containerLayout = LinearLayout(context).apply {
orientation = LinearLayout.VERTICAL
layoutParams = LinearLayout.LayoutParams(
LinearLayout.LayoutParams.MATCH_PARENT,
LinearLayout.LayoutParams.WRAP_CONTENT
)
}
val componentContainer = FrameLayout(context).apply {
layoutParams = LinearLayout.LayoutParams(
LinearLayout.LayoutParams.MATCH_PARENT,
LinearLayout.LayoutParams.WRAP_CONTENT
)
}
containerLayout.addView(componentContainer)
componentContainer.addView(componentHolder.view,
FrameLayout.LayoutParams(
FrameLayout.LayoutParams.MATCH_PARENT,
FrameLayout.LayoutParams.WRAP_CONTENT
)
)
componentsParentContainer.addView(containerLayout)
// Save the newly opened widget to the array
componentHolders.add(componentHolder)
}
}
)
// Handle deletion/hiding of widgets accordingly
# 4.3 Harmony
To use widgets in Harmony, add FinWidget at the desired location and pass the widgetId to identify the widget.
When an error occurs while opening a widget, the proxy method appletLifeCycleHandler.onError will be triggered. Developers can handle the error based on the error message or error code.
Example code:
import { FinWidget } from '@finclip/sdk';
@Entry
@Component
struct WidgetPage {
@State widgetId:string = '1'
// ...
build(){
FinWidget({ widgetId: this.widgetId })
.width('100%')
.height(200)
}
}
# 4.3.1 Opening a Server-Side Release Widget
/**
* Open Widget
*
* @param context The context where the widget resides
* @param request Parameter encapsulation
* @param widgetId The identifier id of the widget
*/
function startWidget(
context: common.UIAbilityContext,
request: IFinApplet.IAppletRequest,
widgetId: string
)
Example code:
import { FinAppClient, FinWidget, IFinApplet } from '@finclip/sdk';
@Entry
@Component
struct WidgetPage {
@State widgetId:string = '1'
client?: FinAppClient
aboutToAppear() {
// SDK initialization logic
}
startWidget(){
this.client?.startWidget(this.context, {
appId: 'appid',
apiServer: 'apiServer',
startParams: {}
}, this.widgetId)
}
// ...
build(){
FinWidget({ widgetId: this.widgetId })
.width('100%')
.height(200)
}
}
# 4.3.2 Opening a Widget via QR Code
/**
* Open Widget
*
* @param context The context where the widget resides
* @param request Parameter encapsulation
* @param widgetId The identifier id of the widget
*/
fun startWidgetByQrCode(
context: common.UIAbilityContext,
request: IFinApplet.IQrCodeRequest,
widgetId: string
)
Example code:
import { FinAppClient, FinWidget, IFinApplet } from '@finclip/sdk';
@Entry
@Component
struct WidgetPage {
@State widgetId:string = '1'
client?: FinAppClient
aboutToAppear() {
// SDK initialization logic
}
startWidgetByQrCode(qrcode: string) { // QR code data obtained from scanning
this.client?.startWidgetByQrCode(this.context, {
qrcode
}, this.widgetId)
}
// ...
build(){
FinWidget({ widgetId: this.widgetId })
.width('100%')
.height(200)
}
}
# 4.3.3 Dynamically Setting Widget Width and Height
The default width and height of a widget are 100% of the parent component. You can manually set the width and height for FinWidget, or call wx.setWindowSize within the Mini-Program to set them.
wx.setWindowSize({width: 200, height: 200})
Example code:
import { FinAppClient, FinWidget, IFinApplet } from '@finclip/sdk';
@Entry
@Component
struct WidgetPage {
// ...
build(){
FinWidget({ widgetId: this.widgetId })
}
}
# 5. Deleting Widgets
# 5.1 iOS
# 5.1.1 Deleting a Specific Widget Cache
Deleting a widget removes it from the page and destroys it from memory.
/// Clean widget
/// - Parameter widgetId: widgetId
- (void)cleanWidget:(NSString *)widgetId;
# 5.1.2 Deleting All Widget Caches
Deleting all widgets removes them from the page and destroys them from memory.
/// Clean all widgets
- (void)cleanAllWidget;
# 5.2 Android
# 5.2.1 Clearing a Specific Widget Cache
For an added widget, call its destroy method.
Example code:
componentHolder?.destroy()
componentHolder = null
# 5.2.2 Clearing All Widget Caches
For all widgets, call their destroy method.
# 5.3 Harmony
# 5.3.1 Clearing a Specific Widget Cache
For an added widget, control it via @State. The widget will automatically clean up its data when the component is destroyed. It is not recommended to clear widgets using other methods.
Example code:
import { FinAppClient, FinWidget, IFinApplet } from '@finclip/sdk';
@Entry
@Component
struct WidgetPage {
@State showWidget: boolean = false
// ...
build(){
if(showWidget){
FinWidget({ widgetId: this.widgetId })
}
}
}