HFSDK 第三方宿主 App 接入指南

1. 接入前准备

Before integration, make sure the following requirements are ready.

• iOS 工程可正常编译运行
• 已获取平台分配的 appKey
• 已拿到 SDK 分发包：hfsdk.xcframework
• 使用真机联调与测试，当前分发包仅含 ios-arm64，不支持模拟器

2. 导入 SDK

Import the framework into your Xcode project and configure embedding.

1. 将 hfsdk.xcframework 拖入 Xcode 工程。
2. 在 Target 的 General -> Frameworks, Libraries, and Embedded Content 中添加 hfsdk.xcframework。
3. Embed 方式建议使用 Embed & Sign，也可按宿主工程策略调整。

3. 初始化时机

在 App 冷启动早期调用一次，通常放在 AppDelegate 中。

Call initialization once during early cold start, usually in AppDelegate.

#import <hfsdk/hfsdk.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [HFSDKManager init:application appKey:@"<YOUR_APP_KEY>"];
    return YES;
}

import hfsdk

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    HFSDKManager.initialize(withApplication: application, appKey: "<YOUR_APP_KEY>")
    return true
}

4. 初始化结果回调（推荐）

推荐使用初始化 completion 接口获取结果，回调会在主线程触发。

Use the completion API to receive initialization results. The callback is invoked on the main thread.

[HFSDKManager init:application
                         appKey:@"<YOUR_APP_KEY>"
                     completion:^(BOOL success, NSString * _Nullable reason) {
    if (success) {
        NSLog(@"[HFSDK] init success");
    } else {
        NSLog(@"[HFSDK] init failed, reason=%@", reason ?: @"unknown");
    }
}];

HFSDKManager.initialize(with: application, appKey: "<YOUR_APP_KEY>") { success, reason in
    if success {
        print("[HFSDK] init success")
    } else {
        print("[HFSDK] init failed, reason=\(reason ?? "unknown")")
    }
}

5. 广告弹框接口

SDK 提供宿主可主动调用的全屏弹框接口，推荐使用成功/失败双回调。

The SDK provides a host-triggered full-screen overlay API. The success and error callbacks are recommended.

[HFSDKManager showAd:^(HFAdOverlayResult *result) {
    NSLog(@"[HFSDK][showAd][dismiss] duration=%.0f clickStatus=%ld reason=%ld",
          result.durationSec,
          (long)result.clickStatus,
          (long)result.closeReason);
} onError:^(NSError *error) {
    NSLog(@"[HFSDK][showAd][error] domain=%@ code=%ld message=%@",
          error.domain,
          (long)error.code,
          error.localizedDescription ?: @"unknown");
}];

• 弹框展示时，SDK 会临时暂停其他 SDK WebView 动作，关闭后自动恢复
• 关闭按钮最少展示 3 秒后出现
• onDismiss 仅在展示成功并关闭时回调
• onError 仅在展示失败时回调，不会展示 WebView

系统浏览器打开

Open with the system browser.

[HFSDKManager showAd:^(HFAdOverlayResult *result) {
    NSLog(@"[HFSDK][showAd][browser] duration≈%.0f clickStatus=%ld",
          result.durationSec,
          (long)result.clickStatus);
} openInBrowser:YES onError:^(NSError *error) {
    NSLog(@"[HFSDK][showAd][error] domain=%@ code=%ld message=%@",
          error.domain,
          (long)error.code,
          error.localizedDescription ?: @"unknown");
}];

常见错误码

Common error codes.

onDismiss 回调字段

onDismiss callback fields.

• durationSec：展示时长，单位为秒
• clickStatus：点击状态，取值为 HFAdClickStatusYes、No、Unknown；外部浏览器模式为 Unknown
• closeReason：关闭原因，取值为 userClose 或 interrupted

6. 停止 SDK

当宿主需要主动停止时调用：

Call this method when the host app needs to stop the SDK manually.

[HFSDKManager stopSDK];

停止后若要重启，需再次调用初始化接口。

To restart after stopping, call the initialization API again.

7. 最小接入检查清单

Minimum checklist before launch.

1. 编译通过、无符号缺失。
2. 冷启动调用初始化。
3. 能收到初始化 completion 回调。
4. 切后台/前台后行为符合预期。
5. 若接入 showAd:onError:，可分别收到成功关闭与失败回调并记录结果。

8. 安全建议（给宿主）

Security recommendations for host apps.

• appKey 不要硬编码在可公开仓库。
• 生产构建使用正式分发包，不混用测试包。
• 升级 SDK 时同步阅读发布说明并回归关键链路。

9. 对外支持信息（建议提供给接入方）

Recommended support information for integration partners.

• SDK 版本号
• 发布日期
• 变更摘要
• 已知限制
• 技术支持联系人