ZJSDK

SDK 集成

SDK 集成

此章节将演示如何集成ZJSDK到您的原生项目中。

温馨提示

请找运营人员获取应用ID和广告位ID。

SDK接入后，需要使用真机进行调试

接入完成后，在正式上线前需要提供测试包，测试广告是否正常展现

打包回测

企业账号可直接打包。 公司账号或个人账号打包回测请添加下面的测试设备的udid：

e36a75f610d3ea9e905c2cdff9720635b37f8c13

c1073d3ab1b89d8f3d8036f9ed602315b3934eeb

00008110-001450A20121A01E

一. 版本配置

SDK可运行于 iOS 11.0 及以上版本，请确保PROJECT -> Deployment Target -> iOS Deployment Target 选择大于等于 11.0

二. Xcode编译选项设置

运行环境支持

  • 支持系统 iOS 11.X 及以上;
  • 支持架构： x86-64, armv7, arm64
  • SDK编译环境 Xcode 14.0 + （23年4月起，Xcode 14以下编译的包不再支持上架app store）
  • xcode 15.0 +，请把TARGETS -> Build Settings -> Build Options -> User Script Sandboxing 设置为NO

三. 工程设置导入framework

1. Cocoapods接入方式

首先需要在项目中配置pod环境，pod环境配置过程略

1.1 一般引入方式

#引入常用广告模块  
pod 'ZJSDK'

1.2 拆分模块引入方式

#常用广告模块（如需模块拆分引入，请引入ZJSDKModuleDSP）
pod 'ZJSDK/ZJSDKModuleDSP'#依赖库，引入任何模块都需要依赖此模块，默认引入
pod 'ZJSDK/ZJSDKModuleGDT'#优量汇广告
pod 'ZJSDK/ZJSDKModuleCSJ'#穿山甲广告
pod 'ZJSDK/ZJSDKModuleKS'#快手广告
pod 'ZJSDK/ZJSDKModuleSIG'#Sigmob广告
pod 'ZJSDK/ZJSDKModuleBD'#百度广告
pod 'ZJSDK/ZJSDKModuleBeiZi'#倍孜广告
pod 'ZJSDK/ZJSDKModuleTanX'#TanX广告
pod 'ZJSDK/ZJSDKModuleQM'#趣盟广告
pod 'ZJSDK/ZJSDKModuleOCTOPUS'#章鱼广告
pod 'ZJSDK/ZJSDKModuleYK'#移卡广告
pod 'ZJSDK/ZJSDKModuleJiaJi'#奇运广告

#海外模块(默认不引入)
pod 'ZJSDK/ZJSDKModuleGoogle'#Google广告 
pod 'ZJSDK/ZJSDKModulePangle'#穿山甲海外 
pod 'ZJSDK/ZJSDKModuleMTG'#MTG广告

#聚合广告模块（默认不引入）
#注意：引入多个聚合广告可能会引起一些联盟重复初始化的问题。
pod 'ZJSDK/ZJSDKModuleWM'     #Sigmob to-bid广告

注意

如果您项目已经集成有其他家SDK，比如项目已经引入了有快手SDK，再次引入我们的快手适配器，可能存在依赖快手SDK版本不同会有错误，请按照如下方式引入

pod 'ZJSDK/ZJSDKModuleGDTCompatible'#优量汇广告
pod 'ZJSDK/ZJSDKModuleCSJCompatible'#穿山甲广告
pod 'ZJSDK/ZJSDKModuleKSCompatible'#快手广告
pod 'ZJSDK/ZJSDKModuleSIGCompatible'#Sigmob广告
pod 'ZJSDK/ZJSDKModuleBDCompatible'#百度广告
pod 'ZJSDK/ZJSDKModuleBeiZiCompatible'#倍孜广告
pod 'ZJSDK/ZJSDKModuleTanXCompatible'#TanX广告
pod 'ZJSDK/ZJSDKModuleQMCompatible'#趣盟广告
pod 'ZJSDK/ZJSDKModuleOCTOPUSCompatible'#章鱼广告
pod 'ZJSDK/ZJSDKModuleYKCompatible'#移卡广告
pod 'ZJSDK/ZJSDKModuleJiaJiCompatible'#奇运广告

1.3 本地视频内容（类似dy，ks短视频）引入方式 接入视频内容注意事项，请转到ZJContentPage接入注意事项，新版本SDK不再需要单独引入快手内容包

# 在以上引入的基础上，将快手库指定为本地内容包
pod 'KSAdSDK',:path => '../ZJSDK/ZJSDKModuleKS'#指定快手库为本地内容库

