SDK 接口说明
JAdService 类,联盟广告的功能接口类。
JAdConfig 类,联盟 SDK 启动配置模型。
SDK 初始化
Method - setupWithConfig
接口说明
初始化接口,建议在 application:didFinishLaunchingWithOptions 中调用。
接口定义
+(void)setupWithConfig:(JAdConfig *)config
参数说明
- config:JAdConfig 类。
调用示例
// 引入所需头文件
#import "JAdService.h"
// 如果需要使用 idfa 功能所需要引入的头文件(可选)
#import <AdSupport/AdSupport.h>
#import <AppTrackingTransparency/AppTrackingTransparency.h>
@interface AppDelegate ()
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
// Optional
// 获取 IDFA
// 如需使用 IDFA 功能请添加此代码并在初始化方法的 advertisingIdentifier 参数中填写对应值
NSString *advertisingId;
if (@available(iOS 14, *)) {
[ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
if (status == ATTrackingManagerAuthorizationStatusAuthorized) {
advertisingId = [[ASIdentifierManager sharedManager] advertisingIdentifier].UUIDString;
}
}];
} else {
// 使用原方式访问 IDFA
advertisingId = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
}
// 初始化
JAdConfig *config = [[JAdConfig alloc] init];
config.appKey = @"AppKey copied from JiGuang Portal application";
config.channel = @"App Store";
config.advertisingId = advertisingId;
[JAdService setupWithConfig:config];
[JAdService setInMessageDelegate:self];
return YES;
}
日志等级设置
Method - setDebugMode:
接口说明
API 用于开启 Debug 模式,显示更多的日志信息
接口定义
+ (void)setDebug:(BOOL)enable;
调用示例
[JAdService setDebug:YES];
设置代理
Method - setInMessageDelegate
接口说明
设置inapp的代理回调
接口定义
+ (void)setInMessageDelegate:(id<JAdInMessageDelegate>)inMessageDelegate;
参数说明
JAdInMessageDelegate:遵守JAdInMessageDelegate的代理对象
调用示例
@interface AppDelegate ()<JAdInMessageDelegate>
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
// 初始化
JAdConfig *config = [[JAdConfig alloc] init];
config.appKey = @"AppKey copied from JiGuang Portal application";
config.channel = @"App Store";
config.advertisingId = advertisingId;
[JAdService setupWithConfig:config];
// 设置代理回调
[JAdService setInMessageDelegate:self];
return YES;
}
#pragma mark - JAdInMessageDelegate
/**
*应用内消息已消失
*/
- (void)jAdInMessageAlreadyDisappear {
NSLog(@"应用内消息已消失");
}
/**
inMessage展示的回调
*/
- (void)jAdInMessageAlreadyPopInMessageType:(JAdInMessageContentType)messageType Content:(NSDictionary *)content {
NSLog(@"应用内消息已展示");
}
/**
inMessage点击的回调
*/
- (void)jAdInMessagedidClickInMessageType:(JAdInMessageContentType)messageType Content:(NSDictionary *)content {
NSLog(@"应用内消息被点击");
}
广告拉取
Method - pullInMessageWithAdPosition:completion:
接口说明
用户通过广告位拉取广告
支持的版本
开始支持的版本:5.0.0
接口定义
+ (void)pullInMessageWithAdPosition:(NSString *)adPosition completion:(JAdInMssageCompletion)completion;
参数说明
adPosition:广告位
JAdInMssageCompletion:拉取结果的回调,回调返回的 iResCode为查询结果状态码。
调用示例
[JAdService pullInMessageWithAdPosition:@"您的广告位" completion:^(NSInteger iResCode) {
NSLog(@"%ld",iResCode);
}];
Method - pullInMessageWithParams:completion:
接口说明
用户有条件拉取in app广告
支持的版本
开始支持的版本:5.0.0
接口定义
+ (void)pullInMessageWithParams:(NSDictionary *)params completion:(JAdInMssageCompletion)completion;
参数说明
params:拉取条件 可传参数: @"adPosition" -> 广告位 NSString, @"event" -> 事件 NSString
JAdInMssageCompletion:拉取结果的回调。
调用示例:
// 通过广告位拉取广告
[JAdService pullInMessageWithParams:@{@"adPosition":@"adp1"} completion:^(NSInteger iResCode) {
NSLog(@"%ld",iResCode);
}];
// 通过指定事件拉取广告
[JAdService pullInMessageWithParams:@{@"event":@"event1"} completion:^(NSInteger iResCode) {
NSLog(@"%ld",iResCode);
}];
JAdInMssageCompletion 的定义为:
typedef void (^JAdInMssageCompletion)(NSInteger iResCode);
Method - triggerInMessageByEvent
接口说明
通过事件触发in app下发,针对开通了“极光下发”方式的用户调用。
支持的版本
开始支持的版本:5.0.0
接口定义
+ (void)triggerInMessageByEvent:(NSString *)event;
参数说明
event:事件
调用示例:
[JAdService triggerInMessageByEvent:@"事件名"];
设置应用内消息的父控件
Method - setInMessageSuperView
接口说明
通过该接口设置用户希望in app 广告展示的父控件,建议设置成当前展示的window。如果没有额外设置,SDK会默认取当前APP顶层的Window。
支持的版本
开始支持的版本:5.0.0
接口定义
+ (void)setInMessageSuperView:(UIView *)view;
参数说明
view:建议设置成当前展示的window,SDK默认取当前APP顶层的Window。
调用示例:
UIWindow *window = [UIApplication sharedApplication].keyWindow;//这里设置成您想要广告展示的父控件
[JAdService setInMessageSuperView:window];
动态控制横幅广告展示页面接口
Method - currentViewControllerName
接口说明
在页面切换的时候调用,告诉sdk当前切换到的页面名称。
通过定向页面触发应用内消息下发的功能、页面跳转到黑名单页面隐藏正在曝光中的inapp的功能、inapp页面延迟展示功能都依赖于该接口调用。
请在页面切换的时候调用此方法。确保在所有页面的viewDidAppear中调用此方法。不然可能会造成inapp部分功能不完善。建议在viewController的基类中调用,或者使用method swizzling方法交换viewController的viewDidAppear方法。
支持的版本
开始支持的版本:5.0.0
接口定义
+ (void)currentViewControllerName:(NSString *)className;
参数说明
className:当前页面的类名,传空的话SDK会自动去获取最顶层vc的类名。
调用示例:
[JAdService currentViewControllerName:@"classname"];
说明: 1.由于SDK没有做hook操作,并不知道app是否进行了页面跳转。该接口是为了告诉SDK页面进行了切换,并告诉SDK当前切换到的页面。
2.由于inapp的黑名单部分功能、通过定向页面触发应用内消息下发、inapp页面延迟展示 等功能都依赖于此接口。所以请确保在所有页面的viewDidAppear中调用此方法。不然可能会造成inapp部分功能不完善。建议在viewController的基类中调用,或者使用method swizzling方法交换viewController的viewDidAppear方法。
3.不调用该接口会造成黑名单功能部分问题:当用户在非黑名单页面曝光了inapp时,如果用户切换到了黑名单页面,仍在曝光的inapp无法隐藏。
自渲染相关接口
说明
为满足媒体实现自定义样式渲染的需求,SDK新增自渲染广告拉取,并对创意物料进行自渲染和回调。
使用
请先调用setupWithOption:appKey:channel:apsForProduction:advertisingIdentifier:进行初始化后再调用相关自渲染接口。
使用JAdNativeAdManager对象调用loadAdData方法请求广告。通过设置JAdNativeAdManagerDelegate代理获取广告素材,设置JAdNativeAdDelegate代理获取广告渲染视图的展示和点击回调。
广告素材类 (JAdNativeAd)
广告的数据信息。包括广告的标题、描述、图片信息。
开发者拿到广告素材后,就可以自建视图渲染广告样式。 当渲染视图加载到屏幕上并且显示在屏幕上时调用registerContainer:withClickableViews:rootViewController:注册绑定广告视图和可点击的view,并传入rootViewController作为广告跳转的根视图,跳转方式为present,为必传。
registerContainer:withClickableViews要在广告渲染视图展示在屏幕上之后调用,一定要正确调用,不然会影响广告计费。
渲染视图的点击行为由SDK控制。(包括 打开h5页面,deeplink跳转,appstore下载事件)
提供JAdNativeAdDelegate代理获取广告渲染视图的展示和点击回调。
广告位类 (JAdSlot)
广告位的描述信息。在使用JAdNativeAdManager对象拉取广告时作为必传参数。
该对象必传字段:广告位名称adCode、广告位样式JAdType。
现支持三种广告位样式:横幅JAdTypeBanner、模态JAdTypeModal、悬浮JAdTypeFloat。
广告拉取类(JAdNativeAdManager)
创建该类对象,进行广告素材的拉取。初始化函数请传入JAdSlot对象。
可以设置的参数:超时时间timeout(默认为3秒)。
用该类对象调用loadAdData方法拉取广告。
提供JAdNativeAdManagerDelegate代理获取拉取结果。提供成功和失败两种回调。成功返回JAdNativeAd对象数组。失败返回NSError错误对象。
示例
// 1.创建广告代码位
JAdSlot *adSlot = [[JAdSlot alloc] init];
adSlot.adCode = @"广告代码位名称";
adSlot.adType = JAdTypeModal;
// 2.创建自渲染拉取对象拉取广告
JAdNativeAdManager *manager = [[JAdNativeAdManager alloc] initWithSlot:adSlot];
manager.timeout = 3; // 超时时间,单位为秒
manager.delegate = self; // <JAdNativeAdManagerDelegate>
manager.adCount = 1; // 请求广告物料数量(目前仅支持一条)
[manager loadAdData]; // 请求广告
#pragma mark - JAdNativeAdManagerDelegate
/// 请求广告成功
- (void)nativeAdsManagerSuccessToLoad:(JAdNativeAdManager *)adsManager nativeAds:(NSArray<JAdNativeAd *> *_Nullable)nativeAdDataArray {
if (nativeAdDataArray.count == 0) { return; }
// 3. 拿到物料后,客户进行自渲染。 目前仅支持返回一条物料
JAdNativeAd *ad = nativeAdDataArray[0];
// 3.1设置物料的代理
ad.delegate = self; //<JAdNativeAdDelegate>
// 3.2客户自定义视图。根据返回的物料渲染view
RegisterAdView *registerAdView = [RegisterAdView new];
registerAdView.frame = CGRectMake(0, 0, [UIScreen mainScreen].bounds.size.width, 100);
registerAdView.title = ad.adTitle; // 标题
registerAdView.content = adDescription; // 描述
JAdImage *image = ad.imageList[0]; // 图片信息
NSString *imageURL = image.imageURL;
// UIImage *image = [UIImage imageWithData:[NSData dataWithContentsOfURL:imageUrl]];
// registerAdView.imageView.image = image;
[self.view addSubview:registerAdView]; // 加载到屏幕上
// 3.3. 在广告渲染视图展示后调用此方法,将渲染的视图注册给SDK。请正确调用此方法,不然会影响广告计费。
[ad registerContainer:registerAdView withClickableViews:nil rootViewController:self];
}
/// 请求广告失败
- (void)nativeAdsManager:(JAdNativeAdManager *)adsManager didFailWithError:(NSError *_Nullable)error {
if (self.nativeAdManager != adsManager) {
return;
}
NSLog(@"%@----%@",adsManager,error);
}
#pragma mark - JAdNativeAdDelegate
/// 自渲染广告视图可见
- (void)nativeAdDidBecomeVisible:(JAdNativeAd *)nativeAd {
NSLog(@"广告展示了");
}
/// 点击自渲染广告视图
- (void)nativeAdDidClick:(JAdNativeAd *)nativeAd withView:(UIView *_Nullable)view {
NSLog(@"广告点击了");
}
信息流广告相关接口
说明
开始支持的版本:5.0.3
支持图文样式,开发者直接调用相关接口获取已经渲染好的广告view进行展示。
使用
请先调用setupWithOption:appKey:channel:apsForProduction:advertisingIdentifier:进行初始化后再调用信息流广告相关接口。
使用JAdNativeExpressAdManager对象调用loadAdData方法请求广告。 通过设置JAdNativeExpressAdManagerDelegate代理获取广告view和广告view的展示、点击、关闭等回调。使用JAdNativeExpressAdView对象进行广告的渲染render。
创建广告位,请求广告
广告拉取类(JAdNativeAdManager)
- 创建该类对象,进行广告素材的拉取。初始化函数请传入JAdSlot对象和adSize广告尺寸。
- JAdSlot对象的adType请选择JAdTypeFeed。当前模板渲染仅支持信息流广告。
- adSize建议宽度设置为屏幕宽度,高度设置为0。不要随意设置尺寸大小否则可能出现拉取失败或者广告显示不正常的情况。
- 其他可以设置的参数:超时时间timeout(默认为3秒)。
- 用该类对象调用loadAdData方法拉取广告。
- 提供JAdNativeAdManagerDelegate代理获取拉取结果。提供成功和失败两种回调。成功返回JAdNativeExpressAdView对象数组。失败返回NSError错误对象。
JAdSlot *adSlot = [[JAdSlot alloc] init];
adSlot.adCode = @"您的信息流广告的广告位名称";
adSlot.adType = JAdTypeFeed; // 当前只支持信息流广告
CGSize size = CGSizeMake(self.widthSlider.value, self.heightSlider.value);
JAdNativeExpressAdManager *manager = [[JAdNativeExpressAdManager alloc] initWithSlot:adSlot adSize:size];
manager.timeout = 3;
manager.delegate = self; // <JAdNativeAdManagerDelegate>
manager.adCount = 1;
self.manager = manager;
[manager loadAdData];
广告加载回调
/// 接收广告加载结果
/// 拉取模板广告成功
- (void)nativeExpressAdSuccessToLoad:(JAdNativeExpressAdManager *)nativeExpressAd views:(NSArray<__kindof JAdNativeExpressAdView *> *)views;
/// 拉取模板广告失败
- (void)nativeExpressAdFailToLoad:(JAdNativeExpressAdManager *)nativeExpressAd error:(NSError *)error;
/// 广告视图渲染成功
- (void)nativeExpressAdViewRenderSuccess:(JAdNativeExpressAdView *)nativeExpressAdView;
/// 广告视图渲染失败
- (void)nativeExpressAdViewRenderFail:(JAdNativeExpressAdView *)nativeExpressAdView error:(NSError *_Nullable)error;
/// 广告视图曝光回调
- (void)nativeExpressAdViewWillShow:(JAdNativeExpressAdView *)nativeExpressAdView;
/// 广告视图点击回调
- (void)nativeExpressAdViewDidClick:(JAdNativeExpressAdView *)nativeExpressAdView;
/// 广告视图被关闭
- (void)nativeExpressAdViewDidClosed:(JAdNativeExpressAdView *)nativeExpressAdView;
广告渲染
在nativeExpressAdSuccessToLoad回调后会拿到JAdNativeExpressAdView类型的广告视图。
官方Demo使用tableView进行的广告的展示,在cell上进行广告视图的添加。更新数据源就可以更新广告的展示。如果不是用tableView进行广告展示,记得要调用addSubview方法添加广告视图进行广告展示。注意先调用addSubview方法添加广告视图,再调用广告视图的render方法进行渲染,不然会影响广告的曝光和计费。
/// 拉取模板广告成功
- (void)nativeExpressAdSuccessToLoad:(JAdNativeExpressAdManager *)nativeExpressAd views:(NSArray<__kindof JAdNativeExpressAdView *> *)views {
NSLog(@"%@",NSStringFromSelector(_cmd));
[self.expressAdViews removeAllObjects];//【重要】不能保存太多view,需要在合适的时机手动释放不用的,否则内存会过大
if (views.count) {
[self.expressAdViews addObjectsFromArray:views];
[views enumerateObjectsUsingBlock:^(id _Nonnull obj, NSUInteger idx, BOOL * _Nonnull stop) {
JAdNativeExpressAdView *expressView = (JAdNativeExpressAdView *)obj;
expressView.rootViewController = self;
[expressView render]; // 广告视图进行渲染
}];
}
[self.tableView reloadData]; // 在cell里面将广告视图加在cell上。
}
code码
code码 | 说明 | 解决方案 |
---|---|---|
21002 | 参数错误。请输入正确的广告位和请求样式 | 请输入正确的广告位和请求样式 |
21003 | 调用广告加载api超过10s/30次限制 | 请求过于频繁,请稍后再试 |
21004 | 调用广告加载api超过后台下发间隔 | 请求过于频繁,请稍后再试 |
21005 | 没有网络 | 请检查网络状况 |
21006 | 请求超时 | 请检查网络状况 |
21009 | 解析失败 | 内部数据错误,尝试重新拉取 |
21011 | inapp业务未开通 | 请联系运营开通相关业务 |
21012 | 未登录 | 请检查appkey,bundleid等配置,检查是否调用了初始化函数 |
0 | 有广告 | 正常拉取到广告 |
8001 | 无可用广告 | 多拉几次,若依旧没填充,登录联盟后台确认广告位是否设置了过于严格的过滤规则 |
8002 | 超频 | 不要过于频繁请求接口,过段时间重试 |
8003 | 无匹配样式 | 广告样式已通过广告位进行控制,请求时无需指定样式 |
8004 | 内部错误 | 基本不会发生,如出现请重试 |
8005 | 拉取模式不匹配 | 广告位只支持极光主动下发或者开发者拉取这两种模式二选一,需确认广告下发方式与广告位配置的下发方式是否一致 |
8006 | 业务未开通或者加载运营配置异常 | 请确认appkey和代码位的业务状态为开启 |
8007 | 运营无可用广告位 | 请找运营开通对应广告位 |
8008 | 广告位曝光频控内部错误 | 基本不会发生,如出现请重试 |
8009 | 广告位曝光间隔频控 | 请求过于频繁,请稍后再试 |
8010 | 广告位曝光次数频控 | 该用户已达到当日曝光上限 |
8011 | uid下发频控内部错误 | 请找运营核对频控配置。 |
8012 | uid下发间隔频控 | 请求过于频繁,请稍后再试 |
8013 | uid下发次数频控 | 该用户下发次数已达上限,请更换设备或明天再试 |
8014 | 请求超时 | 请检查网络状况 |
8015 | extra请求参数不合法 | 请求参数不合法,请查看集成文档 |
8100 | 正在请求 | 正在请求广告,请稍后再试 |
8101 | 超出API频率 | 不要过于频繁请求接口,请稍后再试 |
8102 | 请求超时 | 请检查网络状况 |
8103 | 没有获取到黑白名单设置 或者是当前正处在黑名单页面,不允许拉取广告 | 重启应用再尝试拉取,如果仍报该错误,请联系运营确认黑名单页面配置 |
8104 | inapp业务未开通 | 请联系运营开通相关业务 |
8105 | 请求参数错误 | 检查请求参数 |
8106 | 没有网络 | 检查网络状况 |
8107 | 广告数据格式校验错误 | 请稍后重新拉取 |
8108 | 未登录 | 请检查appkey,bundleid等配置,检查是否调用了初始化函数 |