iOS 接入
收藏我的收藏
前提条件
- •授权、分享版 v4.2.6 最低支持 iOS 15.0;需兼容 iOS 9–14 的工程请使用 v4.2.5。推荐 Xcode 15.0 及以上版本。
注意
抖音不再支持低版本iOS系统
iOS 9.0 系统能使用的最新抖音版本为 17.8.0
iOS 10.0 系统能使用的最新抖音版本为 23.0.0
iOS 11.0 系统能使用的最新抖音版本为 27.5.0
iOS 12.0 系统能使用的最新抖音版本为 35.5.0
- •获取 ClientKey:
- ◦请到开发者应用登记页面进行申请,申请后将获得 AppID。具体步骤请参见创建移动应用和网站应用。
- ◦通过 AppID 为应用申请相关的权限,如分享、授权、默认话题等。
- ◦审核通过后即可使用相关的功能。
接入流程
- 1.集成 SDK。
- ◦通过 CocoaPods 集成(推荐)。
- ◦手动集成。
- 2.配置 SDK。
- ◦配置 URLScheme。
- ◦配置相册使用权限。
- 3.SDK 代码配置。
- ◦初始化以及 UIApplicationDelegate 部分。
- ◦获取日志信息。
操作步骤
第一步:集成 SDK
可以通过 CocoaPods(推荐)或手动(不推荐)两种方式集成 SDK。
通过 CocoaPods 集成(推荐)
- 1.在工程的 Podfile 中添加 SDK。
pod 'DouyinOpenSDK'
- 2.运行
pod install 命令安装 SDK。pod install --repo-update
运行
pod install 不会自动更新 repo,如果下载的不是最新版,可使用 pod install --repo-update 更新或先运行 pod repo update。已安装旧版 SDK 的工程,请执行
pod update DouyinOpenSDK --repo-update。需兼容 iOS 9–14 时,使用 pod 'DouyinOpenSDK', '4.2.5'。注意
包含【外部版本名片】能力的SDK暂不支持通过cocoapods集成
手动集成
- 1.下载 SDK 包
- a.包含【授权】【分享】能力: DouyinOpenSDK(v4.2.6)。
- b.包含【授权】【分享】【外部版本名片】能力: DouyinOpenSDK-external-profile(v4.2.4-external-profile)
注意
以上SDK静态包选择其一下载即可。
- 2.集成 Framework。v4.2.6 请将下文的
DouyinOpenSDK.framework 替换为 DouyinOpenSDK.xcframework,并将解压目录下的 Resources/DYOpenCore.bundle 添加到「TARGETS」>「Build Phases」>「Copy Bundle Resources」。旧版和名片包仍按以下步骤接入。在 Xcode 13.0 版本上的具体操作步骤如下:- a.将解压后的
DouyinOpenSDK.framework 文件复制或拖拽到工程文件夹中。- b.在左侧目录选中工程名,选择 「TARGETS」>「Build Phases」>「Link Binary With Libraries」 。
- c.点击「+」按钮,在弹出的窗口中点击「Add Other」,选择工程目录下的
DouyinOpenSDK.framework 文件添加到工程中。- d.在左侧目录选中工程名,选择 「TARGETS」>「Build Phases」>「Link Binary With Libraries」 。
- e.点击「+」按钮,在弹出的窗口中查找并选择下列所需的库,单击「Add」,将系统库文件添加到工程中。
- i.
WebKit.framework :SDK 内部采用 Web 授权时所使用。- ii.
SystemConfiguration.framework :SDK 内部采用 Web 授权时所使用。- iii.
Network.framework :SDK 内部采用 Web 授权时所使用。- iv.
Security.framework:SDK 传递信息安全的加解密库。- v.
CoreData:SDK 存储埋点数据使用的数据库- vi.
QuartzCore:SDK 计算方法耗时时使用- f.在左侧目录选中工程名,然后选择「TARGETS」>「Build Settings」>「Other Linker Flags」 ,在「Other Linker Flags」 页面中添加
-ObjC,字母 O 和 C 大写。- g.如果工程「TARGETS」>「Build Settings」中的
Mach-O Type是static library类型,则需要在「Other Linker Flags」 页面中添加-all_load。注意
在 Xcode 升级之后,系统可能会还原部分配置。若在未升级 SDK 却升级了 Xcode 的情况下,出现诸如 "unrecognized selector" 之类的问题,可以重新检查接入流程,补充缺失的参数。
第二步:配置工程
下列步骤是在 Xcode 13.0 版本上的操作。
- 1.配置 URLScheme:在通过 CocoaPods 或手动将 SDK 引入工程之后,需要 配置 app 与抖音短视频通讯的 URLScheme。
- a.为了保证可以正常唤起抖音短视频,在「info」标签栏的
Custom iOS Target Properties中找到 LSApplicationQueriesSchemes 。如果没有,点击「+」添加一个并设置 Key 为LSApplicationQueriesSchemes,Value 类型为数组,将如下配置粘贴到数组中(在iOS15.0及以上版本,需要设置在前50位以内)。<key>LSApplicationQueriesSchemes</key> <array> <string>douyinopensdk</string> <string>douyinliteopensdk</string> <string>douyinsharesdk</string> <string>snssdk1128</string> </array>
- b.为了保证抖音短视频可以正常唤起你的 App,在 Xcode 中,点击「TARGETS」,在「info」标签栏的最下面的 URL Types 的
URL Schemes 中填入申请得到的 ClientKey。你的 App 通过这个 URL Schemes 接收抖音短视频完成请求后的通信。- c.在「info」标签栏的「Custom iOS Target Properties」中点击「+」新加一项设置 Key 为
DouyinAppID,value 为 String 类型,值为申请的 AppID。在 App 启动时会自动将配置同步到 SDK 中。DouyinAppID 即 ClientKey。注意: 如果不想通过 Info.plist 的方式向 SDK 注册你的 Key,也可以按如下方式通过代码方式进行注册。[[DouyinOpenSDKApplicationDelegate sharedInstance] registerAppId:DouYinNewClientKey];如果你同时使用了两种设置方式,将按照 - [DouyinOpenSDKApplicationDelegate application: didFinishLaunchingWithOptions:]和 - [DouyinOpenSDKApplicationDelegate registerAppId:] 调用顺序进行覆盖,后者覆盖前者。- 2.配置相册使用权限。分享的图片通过相册进行跨进程共享,如需使用分享功能,还需要填写相册访问权限,在 info 标签栏中添加 Privacy - Photo Library Usage Description。注意:请务必保证正确填写 ClientKey,并确保与网页申请时填写的 BundleID 及工程配置中的 BundleID 一致。
第三步:SDK 代码配置
初始化 DouyinOpenSDKApplicationDelegate
最佳实践:
- 1.建议在实际调用之前初始化
DouyinOpenSDKApplicationDelegate,您也可以在 AppDelegate 或者 SceneDelegate 中进行初始化,但是要保证初始化操作在用户同意 App 隐私协议之后进行// 用户已经同意了App的隐私协议弹窗 // .... 业务代码 // 初始化DouyinOpenSDKApplicationDelegate [[DouyinOpenSDKApplicationDelegate sharedInstance] application:nil didFinishLaunchingWithOptions:nil]; // 执行授权/分享/投稿操作 // .... 业务代码
警告
由于个人信息保护法的实施,开发者需要确保初始化 DouyinOpenSDKApplicationDelegate 的时机在用户同意隐私协议之后。
如果因代码架构问题实现困难,可在代码初始化之后设置 openAutoTracker 参数为 NO(需在隐私协议同意后设为 YES),在用户同意隐私协议后,设置 openAutoTracker 参数为 YES
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // 隐私协议弹窗用户还未确认 [[DouyinOpenSDKApplicationDelegate sharedInstance] application:application didFinishLaunchingWithOptions:launchOptions]; [DouyinOpenSDKApplicationDelegate sharedInstance].openAutoTracker = NO; // ... // 隐私协议弹窗用户已确认 [DouyinOpenSDKApplicationDelegate sharedInstance].openAutoTracker = YES; // 执行授权/分享/投稿等操作 return YES; }
- 2.同时您还需要在应用被抖音主动唤起的时候,获取唤起url,传递给SDK进行解析,触发您设置的回调。
注意
如果您发现授权/分享/投稿后,抖音无法跳转到您的应用,请检查这部分代码是否接入正常!!!
// 如果使用 SceneDelegate - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts { // 示例代码 [[DouyinOpenSDKApplicationDelegate sharedInstance] application:nil openURL:URLContexts.allObjects.firstObject.URL.absoluteURL sourceApplication:nil annotation:nil]; } // 如果使用 AppDelegate - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url { if ([[DouyinOpenSDKApplicationDelegate sharedInstance] application:application openURL:url sourceApplication:nil annotation:nil]) { return YES; } return NO; }
一般接入:
- •如果使用 SceneDelegate: 冷启动时,从
scene:willConnectToSession:options: 的 connectionOptions.URLContexts 获取回跳 URL,并调用下方的 application:openURL:sourceApplication:annotation: 处理。若 SDK 尚未初始化,先保留 URL,待用户同意隐私协议并完成初始化后再处理。热启动仍通过 scene:openURLContexts: 接收 URL。#import <DouyinOpenSDK/DouyinOpenSDKApplicationDelegate.h> - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions { // ... [[DouyinOpenSDKApplicationDelegate sharedInstance] application:nil didFinishLaunchingWithOptions:nil]; // ... } - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts { // 示例代码 [[DouyinOpenSDKApplicationDelegate sharedInstance] application:nil openURL:URLContexts.allObjects.firstObject.URL.absoluteURL sourceApplication:nil annotation:nil]; }
- •如果使用 AppDelegate:
在 AppDelegate 中引入<DouyinOpenSDK/DouyinOpenSDKApplicationDelegate.h>头文件并在 app 启动、收到 Open URL 打开 app 时调用 SDK 进行处理。
#import <DouyinOpenSDK/DouyinOpenSDKApplicationDelegate.h> @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [[DouyinOpenSDKApplicationDelegate sharedInstance] application:application didFinishLaunchingWithOptions:launchOptions]; return YES; } - (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options { if ([[DouyinOpenSDKApplicationDelegate sharedInstance] application:application openURL:url sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey] annotation:options[UIApplicationOpenURLOptionsAnnotationKey]] ) { return YES; } return NO; } - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { if ([[DouyinOpenSDKApplicationDelegate sharedInstance] application:application openURL:url sourceApplication:sourceApplication annotation:annotation]) { return YES; } return NO; } - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url { if ([[DouyinOpenSDKApplicationDelegate sharedInstance] application:application openURL:url sourceApplication:nil annotation:nil]) { return YES; } return NO; } @end
注册 Log 代理
注册 Log 代理用于获取并打印 SDK 产出的日志信息,便于排查问题。
通过向
DouyinOpenSDKApplicationDelegate 注册 Log 的代理 DouyinOpenSDKLogDelegate 并实现 onLog 方法,可以收到 SDK 内部的一些错误或警告信息。#import <DouyinOpenSDK/DouyinOpenSDKApplicationDelegate.h> @interface AppDelegate () <DouyinOpenSDKLogDelegate> #pragma mark - (void)registerLogDelegate { [DouyinOpenSDKApplicationDelegate sharedInstance].logDelegate =self; } #pragma mark - DouyinOpenSDKLogDelegate Delegate - (void)onLog:(NSString *)logInfo { //Process log // 建议将log打印或者使用您自己的日志基建打印出来,便于查找接入问题。 } @end
常见问题
Q:运行后,出现
NSFetchRequest could not locate an NSEntityDescription for entity name 'DYOpenKVItem' Crash问题A:请检查是否正确引入 DYOpenCore.bundle ,可以尝试手动引入该Bundle文件。
v4.2.6 的 Bundle 文件位于
Pods/DouyinOpenSDK/Resources/DYOpenCore.bundle;v4.2.5 和当前名片包仍位于 Pods/DouyinOpenSDK/DouyinOpenSDK.framework/Resources/DYOpenCore.bundle。
Q:打包上传时,出现
Unexpected CFBundleExecutable Key 问题Unexpected CFBundleExecutable Key. The bundle at 'xxx/xxx.app/DYOpenCore.bundle does not contain a bundle executable. If this bundle intentionally does not contain an executable, consider removing the CFBundleExecutable key from itInfo.plist and using a CFBundlePackageType of BNDL. If this bundle is part of a third-party framework, consider contacting the developer of the framework for an update to address this isue. (İD: xxx)
A:该问题已在 DouyinOpenSDK v4.2.5 中解决,请升级至 v4.2.5 或更高版本。若当前使用 v4.2.4(包括 v4.2.4-external-profile)且暂时无法升级,可找到
Pods/DouyinOpenSDK/DouyinOpenSDK.framework/Resources/DYOpenCore.bundle/info.plist ,手动删除 CFBundleExecutable 键。