添加深度链接支持
深度链接可引导用户访问应用程序中的特定内容。当用户在已安装应用的设备上点击深层链接时，应用会直接打开到目标内容，如产品页面或特定体验。
奇异跟踪链接支持标准深度链接（适用于已安装的应用）和延迟深度链接（适用于新安装的应用）。有关详细信息，请参阅深度链接常见问题解答和奇异链接常见问题解答。
要求
先决条件
完成Singular Links 先决条件，为您的应用程序启用深度链接。
所需配置步骤：
- 关联域：在 Xcode 中，在 "签名和功能">"关联域 "中添加奇异自定义子域
- URL 类型：在 "信息">"URL 类型 "中将应用程序方案添加到 URL 类型中
- 奇异平台：在 Singular 平台的应用程序页面中添加 Apple DeveloperTeam ID和方案
备注：
- 如果应用程序已配置为使用 iOS 通用链接，则通用链接域已存在于关联域中，可以保留。该域应添加到 "支持的域 "配置选项中，如下文高级部分所述
- 您还必须包含Singular 自定义链接域，以便 Singular 可以跟踪营销活动的属性并处理这些营销活动的深度链接
实施 Singular 链接处理程序
SingularLinkHandler 提供了一种回调机制，用于在应用程序打开时从 Singular 跟踪链接中检索深度链接、延迟深度链接和直通参数。
可用参数：
- 深度链接：点击链接的用户在应用程序中的目标 URL
- 延迟深度链接：用户点击链接后安装应用程序的目标 URL
- 传递：通过跟踪链接传递的自定义数据，以获取更多上下文信息
- URL 参数：来自跟踪链接 URL 的所有查询参数
SDK 配置
在配置中添加 SingularLinkHandler
在 SDK 初始化过程中配置 SingularLinkHandler，以处理传入的深度链接和延迟的深度链接数据。
func getConfig() -> SingularConfig? {
// Create config with API credentials
guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
return nil
}
// Set deep link handler
config.singularLinksHandler = { params in
self.handleDeeplink(params: params)
}
return config
}
func handleDeeplink(params: SingularLinkParams?) {
// Get Deeplink data from Singular Link
let deeplink = params?.getDeepLink()
let passthrough = params?.getPassthrough()
let isDeferred = params?.isDeferred()
let urlParams = params?.getUrlParameters()
print("Deeplink: \(deeplink ?? "null")")
print("Passthrough: \(passthrough ?? "null")")
print("Is Deferred: \(isDeferred ?? false)")
// Handle deep link routing
if let url = deeplink {
handleDeepLinkRouting(url: url, isDeferred: isDeferred ?? false)
}
}- (SingularConfig *)getConfig {
// Create config with API credentials
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
andSecret:@"SDK_SECRET"];
// Set deep link handler
config.singularLinksHandler = ^(SingularLinkParams *params) {
[self handleDeeplink:params];
};
return config;
}
- (void)handleDeeplink:(SingularLinkParams *)params {
// Get Deeplink data from Singular Link
NSString *deeplink = [params getDeepLink];
NSString *passthrough = [params getPassthrough];
BOOL isDeferred = [params isDeferred];
NSDictionary *urlParams = [params getUrlParameters];
NSLog(@"Deeplink: %@", deeplink ?: @"null");
NSLog(@"Passthrough: %@", passthrough ?: @"null");
NSLog(@"Is Deferred: %d", isDeferred);
// Handle deep link routing
if (deeplink) {
[self handleDeepLinkRouting:deeplink isDeferred:isDeferred];
}
}注意：SingularLinkHandler 仅在应用程序通过 Singular Link 打开时触发。有关详细信息，请参阅Singular Links FAQ。
处理程序行为
了解 SingularLinkHandler 的执行
根据应用程序是新安装还是已安装，SingularLinkHandler 的行为会有所不同。
全新安装（延迟深度链接）
刚安装时，应用程序启动时不存在打开 URL。Singular 会完成归因，以确定跟踪链接是否包含深度链接或延迟深度链接值。
延迟深度链接流程：
- 用户点击配置了深度链接值的 Singular 跟踪链接
- 用户安装并首次打开应用程序
- Singular SDK 向 Singular 服务器发送第一个会话
- 归因完成，并从跟踪链接中识别深层链接
-
深层链接值返回 SingularLinkHandler，网址为
isDeferred = true
测试延迟深度链接：
- 从测试设备上卸载应用程序（如果当前已安装）
- 重置设备上的 IDFA（设置 > 隐私 > 苹果广告 > 重置广告标识符
- 点击设备上的 Singular 跟踪链接（确保配置了深度链接值
- 安装并打开应用程序
归因应成功完成，延迟的深度链接值将传递给 SingularLinkHandler。
专业提示在使用不同的捆绑标识符（如com.example.dev 而不是com.example.prod ）的开发构建中测试深度链接时，请专门为开发应用的捆绑标识符配置跟踪链接。点击测试链接后，通过 Xcode 或 TestFlight 将开发构建直接安装到设备上，而不是从 App Store 下载生产应用。
已安装（即时深度链接）
当应用程序已安装时，点击奇异链接可使用 iOS 通用链接技术立即打开应用程序。
即时深度链接流程：
- 用户点击奇异跟踪链接
- iOS 提供一个包含整个 Singular 跟踪链接的开放 URL
- 在 SDK 初始化过程中，Singular 会解析 NSUserActivity 或 URL
- Singular 提取深度链接和直通值
-
通过带有
isDeferred = false的 SingularLinkHandler 返回值
直通参数
使用直通参数从跟踪链接点击中获取其他数据。
如果跟踪链接中包含直通参数，SingularLinkHandler 的passthrough 参数就会包含相应的数据。使用该参数可捕获营销活动元数据、用户细分数据或应用程序中需要的任何自定义信息。
func handleDeeplink(params: SingularLinkParams?) {
// Extract passthrough data
if let passthroughData = params?.getPassthrough() {
// Parse JSON passthrough data
if let data = passthroughData.data(using: .utf8),
let jsonData = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
let campaignId = jsonData["campaign_id"] as? String
let userSegment = jsonData["segment"] as? String
print("Campaign ID: \(campaignId ?? "unknown")")
print("User Segment: \(userSegment ?? "unknown")")
}
}
}- (void)handleDeeplink:(SingularLinkParams *)params {
// Extract passthrough data
NSString *passthroughData = [params getPassthrough];
if (passthroughData) {
// Parse JSON passthrough data
NSData *data = [passthroughData dataUsingEncoding:NSUTF8StringEncoding];
NSError *error;
NSDictionary *jsonData = [NSJSONSerialization JSONObjectWithData:data
options:0
error:&error];
if (!error && jsonData) {
NSString *campaignId = jsonData[@"campaign_id"];
NSString *userSegment = jsonData[@"segment"];
NSLog(@"Campaign ID: %@", campaignId ?: @"unknown");
NSLog(@"User Segment: %@", userSegment ?: @"unknown");
}
}
}URL 参数
使用getUrlParameters() 方法捕获跟踪链接 URL 中的所有查询参数。
SingularLinkHandler 可访问跟踪链接中的所有 URL 参数，让您完全访问自定义参数和 UTM 标记。
func handleDeeplink(params: SingularLinkParams?) {
// Get all URL parameters
if let urlParams = params?.getUrlParameters() {
for (key, value) in urlParams {
print("Parameter: \(key) = \(value)")
}
// Access specific parameters
if let utmSource = urlParams["utm_source"] as? String {
print("UTM Source: \(utmSource)")
}
if let promoCode = urlParams["promo"] as? String {
print("Promo Code: \(promoCode)")
}
}
}- (void)handleDeeplink:(SingularLinkParams *)params {
// Get all URL parameters
NSDictionary *urlParams = [params getUrlParameters];
if (urlParams) {
for (NSString *key in urlParams) {
NSLog(@"Parameter: %@ = %@", key, urlParams[key]);
}
// Access specific parameters
NSString *utmSource = urlParams[@"utm_source"];
if (utmSource) {
NSLog(@"UTM Source: %@", utmSource);
}
NSString *promoCode = urlParams[@"promo"];
if (promoCode) {
NSLog(@"Promo Code: %@", promoCode);
}
}
}
跟踪链接示例：
https://yourapp.sng.link/A1b2c/abc123?_dl=myapp://product/123&utm_source=facebook&promo=SALE2024
SingularLinkHandler 可通过getUrlParameters() 方法访问所有参数，包括utm_source 和promo 。
高级配置
处理非单一通用链接
支持来自第三方合作伙伴（如 Google Ads 和 Facebook）的通用链接，用于归因跟踪。
对于 Singular iOS SDK 12.0.3 及以上版本，默认支持非 Singular 通用链接。
在旧版本的 SDK 中支持第三方深度链接：
- 每次初始化 Singular SDK 时，将所有相关域（不包括sng.link）添加到 Config 对象的supportedDomains配置选项中。
- 这样可以实现第三方深度链接行为，但无法实现深度链接的归属。要进行归因，仍需使用 Singular 跟踪链接。
- supportedDomains功能假定您已为通用链接配置了应用程序，并在您的域上托管了自己的 AASA 文件。
func getConfig() -> SingularConfig? {
guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
return nil
}
// Add supported domains for third-party Universal Links
config.supportedDomains = [
"subdomain.mywebsite.com",
"anothersubdomain.myotherwebsite.com"
]
return config
}- (SingularConfig *)getConfig {
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
andSecret:@"SDK_SECRET"];
// Add supported domains for third-party Universal Links
config.supportedDomains = @[
@"subdomain.mywebsite.com",
@"anothersubdomain.myotherwebsite.com"
];
return config;
}支持 ESP 自定义跟踪链接域
启用由电子邮件服务提供商 (ESP) 提供的通用链接，用于电子邮件营销活动归因。
ESP 域必须启用 HTTPS。Apple要求iOS 应用程序从启用 HTTPS 的端点提取 apple-app-site-association 文件，而无需重定向。请咨询您的 ESP，了解他们如何为您的应用程序托管此文件，因为这可能需要在您网站的 DNS 上进行 DNS 配置。
要支持 ESP 域，请在每次初始化 Singular SDK 时将自定义跟踪域添加到配置对象的espDomains配置选项中。
func getConfig() -> SingularConfig? {
guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
return nil
}
// Add ESP domains for email campaign tracking
config.espDomains = ["links.mywebsite.com"]
return config
}- (SingularConfig *)getConfig {
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
andSecret:@"SDK_SECRET"];
// Add ESP domains for email campaign tracking
config.espDomains = @[@"links.mywebsite.com"];
return config;
}