2. 手动导入的方式

2.1. 获取 framework 文件后直接将 {ZJSDK}文件拖入工程即可。

2.2. 前往项目的Build Setting中的Enable Bitcode设置为NO

2.3. Build Settings中Other Linker Flags 增加参数-ObjC和-l 'ObjC'，字母o和c大写

2.4. 升级SDK的同学必须同时更新framework和bundle文件，否则可能出现部分页面无法展示的问题，老版本升级的同学需要重新引入ZJSDK.framework，引入完请确保Copy Bundle Resources中有BUAdSDK.bundle，DSPBundle.bundle等否则可能出现icon图片加载不出来的情况。

2.5. 添加依赖库

工程需要在TARGETS -> Build Phases中找到Link Binary With Libraries，点击“+”,
依次添加下列依赖库
  • libsqlite3.0.tbd
  • JavaScriptCore.framework
  • AudioToolbox.framework
  • QuickLook.framework
  • MessageUI.framework
  • AVKit.framework
  • DeviceCheck.framework
  • CFNetwork.framework
  • CoreGraphics.framework
  • SafariServices.framework
  • StoreKit.framework
  • MobileCoreServices.framework
  • WebKit.framework
  • MediaPlayer.framework
  • CoreMedia.framework
  • CoreLocation.framework
  • AVFoundation.framework
  • CoreTelephony.framework
  • SystemConfiguration.framework
  • AdSupport.framework
  • CoreMotion.framework
  • Accelerate.framework
  • libresolv.9.tbd
  • libc++.tbd
  • libz.tbd
  • libsqlite3.tbd
  • libbz2.tbd
  • libxml2.tbd
  • QuartzCore.framework
  • Security.framework
  • libc++abi.tbd
  • libiconv.tbd
  • AppTrackingTransparency.framework
  • CoreText.framework
  • MapKit.framework
  • CoreImage.framework
  • ImageIO.framework
  • SystemConfiguration.framework
  • CoreTelephony.framework
  • Security.framework
  • AddressBook.framework
  • CoreData.framework
  • MessageUI.framework
  • QuickLook.framework
  • AudioToolBox.framework
  • Photos.framework

注意事项

  • 快手广告：

    • 手动导入快手广告需.前往项目的： Targets-当前项目-General-Frameworks,Libraries,and Embedded Content。 将KSAdSDK.xcframework - Do Not Embed 更改为 Embed & Sign 否则导入后启动将会闪退

  • Google广告：

    • 需要在info.plist 添加GADApplicationIdentifier字段，value为AppId ,如果使用了Google广告sdk且未在info.plist中配置，会导致运行时错误，参考网站open in new window
<key>GADApplicationIdentifier</key>
<string>申请的Google广告的appid</string>

Google启用测试广告，参考网站open in new window

  • MTG 广告：
    • 手动添加SDK依赖配置 从Mintegral iOS SDK v7.5.4版本开始，内部用到了Swift语言。如果您在项目中没有使用Swift，您需要确保添加以下依赖项：
    • 选择 Project > BuildSettings > Defines Module: 设置为 Yes
    • 选择 Project > BuildSettings > Search path > Library Search Paths, 并添加如下代码:
$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)
$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)

之后在 Project > BuildSettings > Linking > Runpath search path, 然后添加如下代码:

#该路径需要配置在list的第一个
/usr/lib/swift

最后在 Project > BuildSettings > Build option > Always embed swift standard libraries: 设置为 Yes

提示

导入后无法编译等问题详见常见问题-编译

四. 权限声明

1. 添加HTTP权限

工程plist文件设置，点击右边的information Property List后边的 "+" 展开 添加 App Transport Security Settings，先点击左侧展开箭头，再点右侧加号，Allow Arbitrary Loads 选项自动加入，修改值为 YES。 SDK API 已经全部支持HTTPS，但是广告主素材存在非HTTPS情况。

<key>NSAppTransportSecurity</key>
  <dict>
     <key>NSAllowsArbitraryLoads</key>
   <true/>
</dict>

切记

千万不要在NSAllowsArbitraryLoads这个属性 之后 再去设置 Allow Arbitrary Loads in Web Content 这个属性，否则会影响SDK的正常功能的使用

2. 添加位置权限

SDK 需要位置权限以更精准的匹配广告，需要在应用的 info.plist 添加相应配置信息，避免 App Store 审核被拒：

Privacy - Location When In Use Usage Description
Privacy - Location Always and When In Use Usage Description
Privacy - Location Always Usage Description
rivacy - Location Usage Description

