ZhiziyunMobileAds

Zhiziyun mobile advertising iOS SDK.


License
MIT
Install
pod try ZhiziyunMobileAds

Documentation

智子云移动广告 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 支持开屏广告