iOS SDK 归因接口使用说明
归因 API 使用说明（iOS）
概述
归因模块提供的核心能力：
能力 | API | 场景 |
延迟深链还原 |
| 新安装用户首次启动 App，还原安装前点击的广告链接参数 |
拉活传参归因上报 |
| 已安装用户通过 DeepLink 被拉活时，解析链接参数并上报归因 |
剪切板归因 | handlePasteboardURL: | 读取 OneLink 写入剪切板的内容，解析深链参数并触发归因上报 |
获取归因结果 | setOnAttributionResultListener: | SDK 初始化后自动查询服务端归因结果，并通过 Block 返回最终结果 |
头文件: UMCommonDeepLink.h
快速接入
1. 注册回调（在 AppDelegate 中）
#import <UMCommon/UMCommonDeepLink.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// 1. 友盟 SDK 初始化
[UMConfigure initWithAppkey:@"YOUR_APPKEY" channel:@"App Store"];
// 2. 注册 DeepLink 回调（可选，仅拉活场景需要）
[UMCommonDeepLink sharedInstance].delegate = self;
return YES;
}
实现 UMCommonDeepLinkDelegate 协议：
@interface AppDelegate () <UMCommonDeepLinkDelegate>
@end
@implementation AppDelegate
- (void)didResolveDeepLink:(NSDictionary *)params {
// params 包含:
// @"install_params" → NSDictionary (URL query 参数键值对)
// @"install_path" → NSString (URL path 部分)
NSLog(@"拉活参数: %@", params);
NSDictionary *queryParams = params[@"install_params"];
NSString *path = params[@"install_path"];
// 根据 path 跳转对应页面
[self navigateToPage:path withParams:queryParams];
}
@end
2. 拉活传参
URL Scheme 方式（在 AppDelegate 中）
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options {
BOOL handled = [[UMCommonDeepLink sharedInstance] handleOpenURL:url];
// handled=YES 表示 URL 中包含归因参数，已触发回调和上报
return handled;
}
Universal Link 方式（在 AppDelegate 中）
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {
BOOL handled = [[UMCommonDeepLink sharedInstance] handleUserActivity:userActivity];
return handled;
}
SceneDelegate（iOS 13+）
// 冷启动
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
// URL Scheme
for (UIOpenURLContext *urlContext in connectionOptions.URLContexts) {
[[UMCommonDeepLink sharedInstance] handleOpenURL:urlContext.URL];
}
// Universal Link
for (NSUserActivity *activity in connectionOptions.userActivities) {
[[UMCommonDeepLink sharedInstance] handleUserActivity:activity];
}
}
// 热启动 - URL Scheme
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
for (UIOpenURLContext *urlContext in URLContexts) {
[[UMCommonDeepLink sharedInstance] handleOpenURL:urlContext.URL];
}
}
// 热启动 - Universal Link
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {
[[UMCommonDeepLink sharedInstance] handleUserActivity:userActivity];
}
3. DDL 延迟深链还原
#import <UMCommon/UMCommonDeepLink.h>
[[UMCommonDeepLink sharedInstance] getInstallParams:^(NSDictionary * _Nullable params, NSError * _Nullable error) {
if (params) {
// params 包含:
// @"install_params" → NSDictionary (服务端返回的安装归因参数)
// @"install_path" → NSString (广告目标页路径)
NSString *targetPath = params[@"install_path"];
NSLog(@"DDL 还原成功, targetPath=%@", targetPath);
} else {
// error.code: -1~-4，详见"错误码"章节
NSLog(@"DDL 失败: code=%ld, msg=%@", (long)error.code, error.localizedDescription);
}
}];
4. 剪切板归因
请在友盟 SDK 完成初始化后读取剪切板内容，并将读取结果传给 handlePasteboardURL:。SDK 不会主动读取系统剪切板。如需获取解析后的深链参数，请沿用前文方式提前设置 UMCommonDeepLinkDelegate。
import <UIKit/UIKit.h>
import <UMCommon/UMCommonDeepLink.h>
[UMCommonDeepLink sharedInstance].delegate = self;
NSString *content = [UIPasteboard generalPasteboard].string;
if (content.length > 0) {
BOOL handled = [[UMCommonDeepLink sharedInstance] handlePasteboardURL:content];
if (handled) {
// 内容已进入归因处理流程
}
}
剪切板归因与 handleOpenURL: 共用 UMCommonDeepLinkDelegate。已注册代理时，识别成功后 SDK 会在主线程通过 didResolveDeepLink: 返回解析结果：
- (void)didResolveDeepLink:(NSDictionary *)params {
NSDictionary *queryParams = params[@"install_params"];
NSString *path = params[@"install_path"];
[self navigateToPage:path withParams:queryParams];
}5. 获取归因结果
请在 initWithAppkey:channel: 之前注册归因结果回调。SDK 初始化完成后会自动查询服务端归因结果。
#import <UMCommon/UMConfigure.h>
[UMConfigure setOnAttributionResultListener:^(NSDictionary * _Nullable attribution,
NSInteger errorCode) {
if (errorCode == 0) {
// 归因查询成功，attribution 为服务端返回的归因结果
NSLog(@"归因结果: %@", attribution);
} else {
// errorCode == -1，表示未获得有效归因结果
NSLog(@"归因查询失败: %ld", (long)errorCode);
}
}];
[UMConfigure initWithAppkey:@"YOUR_APPKEY" channel:@"App Store"];API 详细说明
UMCommonDeepLink
门面单例类，通过 [UMCommonDeepLink sharedInstance] 获取实例。
sharedInstance
+ (instancetype)sharedInstance;
delegate
@property(weak, nonatomic) id<UMCommonDeepLinkDelegate> delegate;
注册 handleOpenURL: 的全局回调代理。
注意: 建议在 [UMConfigure initWithAppkey:channel:] 之后尽早设置，确保拉活时回调已注册。getInstallParams:
- (void)getInstallParams:(void (^)(NSDictionary * _Nullable params, NSError * _Nullable error))completion;向服务端请求 DDL（Deferred Deep Link）安装归因参数。
参数 | 类型 | 说明 |
completion | Block | 结果回调，params 和 error 互斥 |
handleOpenURL:
- (BOOL)handleOpenURL:(NSURL *)URL;
解析拉活 URL，检测有效参数触发归因回调和上报。
参数 | 类型 | 说明 |
URL | NSURL | 拉活传入的 URL（URL Scheme 或 Universal Link） |
返回值: YES 表示 URL 有效且已处理；NO 表示无归因参数，不做处理。
handleUserActivity:
- (BOOL)handleUserActivity:(NSUserActivity *)userActivity;
处理 Universal Link 拉活场景。
参数 | 类型 | 说明 |
userActivity | NSUserActivity | 系统传入的 UserActivity 对象 |
返回值: 同 handleOpenURL:。
handlePasteboardURL:
- (BOOL)handlePasteboardURL:(NSString *)urlString;处理从系统剪切板读取到的 OneLink 内容。调用前须完成友盟 SDK 初始化；如需接收参数回调，应提前设置 UMCommonDeepLinkDelegate。SDK 只处理有效内容，普通文本或明文 URL 不会被处理。
参数 | 类型 | 说明 |
urlString | NSString | 从系统剪切板读取到的 OneLink字符串 |
返回 YES 表示内容有效，SDK 已进入归因处理流程；已注册代理时会异步投递解析结果。返回 NO 表示无效内容。返回 YES 仅代表 SDK 已受理，不代表服务端最终归因成功。
注意事项补充
SDK 不会主动读取剪切板，读取时机与隐私合规由应用自行控制。建议在用户同意隐私授权后、应用处于前台且存在明确业务场景时读取；iOS 16 及以上系统可能展示粘贴授权提示。接口不对重复调用去重，同一剪切板内容应避免重复提交。
setOnAttributionResultListener:
typedef void(^UMAttributionResultBlock)(NSDictionary * _Nullable attribution,
NSInteger errorCode);
+ (void)setOnAttributionResultListener:(nullable UMAttributionResultBlock)listener;注册安装归因结果回调。建议在 SDK 初始化前调用，确保首次初始化时自动发起归因查询。
参数 | 类型 | 说明 |
listener | UMAttributionResultBlock | 归因结果回调；传 nil 可取消注册，重复注册时后注册的 Block 覆盖先前注册 |
回调参数：
参数 | 成功 | 失败 |
attribution | 服务端返回的归因结果字典 | nil |
errorCode | 0 | -1 |
归因结果字典的字段由服务端返回，接入方不应假定所有字段始终存在。
UMCommonDeepLinkDelegate
@protocol UMCommonDeepLinkDelegate <NSObject>
@optional
- (void)didResolveDeepLink:(NSDictionary *)params;
@end
handleOpenURL: 命中归因参数时的回调协议。handleOpenURL: 未命中归因（返回 NO）则不会回调。
params 字段说明:
Key | 类型 | 说明 |
install_params | NSDictionary | URL 中所有 query 参数的键值对 |
install_path | NSString | URL 的 path 部分（如 |
错误码
值 | 说明 |
-1 | 服务端匹配失败（ |
-2 | SDK 初始化未就绪（ |
-3 | 内部错误 / Appkey 缺失（ |
-4 | 网络错误或响应解析失败（ |
说明: error code -1 是正常场景（服务端无匹配记录），无需特殊处理。完整接入示例
AppDelegate.h
#import <UIKit/UIKit.h>
#import <UMCommon/UMCommonDeepLink.h>
@interface AppDelegate : UIResponder <UIApplicationDelegate, UMCommonDeepLinkDelegate>
@property (strong, nonatomic) UIWindow *window;
@end
AppDelegate.m
#import "AppDelegate.h"
#import <UMCommon/UMConfigure.h>
#import <UMCommon/UMCommonDeepLink.h>
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// 1. 友盟 SDK 初始化（正式初始化必须在用户同意隐私授权之后调用）
[UMConfigure initWithAppkey:@"YOUR_APPKEY" channel:@"App Store"];
// 2. 注册 DeepLink 回调
[UMCommonDeepLink sharedInstance].delegate = self;
// 3. 获取安装归因参数（建议在首页调用）
[[UMCommonDeepLink sharedInstance] getInstallParams:^(NSDictionary * _Nullable params, NSError * _Nullable error) {
if (params) {
NSString *targetPath = params[@"install_path"];
if (targetPath.length > 0) {
// 跳转到广告目标页
[self navigateToPage:targetPath withParams:params[@"install_params"]];
}
} else {
// 非首次安装或无匹配记录，忽略即可
}
}];
return YES;
}
#pragma mark - DeepLink 拉活处理
// URL Scheme 方式
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options {
return [[UMCommonDeepLink sharedInstance] handleOpenURL:url];
}
// Universal Link 方式
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {
return [[UMCommonDeepLink sharedInstance] handleUserActivity:userActivity];
}
#pragma mark - UMCommonDeepLinkDelegate
- (void)didResolveDeepLink:(NSDictionary *)params {
NSDictionary *queryParams = params[@"install_params"];
NSString *path = params[@"install_path"];
// 根据 path 跳转对应页面
[self navigateToPage:path withParams:queryParams];
}
@end
SceneDelegate（iOS 13+ 使用 UIScene）
#import "SceneDelegate.h"
#import <UMCommon/UMCommonDeepLink.h>
@implementation SceneDelegate
// 冷启动处理
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
// URL Scheme
for (UIOpenURLContext *urlContext in connectionOptions.URLContexts) {
[[UMCommonDeepLink sharedInstance] handleOpenURL:urlContext.URL];
}
// Universal Link
for (NSUserActivity *activity in connectionOptions.userActivities) {
[[UMCommonDeepLink sharedInstance] handleUserActivity:activity];
}
}
// 热启动 - URL Scheme
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
for (UIOpenURLContext *urlContext in URLContexts) {
[[UMCommonDeepLink sharedInstance] handleOpenURL:urlContext.URL];
}
}
// 热启动 - Universal Link
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {
[[UMCommonDeepLink sharedInstance] handleUserActivity:userActivity];
}
@end
注意事项
调用时机:
getInstallParams:仅需在 App 首次安装启动时调用一次，成功后结果会缓存，后续重复调用直接返回缓存数据。handleOpenURL 时机: 建议在
AppDelegate的application:openURL:options:和application:continueUserActivity:restorationHandler:中都调用；若使用UIScene（iOS 13+），还需在SceneDelegate对应方法中调用，确保冷启动和热启动场景均能处理。回调注册:
delegate应在handleOpenURL:之前设置，否则拉活回调会丢失。错误处理:
error.code == -1是正常场景（服务端无匹配记录），无需特殊处理。