3. scheme列表添加以下内容

用于判断用户设备使用环境，提高安全性，增加收益，需要在应用的 info.plist 添加相应配置信息。 默认状态开启检测断言，需要关闭请联系客服修改配置。

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>alipayauth</string>
    <string>alipays</string>
    <string>alipay</string>
    <string>wechat</string>
    <string>weixin</string>
    <string>taobao</string>
    <string>tbopen</string>
    <string>openapp.jdmobile</string>
    <string>pinduoduo</string>
    <string>meituanwaimai</string>
    <string>imeituan</string>
    <string>snssdk1128</string>
    <string>kwai</string>
    <string>cydia</string>
    <string>cainiao</string>
    以下为集成趣盟所需要的，没有集成则可以不加
    <string>soul</string>
    <string>weixinULAPI</string>
    <string>mqq</string>
    <string>mqqapi</string>
    <string>mqqopensdkapiV2</string>
    <string>mqqopensdkapiV4</string>
    <string>jdmobile</string>
    <string>openjdlite</string>
    <string>openapp.jdpingou</string>
    <string>taobaolite</string>
    <string>taobaolive</string>
    <string>taobaotravel</string>
    <string>tmall</string>
    <string>ctrip</string>
    <string>palfish-read</string>
    <string>douyutv</string>
    <string>fleamarket</string>
    <string>youku</string>
    <string>sinaweibohd</string>
    <string>weibosdk</string>
    <string>sinaweibo</string>
    <string>baidumobads</string>
    <string>itms-beta</string>
    <string>pddopen</string>
    <string>snssdk35</string>
    <string>snssdk1112</string>
    <string>snssdk2329</string>
    <string>vipshop</string>
    <string>dewuapp</string>
    <string>suning</string>
    <string>suningebuy</string>
    <string>iting</string>
    <string>baiduhaokan</string>
    <string>lianjia</string>
    <string>lianjiabeike</string>
    <string>usage_crazyreader</string>
    <string>dianping</string>
    <string>pajkdoctor</string>
    <string>eleme</string>
    <string>onetravel</string>
    <string>qunariphone</string>
    <string>xhsdiscover</string>
    <string>bilibili</string>
    <string>mttbrowser</string>
    <string>dragon1967</string>
    <string>ttnewssso</string>
    <string>wbmain</string>
    <string>awemesso</string>
    <string>douyinopensdk</string>
    <string>mp1089867489</string>
    <string>sohuvideo-iphone</string>
    <string>quark</string>
    <string>momochat</string>
    <string>bdboxiosqrcode</string>
    <string>freereader</string>
    <string>ucbrowser</string>
    <string>gifshow</string>
    <string>weishiiosscheme</string>
    <string>qqnews</string>
    <string>qmkege</string>
    <string>yymobile</string>
    <string>yykiwi</string>
    <string>sinanews</string>
    <string>paesuperbank</string>
    <string>qiyi-iphone</string>
    <string>iqiyi</string>
    <string>baidumap</string>
    <string>openanjuke</string>
    <string>bds</string>
    <string>shuabao</string>
    <string>orpheuswidget</string>
    <string>qqmusic</string>
    <string>zhihu</string>
    <string>cmblife</string>
    <string>iosamap</string>
    <string>sinafinance</string>
    <string>zhwnl</string>
    <string>kugouURL</string>
    <string>ksnebula</string>
    <string>BaiduIMShop</string>
    <string>com.sogou.sogouinput</string>
    <string>tenvideo</string>
    <string>qmtoken</string>
    <string>dzhiphone</string>
    <string>doubanradio</string>
    <string>amihexin</string>
    <string>rm434209233MojiWeather</string>
    <string>com.kuwo.kwmusic.kwmusicForKwsing</string>
    <string>camcard</string> <string>camscanner</string>
    <string>com.kingsoft.powerword.6</string>
    <string>comIfeng3GifengNews</string>
    <string>buka</string>
    <string>yddictproapp</string>
    <string>gtgj</string>
    <string>elongiPhone</string>
    <string>baiduvideoiphone</string>
    <string>wireless1688</string>
    <string>bitauto.yicheapp</string>
    <string>app.soyoung</string>
    <string>weiyun</string>
    <string>xunlei</string>
    <string>mdopen</string>
    <string>mdsopen</string>
    <string>flyreader</string>
    <string>novelfm3040luckydog</string>
    <string>baiduboxlite</string>
    <string>quantgroup</string>
    <string>tantanapp</string>
    <string>usagecrazyreaderios</string>
    <string>dingdongneighborhood</string>
    <string>duapp</string>
    <string>hlluapp</string>
    <string>msec</string>
    <string>bosszp</string>
    <string>tuhu</string>
    <string>bdminivideo</string>
    <string>shuqireader</string>
    <string>txvideo</string>
    <string>baiduboxmission</string>
    <string>com.baidu.tieba</string>
    <string>qihooloan</string>
    <string>travelguide</string>
    <string>kaola</string>
    <string>tomas</string>
    <string>secoo</string>
    <string>taoumaimai</string>
    <string>amapuri</string>
    <string>vmall</string>
    <string>miguvideo</string>
    <string>comjia</string>
    <string>bitauto.yicheapp</string>
    <string>yanxuan</string>
