04/29/2024 11:54:53

解决方案

Universal Link 是 Apple 从 iOS 9 引入的一种打通 web 和 app 之间跳转的机制。在 Safari 或者 WebView 中打开与 app 关联的链接时，会自动跳转到 app 并且不丢失参数内容。Universal Link 解决了 URL Scheme 的部分问题：

（1）当跳转失败时，会直接在 Safari/WebView 中打开链接；
（2）可以借助 Universal Link 统一 web 端和 native 的路由；
（3）跳转时不会弹出提示框，体验更好。

要使用 Universal Link，要将域名和 app 关联起来，这个关联是双向的：

（1）域名对 app 的认证：在 web 服务器根目录放一个名为 apple-app-site-association 的 json 文件，里面描述哪些路径会跳转到哪个 app。
（2）app 对域名的认证：在 Xcode 里设置 Associated Domains，将域名添加进去。

{
    "applinks": {
        "apps": [],
        "details": [{
            "paths": ["/app/*", "/qq_conn/1106977030/*"],
            "appID": "JBS4AWYMFX.com.tencent.itop.example"
        }, 
        {
            "paths": ["/reference2/*", "/qq_conn/1106388413/*"],
            "appID": "JBS4AWYMFX.com.tencent.imsdk2"
        }]
    }
}

注意事项：

（1）域名必须通过 HTTPS 访问 Universal Link 才能生效；
（2）apple-app-site-association 只能放在域名根目录下，不能有跳转；
（3）系统会在 app 初次安装、升级时去对应的域名下请求 apple-app-site-association 文件，如果 Universal Link 不可达，而配置都正常的话，可以尝试重启手机或重装 app。

（1）app 第一次启动或者更新版本后第一次启动（实际结果，未体现在苹果官方文档上）；
（2）app 向工程里配置的域名发起 Get 请求拉取 apple-app-site-association Json 文件；
（3）app 将 apple-app-site-association 注册到系统；
（4）由任意 WebView 发起跳转 url；
（5）如果命中了 apple-app-site-association 注册过的通用链接，则打开 app，触发 Universal Link delegate；
（6）没命中，WebView 继续跳转 url。

在进行 apple-app-site-association 以及 app Xcode 工程配置之后，整个 Universal Link 运作流程完全由系统控制。

总结，在上面第2部出现 apple-app-site-association 文件访问不可用时，会导致新安装用户后续都不能正常登录（在微信/手Q App授权界面无法跳转回游戏App），除非卸载重装。 版本要求：
  • SDK版本
    MSDKV5.7，封装 QQ OpenSDK 3.3.7、微信 OpenSDK 1.8.6版本
  • QQ 平台
    QQ App版本：8.1.3及以上
    iOS系统版本：iOS13 及以上
  • 微信平台
    微信 App 版本：7.0.7及以上
    iOS系统版本：iOS12 及以上

注意事项：

因某些原因 QQ 平台现已关闭 OpenSDK 3.3.6 版本（MSDKV5.6）的 Universal Link 授权登录能力，业务需要测试 QQ 平台该能力的需更新至 OpenSDK 3.3.7 版本，该版本 OpenSDK 已合入 MSDKV5.7 版本。

（1）新增weixinULAPI scheme白名单 info.plist中新增weixinULAPI跳转scheme白名单，否则会造成无法授权登录、分享等问题，详情见下图：

图片描述

（2）开启AppleID Associated Domains能力

根据 Apple官方文档 找证书管理相关同学申请开通 AppleID Associated Domains 的能力，如下图所示：

图片描述

AppleID 开启了 Associated Domains 的能力之后请重新生成签名描述文件。

注意事项：

因目前 Soda 和蓝盾企业签名证书暂不具备 Universal Link 能力，请各业务务必使用开发签名证书调试

（3）飞鹰系统配置Universal Link相关信息

在飞鹰系统中配置 Universal Link 参数，配置路径在飞鹰首页 -> 游戏管理 -> 我的游戏 -> SDK参数 -> 编辑iOS信息，如下图所示：

图片描述 图片描述

图片描述

Universal Link 不强制要求部署在官网域名下，只要确保部署地方高可用即可。以下描述以部署在官网下作为举例说明：

其中Universal Link一栏填写业务官网下的一个子目录且需为 https 链接，例如：https://xxx.com/app/，注意结尾必须要有/；URL Scheme一栏填写业务的 QQ 跳转 scheme，格式为tencent+qqappid，例如：tencent100703379。填写完之后点击更新游戏iOS信息按钮保存。

注意事项：

  1. 若有 QQ 相关报错提示，请先做好下一步:（4）配置apple-app-site-association
  2. 此处有任何报错均可企业微信联系MSDK助手处理
  3. 苹果在 iOS 14 及以后版本修改了 Universal Link 逻辑，会使用苹果的服务器进行 Universal Link 校验。 确认生效方式如下：
