智子云移动广告 iOS SDK 接入文档
Version: 1.0.0
概述
说明
本文档旨在帮助 iOS 应用开发者在程序中快速植入智子云移动广告平台提供的广告。作为应用开发者,您只需要进行简单配置,就可以在您的应用中显示定制的广告。关于 SDK 的具体使用方法,请仔细阅读下面的文档。
背景
开发环境
确保您的开发及部署环境符合以下标准:
-
开发工具:Xcode 10 及以上版本
-
部署目标:iOS 10.0 及以上版本
-
SDK 版本:iOS SDK 最新版本
术语介绍
-
adid:广告位 ID,是智子云移动广告平台为您的应用所创建的某种类型(横幅、开屏、全屏/插屏、视频贴片、移动暂停、信息流)的广告位置的 ID。
-
adtype:广告位类型,是智子云移动广告平台为您的应用所创建的某种广告位类型(横幅、开屏、全屏/插屏、视频贴片、移动暂停、信息流)。
支持广告类型
支持以下几种广告类型,您可以根据开发需要选择合适的广告:
广告类型 | 简介 | 适用场景 | 版本备注 |
---|---|---|---|
开屏广告 | 开屏广告以 APP 启动作为曝光时机,提供5s的可感知广告展示 | APP 启动时,常会使用开屏广告 | 推荐接入开屏 1.0.0 接口 |
SDK 项目部署
说明
使用广告 SDK,您的 iOS 应用可以借助智子云移动广告 SDK 完成广告创收。本章介绍了两种在 iOS 应用中集成广告 SDK 的方法。
自动部署
自动部署可以省去您工程配置的时间。iOS SDK 会通过 CocoaPods 进行发布,推荐您使用自动部署。
- 安装 CocoaPods
CocoaPods 是一个 Swift 和 Objective-C 项目的依赖管理器。它拥有超过 49,000 个第三方库,超过 3,000,000 个 APP 都在使用 CocoaPods 做依赖管理,CocoaPods 可以帮助你优雅的扩展你的项目。 如果您未安装过 CocoaPods,可以通过以下命令行进行安装。更多详情请访问 CocoaPods 官网。
$ sudo gem install cocoapods
- 配置 Podfile 文件
在您的工程文件所在文件夹下有一个名为 Podfile 的文件。如果您第一次使用 CocoaPods,可以在通过以下命令初始化一个 Podfile 文件:
$ pod init
打开 Podfile 文件,应该是如下内容(具体内容可能会有一些出入):
# platform :ios, '10.0'
target 'ZhiziyunMobileAdsSample' do
# use_frameworks!
# Pods for ZhiziyunMobileAdsSample
end
修改 Podfile 文件,将 pod 'ZhiziyunMobileAds'
添加到 Podfile 中,如下所示:
# platform :ios, '10.0'
target 'ZhiziyunMobileAdsSample' do
# use_frameworks!
pod 'ZhiziyunMobileAds', '~> 1.0.0' # 输入你想要的版本号
# Pods for ZhiziyunMobileAdsSample
end
- 使用 CocoaPods 进行 SDK 部署
通过 CocoaPods 安装 SDK 前,确保 CocoaPods 索引已经更新。可以通过运行以下命令来更新索引:
$ pod repo update
运行命令进行安装:
$ pod install
也可以将上述两条命令合成为如下命令:
$ pod install --repo-update
命令执行成功后,会生成 .xcworkspace
文件,可以打开 .xcworkspace
来启动工程。
- 升级 SDK
升级 SDK 时,首先要更新 repo 库,执行命令:
$ pod repo update
之后重新执行如下命令进行安装即可升级至最新版 SDK
$ pod install
注意 :只有在 Podfile 文件中没有指定 SDK 版本时,运行上述命令才会自动升级到最新版本。不然需要修改 Podfile 文件,手动指定 SDK 版本为最新版本。
- 指定 SDK 版本
指定 SDK 版本前,请先确保 repo 库为最新版本,参考上一小节内容进行更新。如果需要指定 SDK 版本,需要在 Podfile 文件中,pod 那一行指定版本号:
pod 'ZhiziyunMobileAds', '~> 1.0.0' #这里改成你想要的版本号
之后运行命令:
$ pod install
手动部署
下面会指导您手动将 iOS SDK 进行集成。如果您没有项目,请先创建一个空白项目。
添加依赖库
-
将 .framework 文件 copy 到工程文件夹中,然后在项目中选中项目文件,选择 Add Files to “your project name”。
-
在 Xcode 中选中工程名,在 Target->Build Phases->Link Binary With Libraries 中点击 “+”,在弹出窗口输入库名称,出现后点击 “Add” 则将库引入到工程中。
位置权限
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
Privacy - Location Usage Description
Objective-C 接入准备
- 新建桥接头文件(bridge.h,推荐放在工程目录下)。这里我们命名为:ZhiziyunMobileAdsSample-Bridging-Header.h。在这个文件中 import 我们需要的所有头文件,代码如下:
#import "ZhiziyunMobileAds-Swift.h"
#import "ZhiziyunMobileAds.h"
- 左侧目录中选中工程名,在 TARGETS->Build Settings-> Swift Compiler - Code Generation -> Objective-C Bridging Header 中输入桥接文件的路径。
其他配置
苹果公司在 iOS 9 中升级了应用网络通信安全策略,默认推荐开发者使用 HTTPS 协议来进行网络通信,并限制 HTTP 协议的请求。为了避免出现无法拉取到广告的情况,我们推荐开发者在 Info.plist 文件中增加如下配置来实现广告的网络访问(信任 HTTP 请求)。
在工程的 Info.plist 文件中,设置 App Transport Security Settings 选项下 Allow Arbitrary Loads 值为 YES,对应 plist 内容为:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
若有获取 SDK 版本的需求,也可直接调用接口:
- Objective-C
Double versionNumber = ZhiziyunMobileAds.ZhiziyunMobileAdsVersionNumber;
- Swift
let versionNumber = ZhiziyunMobileAds.ZhiziyunMobileAdsVersionNumber
开屏广告
简介
基本信息
开屏广告以 APP 启动作为曝光时机,提供 5s 的可感知广告展示。用户可以点击广告跳转到目标页面;或者点击右上角的 “跳过” 按钮,跳转到 APP 内容首页。
权限等级:开放
适用场景:开屏广告会在您的应用开启时加载,拥有固定展示时间(一般为 5 秒),展示完毕后自动关闭并进入您的应用主界面。
分类:开屏广告分为半屏和全屏,其中半屏开屏广告支持开发者自定义设置开屏底部的界面,用以展示应用 Logo 等。
主要 API
事件函数列表
函数名 | 函数名 |
---|---|
loadLaunchAd(adid: String, adtype: Int) | 初始化开屏广告 - Parameters: - adid: 广告位 ID - adtype: 广告位类型 |
回调函数列表
回调函数名 | 回调函数含义 |
---|---|
xhLaunchAd(_ launchAd: XHLaunchAd, customSkip customSkipView: UIView, duration: Int) | 倒计时回调 |
xhLaunchAd(_ launchAd: XHLaunchAd, clickAndOpenModel openModel: Any, click clickPoint: CGPoint) | 广告点击事件回调 |
xhLaunchAd(_ launchAd: XHLaunchAd, imageDownLoadFinish image: UIImage, imageData: Data) | 图片本地读取/或下载完成回调 |
xhLaunchAd(_ launchAd: XHLaunchAd, imageDownLoadFinish image: UIImage, imageData: Data) | 图片本地读取/或下载完成回调 |
xhLaunchAdShowFinish(_ launchAd: XHLaunchAd) | 广告显示完成回调 |
接入代码示例
加载并显示开屏广告
- 在 AppDelegate.swift 文件中导入头文件
import ZhiziyunMobileAds
- 在 didFinishLaunchingWithOptions 函数中初始化根控制器
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// Override point for customization after application launch.
initRootViewController()
setupLaunchAd()
return true
}
}
// MARK: - 初始化根控制器
extension AppDelegate {
/// 初始化根控制器
private func initRootViewController() {
let rootViewController = ViewController.init()
window = UIWindow(frame: UIScreen.main.bounds)
window?.backgroundColor = UIColor.white
window?.rootViewController = rootViewController
window?.makeKeyAndVisible()
}
}
- 在 AppDelegate 的实现文件中初始化并加载广告数据,开屏广告目前支持全屏开屏和半屏开屏广告两种形式,其中半屏开屏广告支持开发者自定义设置开屏底部的界面,用以展示应用 Logo 等。
// MARK: - 初始化开屏广告
extension AppDelegate {
private func setupLaunchAd() {
// 获取 SDK 版本
let versionNumber = ZhiziyunMobileAds.ZhiziyunMobileAdsVersionNumber
print(versionNumber)
// 初始化开屏广告 - Parameters: - adid: 广告位 ID - adtype: 广告位类型
ZhiLaunchAdManager.sharedInstance.loadLaunchAd(adid: "1136", adtype: 202)
}
}
开屏广告拉取超时时间
您可以设置拉取广告的超时时间,默认为 3 秒。通常情况,开发者调用 loadAd 后会展示 backgroundColor,如果在该时间内广告拉取成功,则显示开屏广告;否则放弃本次广告展示。
// 设置等待数据源时间(建议值:3)
ZhiLaunchAdManager.sharedInstance.waitDataDuration = 2
开屏广告启动页类型
您可以设置广告的启动页类型,默认为 LaunchImage。通常情况,设置您工程的启动页使用 LaunchImage 还是 LaunchScreen.storyboard,不设置默认: LaunchImage。
// MARK: - XHLaunchAd配置
// 设置你工程的启动页使用的是: LaunchImage 还是 LaunchScreen.storyboard (不设置默认: LaunchImage)
ZhiLaunchAdManager.sharedInstance.sourceType = .launchScreen
广告请求请求对象
您可以在拉取广告前设置广告的请求对象,例如协议版本号、是否允许广告追踪、广告位宽度、广告位高度、APP 在应用市场的下载地址、User Agent 信息、IP 地址、设备类型、运营商、网络连接方式、设备当前所在经度、设备当前所在纬度等
// MARK: - 广告请求请求对象
// 协议版本号 固定值:20180615
ZhiLaunchAdManager.sharedInstance.version = 20180615
// 是否允许广告追踪 0 – 允许追踪 1 – 不允许追踪 默认为 0
ZhiLaunchAdManager.sharedInstance.dnt = 0
// 广告位宽度
ZhiLaunchAdManager.sharedInstance.width = 1125
// 广告位高度
ZhiLaunchAdManager.sharedInstance.height = 2086
// APP 在应用市场的下载地址 APP 时选填
ZhiLaunchAdManager.sharedInstance.storeurl = "https://apps.apple.com/cn/app/qq/id444934666"
// User Agent 信息
ZhiLaunchAdManager.sharedInstance.ua = "Mozilla/5.0 (iPhone; CPU iPhone OS 12_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148"
// IP 地址
ZhiLaunchAdManager.sharedInstance.ip = "101.81.125.41"
// 设备类型 1 - 移动/平板设备 2 - 个人电脑 3 - 智能 TV 4 - 手机 5 - 平板电脑 6 - 连接设备 7 - 机顶盒
ZhiLaunchAdManager.sharedInstance.devicetype = 4
// 运营商 APP/WAP 时选填,取值: 46000 - 中国移动 46001 - 中国联通 46003 - 中国电信
ZhiLaunchAdManager.sharedInstance.carrier = 46003
// 网络连接方式 0 – 未知 1 - 局域网 2 - WIFI 3 - 蜂窝网络未知 4 - 2G 5 - 3G 6 - 4G
ZhiLaunchAdManager.sharedInstance.connectiontype = 6
// 设备当前所在经度 APP/WAP 时选填
ZhiLaunchAdManager.sharedInstance.lon = 121
// 设备当前所在纬度 APP/WAP 时选填
ZhiLaunchAdManager.sharedInstance.lat = 78
说明:开屏广告只支持竖屏使用。
广告请求
接入方式
-
媒体方根据 SSP API 广告服务接口规范,通过 HTTP(S)协议实时请求广告内容并在媒体 端进行展示。
-
通过 SSP 后台管理 APP 广告位和广告数据。
请求对象
参数 | 类型 | 规则 | 描述 | 备注 |
---|---|---|---|---|
version | int | 必填 | 协议版本号 | 固定值:20180615 |
dnt | int | 必填 | 是否允许广告追踪 | 0 – 允许追踪 1 – 不允许追踪 默认为 0 |
adid | string | 必填 | 广告位 ID | |
adtype | int | 必填 | 广告位类型 | 请查看广告位类型 |
width | int | 必填 | 广告位宽度 | |
height | int | 必填 | 广告位高度 | |
storeurl | string | 选填 | APP 版本 | APP 时选填 |
ua | string | 必填 | User Agent 信息 | |
ip | string | 必填 | IP 地址 | |
devicetype | int | 必填 | 设备类型 | 1 - 移动/平板设备 2 - 个人电脑 3 - 智能 TV 4 - 手机 5 - 平板电脑 6 - 连接设备 7 - 机顶盒 |
carrier | int | 选填 | 运营商 | APP/WAP 时选填,取值: 46000 - 中国移动 46001 - 中国联通 46003 - 中国电信 |
connectiontype | int | 选填 | 网络连接方式 | 0 – 未知 1 - 局域网 2 - WIFI 3 - 蜂窝网络未知 4 - 2G 5 - 3G 6 - 4G |
idfa | string | 选填 | iOS 设备的 IDFA 明文值 | APP/WAP 时选填 |
lat | string | 选填 | 设备当前所在经度 | APP/WAP 时选填 |
lon | string | 选填 | 设备当前所在纬度 | APP/WAP 时选填 |
开屏请求示例
{
"version": 20180615,
"dnt": 0,
"adid": "21",
"adtype": 202,
"width": 1280,
"height": 720,
"appname": " 智子测试 APP-iOS",
"bundle": "com.zhiziyun.ceshi",
"ver": "1.0.0",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0_3 like Mac OS X)
AppleWebKit/604.1.38 (KHTML, like Gecko) Mobile/15A432",
"ip": "36.98.203.175",
"devicetype": 4,
"os": "iOS",
"osv": "11.0",
"carrier": 46000,
"connectiontype": 2,
"make": "Apple",
"model": "iPhone",
"js": 0,
"idfa": "1656F7FD-7AF6-4B6D-A853-CB1334567411",
"dpidmd5": "dbaf94aaca976816395ec802c292670c",
"sw": 640,
"sh": 1136,
"orientation": 0,
"ishttps": 1
}
广告位类型
代码 | 说明 |
---|---|
101 | PC 横幅 |
105 | PC 视频贴片 |
106 | PC 视频暂停 |
107 | PC 信息流 |
201 | 移动横幅 |
202 | 移动开屏 |
203 | 移动全屏/插屏 |
205 | 移动视频贴片 |
206 | 移动移动暂停 |
207 | 移动信息流 |
SDK 相关问题排查
说明
如果根据正常的注册流程仍然无法在嵌入智子云移动广告 iOS SDK 的 APP 中看到广告,可以在各个广告形式的 delegate 失败回调方法中输出错误信息。
智子云移动广告在打印广告关键信息时会带上 [ZhiziyunMobileAds::ZhiziyunMobileAds] 的标记,其他带有 ZhiziyunMobileAds 标记的 log 与广告信息无关。
错误码
errorCode | 描述 |
---|---|
3001 | 网络错误 |
4001 | 初始化错误, 包括广告位为空、广告位类型为空 |
4003 | 广告位错误 |
4006 | 广告未曝光 |
4007 | 设备不支持 |
4008 | 设备方向不支持 |
4009 | 开屏跳过按钮定义非法 |
4010 | 开屏 bottomView 设置非法 |
4011 | 请求广告超时 |
4013 | 系统不支持,原生视频模板广告只支持 iOS 10.0 及以上系统 |
4014 | 广告数据返回前尝试展示广告, 例如激励视频拉到广告后才可以调用展示接口 |
4015 | 广告已经曝光过,不允许二次展示,请重新拉取 |
4016 | 应用横竖方向与广告位支持方向不匹配 |
5001 | 后台数据错误 |
5002 | 视频素材下载错误 |
5003 | 视频素材播放错误 |
5004 | 没匹配的广告,禁止重试,否则影响流量变现效果 |
5005 | 广告请求量或者消耗等超过日限额,请第二天再请求广告 |
5006 | 包名校验非法 |
5009 | 广告请求量或者消耗等超过小时限额,请一小时后再请求广告 |
5010 | 广告样式校验失败,请检查广告位与接口使用是否一致 |
5012 | 广告过期,请重新拉取 |
5013 | 广告拉取过于频繁,请稍后再试 |
6000 | 未知错误,联系智子云移动广告商务同事协助排查 |
附录
法律声明
客户在注册成为用户之后,本文档作为与平台对接的指引文档。智子云拥有修改、调整、增补本文件的权利,并在法律允许范围内对本文档拥有最终解释权。
修订历史
版本 | 日期 | 说明 |
---|---|---|
1.0.0 | 2019-09-27 | 支持开屏广告 |