</array>

4. 如果项目里面集成的有DSPSDK模块

  1. 如果集成DSPSDK模块，媒体有使用原生跳转到微信小程序页面的需求，则需要单独导入WechatOpenSDK 在工程的 Podfile 里面添加以下代码：
pod 'WechatOpenSDK'

  1. 开发者需要在工程中链接上:Security.framework, CoreGraphics.framework, WebKit.framework,如果工程中有，则不需要再次添加

  2. Build Settings中Other Linker Flags 增加参数-ObjC和-all_load

  3. 下面两个配置信息是DSPSDK从原生跳转到微信小程序使用的，如果没有集成DSPSDK，则不需要添加，如果有集成DSPSDK，使用了原生跳转到微信小程序页面，必须添加以下两个配置

<key>LSApplicationQueriesSchemes</key>
<array>
<string>weixin</string>
<string>weixinURLParamsAPI</string>
<string>weixinULAPI</string>
</array>
  1. 如果有集成DSPSDK，使用了原生跳转到微信小程序页面，在 Xcode 中，选择你的工程设置项，选中“TARGETS”一栏，在“info”标签栏的“URL Types“添加“URL scheme”为你所注册的应用程序id，如果不集成，则不需要添加

注意

如果项目里面集成的有DSPSDK模块，要使用跳转微信小程序的功能，则必须加上这个配置，否则无法正常调整到微信小程序

** 以上是配置DSPSDK的从原生拉起微信小程序页面功能，如果有导入DSPSDK模块的媒体，我们建议自行加入以上配置

五. Swift接入准备

1.新建桥接头文件（bridge.h，推荐放在工程目录下）。这里我们命名为：ZJAdSDKDemoSwift-Bridging-Header.h。在这个文件中import我们需要的所有头文件，代码如下：

#import <ZJSDK/ZJSDK.h>

2.左侧目录中选中工程名，在 TARGETS->Build Settings-> Swift Compiler - Code Generation -> Objective-C Bridging Header 中输入桥接文件的路径

六. iOS 14 注意事项

1. iOS 14.5及以上版本ATT权限申请

App Tracking Transparency(ATT) 框架向用户提出应用程序跟踪授权请求，并提供跟踪授权状态。自iOS14.5 开始，在应用程序调用 ATT 向用户提跟踪授权请求之前，IDFA 将不可用。如果应用未提出此请求，应用获取到的 IDFA 将为0，建议您在应用启动时调用，以便我们能够提供更精准的进行广告投放和收入优化。

要获取 ATT 权限，请更新您的 Info.plist，添加 NSUserTrackingUsageDescription 字段和自定义文案描述。代码示例：

<key>NSUserTrackingUsageDescription</key>
<string>该标识符将用于向您投放个性化广告</string>

请先确保项目中已经正确引入AdSupport.framework和AppTrackingTransparency.framework，可在TARGETS -> Link Binary With Libraries下查看。

向用户申请权限时，请调用 requestTrackingAuthorizationWithCompletionHandler:方法。我们建议您申请权限后再请求广告，以便广告能准确的获得用户授权状态。

  • oc
#import <AppTrackingTransparency/AppTrackingTransparency.h>
#import <AdSupport/AdSupport.h>

- (void)applicationDidBecomeActive:(UIApplication *)application { 
    if (@available(iOS 14.0, *)) {
        // iOS14及以上版本需要先请求权限
        dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(2.0 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
            [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
                // 获取到权限后，依然使用老方法获取idfa
                if (status == ATTrackingManagerAuthorizationStatusAuthorized) {
                    NSString *idfa = [[ASIdentifierManager sharedManager].advertisingIdentifier UUIDString];
                } else {
                    NSLog(@"请在设置-隐私-跟踪中允许App请求跟踪");
                }
            }];
        });
    } else {
        // iOS14以下版本依然使用老方法
        // 判断在设置-隐私里用户是否打开了广告跟踪
        if ([[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]) {
            NSString *idfa = [[ASIdentifierManager sharedManager].advertisingIdentifier UUIDString];
        } else {
            NSLog(@"请在设置-隐私-广告中打开广告跟踪功能");
        }
    } 
}
  • swift