请求苹果服务器，查看返回结果确认 Universal Link 配置是否生效：
https://app-site-association.cdn-apple.com/a/v1/你的域名

你的域名 = xx.com。 如：
https://app-site-association.cdn-apple.com/a/v1/docs.msdk.qq.com

注意： https://app-site-association.cdn-apple.com/a/v1/ 为苹果服务器，后续可能会改动。如遇到无法生效的情况，请联系我们进行确认。

（4）配置apple-app-site-association

配置样例如下：

{
    "applinks": {
        "apps": [],
        "details": [{
            "appID": "JBS4AWYMFX.com.tencent.newmsdk2",
            "paths": ["/app/*", "/qq_conn/100703379/*"]
            },
            {
            "appID": "JBS4AWYMFX.com.tencent.itop.example",
              "paths": ["/app/*", "/qq_conn/1106977030/*"]
              }]
    }
}

注意事项：

  1. appID参数需修改为业务自身的签名证书 team id + bundle id；
  2. paths参数中的/app字符需替换为飞鹰上 Universal Link 中设置的官网地址 .com 后面的部分，例如飞鹰上配置的地址为https://xxx.com/client/，则此处的/app/*需替换为/client/*；
    另外 QQ 互联要求 paths 参数中必须配置为/qq_conn/QQ AppID/格式，其中 qq_conn 为固定字段，QQ AppID 填写为业务自身的 QQ AppID。如：/qq_conn/1106977030/；否则飞鹰同步信息到 QQ 互联会校验失败。如需配置多个 appID 和 paths，请参考上述事例。改好之后将文本保存为名称为apple-app-site-association的文件（注意不能加任何后缀），并将文件放置在飞鹰上 Universal Link 中设置的官网地址的根目录，需访问https://xxx.com/apple-app-site-association地址可正常下载到该文件。

（5）配置Xcode Capabilities

在 Xcode 工程 Capabilities 标签下，开启Associated Domains并配置Domains，Domains固定写applinks:+官网域名，注意无需加https://样例如下：

图片描述

5、微信客户端配置

（1）配置MSDKConfig.ini

在MSDKAppSetting.bundle/MSDKConfig.ini中新增WECHAT_UNIVERSAL_LINK_IOS的配置项，值填写飞鹰系统配置的Universal Link

6、实现 iOS 入口函数

（1）Unity

由于当前 GCloudCore 对该入口方法 hook 不生效，所以在 Unity 的UnityAppController.mm文件的 UnityAppController 类中添加 iOS 的生命周期入口函数，添加前请检查确认该入口函数是否已经存在，如果没有就手动添加（函数中不需要额外添加代码）： 注意：生命周期入口函数不要在UnityAppController的子类中添加。确保入口函数是在跟 application:openURL:options: 等系统生命周期函数在同一个类中 

- (BOOL)application:(UIApplication *)application continueUserActivity:
(NSUserActivity *)userActivity restorationHandler:(void(^)
(NSArray<id<UIUserActivityRestoring>> *
__nullablerestorableObjects))restorationHandler {
    return YES;
}

（2）UnrealEngine

在iOS 中实现一个 iOSAppDelegate 的 category ，放在 MSDKCore/Source/MSDKCore/Private/iOS 插件中。该方案使用iOS categery 实现， 有存在被其他 SDK 替换掉的风险，游戏务必验证 UL 是否生效。

新建一个 IOSAppDelegate+MSDK.mm文件，内容如下：

# define WITH_MSDK 1

# if WITH_MSDK
# ifdef __APPLE__

# import <Foundation/Foundation.h>
# import "IOSAppDelegate.h"//UnrealEngine

# include "CoreDelegates.h"//UnrealEngine
# include "MSDKApplicationDelegate.h"

@interface IOSAppDelegate(MSDK)

@end

@implementation IOSAppDelegate(MSDK)
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler
{
    NSLog(@"IOSAppDelegate(MSDK) continueUserActivity ");
    [[MSDKApplicationDelegate sharedInstance] application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
    return YES;
}
@end

# endif
# endif
MSDK V5.8.000（GCloud V2.0.14）及以上版本已使用iOS categery 实现， 有存在被其他 SDK 替换掉的风险，游戏务必验证 UL 是否生效

（1）微信平台

需拉起微信授权登录成功且MSDK日志中包含call [WXApi handleOpenUniversalLink:delegate字样，日志样例如下图所示：

图片描述

（2）QQ平台

需拉起QQ授权登录成功且MSDK日志中包含universal link continueUserActivity called字样，日志样例如下图所示：

图片描述

注意事项：

因目前 Soda 和蓝盾企业签名证书暂不具备 Universal Link 能力，请各业务务必使用开发签名证书调试

8、参考

（1）Universal Links for Developers

（2）Enabling Universal Links

（3）苹果官方的UL测试工具

（4）微信

（5）手Q



Copyright © 2024 MSDK.
All rights reserved.

results matching ""

    No results matching ""