import AdSupport
import AppTrackingTransparency

override func applicationDidBecomeActive(_ application: UIApplication) {
    DispatchQueue.main.asyncAfter(deadline: .now() + 2.0) {
        if #available(iOS 14.0, *) {
            AppTrackingManager.requestTrackingAuthorization { status in 
                switch status {
                    case .authorized:
                        print("用户授权跟踪")
                    case .denied:
                        print("用户拒绝授权")
                    case .restricted:
                        print("跟踪被限制")
                    case .notDetermined:
                        print("用户尚未决定")
                    @unknown default:
                        print("未知的跟踪状态")
                }
            }
        }
    }
}

注意

  • 请求idfa权限的这个方法需要在applicationDidBecomeActive中调用，如果在 didFinishLaunchingWithOptions这个方法中调用，那么可能不会弹出授权弹窗，最终导致获取不到idfa。
  • 上架AppStore时，有些系统无法弹出授权弹窗，请把申请权限代码延迟2秒左右加载即可。

2. SKAdNetwork 接入

使用Apple的转化跟踪SKAdNetwork，这意味着即使IDFA不可用，也可以将应用安装归因。 1.在Xcode项目导航器中，选择Info.plist。 2.单击属性列表编辑器中任何键旁边的添加按钮（+），以创建一个新的属性键。 3.输入密钥名称SKAdNetworkItems。选择Array。 4.将SKAdNetworkId以字典的形式添加到数组中。

//将SKAdNetwork ID 添加到 info.plist 中，以保证 SKAdNetwork 的正确运行
//广点通
SKAdNetworkIdentifier : f7s53z58qe.skadnetwork
//快手
SKAdNetworkIdentifier : r3y5dwb26t.skadnetwork
//sigmob
SKAdNetworkIdentifier : 58922NB4GD.skadnetwork
//MTG
SKAdNetworkIdentifier : kbd757ywx3.skadnetwork
//穿山甲
SKAdNetworkIdentifier : 238da6jt44.skadnetwork
SKAdNetworkIdentifier : x2jnk7ly8j.skadnetwork
SKAdNetworkIdentifier : 22mmun2rn5.skadnetwork
//Google
SKAdNetworkIdentifier : cstr6suwn9.skadnetwork

info.plist代码示例

<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>238da6jt44.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>x2jnk7ly8j.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>f7s53z58qe.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>58922NB4GD.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>kbd757ywx3.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>22mmun2rn5.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>r3y5dwb26t.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cstr6suwn9.skadnetwork</string>
    </dict>
</array>

3. 所有类型广告的接入注意事项

特别注意

ZJSDK所有类型的广告，请求广告展示的时候，必须每次都要先加载广告，不能使用一次加载多次展示，否则会出现问题，包括代码的初始化和设置delegate，都需要重新执行。

4. 所有广告类型的接入，新版本都支持bidding竞价成功/竞价失败的事件回传

bidding比价竞胜/竞败方法

  • 竞胜
/**
 * @brief 设置竞价价格，单位（分）
 * @param ecpm              竞价价格
 * @param highestLossEcpm   最大竞价失败方出价
 */
- (void)setBidEcpm:(NSInteger)ecpm
   highestLossEcpm:(NSInteger)highestLossEcpm
  • 竞败
/**
 * @brief 广告曝光失败后上报失败原因
 * @param failureCode 曝光失败原因类型
 * @param reportParam 曝光失败原因描述
 *        reportParam.winEcpm 胜出者的ecpm报价（单位：分）
 *        reportParam.adnType 胜出方，见ZJAdExposureReportParam.h 中ZJAdExposureAdnType定义
 *        reportParam.adnName 胜出平台名，见ZJAdExposureReportParam.h 中ZJAdADNType平台定义
 */
- (void)reportAdExposureFailed:(ZJAdExposureFailureCode)failureCode reportParam:(ZJAdExposureReportParam *)reportParam;

特别注意

所有类型的广告，媒体在对接的时候，都可以拿我们的广告和别人家的广告进行竞价，如果我们的广告竞胜了，可以调用我们sdk提供的竞胜的方法，如果失败，就可以调用我们的竞败方法

目录