SDK 接入准备和初始化说明

大约 9 分钟

SDK 接入准备和初始化说明

说明

本文档旨在帮助 Android 应用开发者在程序中快速集成 Mobit SDK。开发者仅需执行基础配置，即可轻松展示个性化广告内容。为了掌握SDK的具体使用方法，请仔细阅读以下文档。

接入前准备

接入Mobit SDK前，请联系Mobit 运营，在Mobit平台添加应用、广告位、广告网络等信息，获取请求广告所需的应用 ID 和广告位 ID。
下载 SDK 并集成到应用内。集成完毕后，首先需要先初始化SDK，并填写平台创建的AppID（应用ID）。然后根据您的需求接入不同的广告功能，按照规范调用各个广告类型方法。
每一次广告加载时都需要填写sposId（广告位ID）。
Mobit SDK Demoopen in new window

当前已接入的广告平台、adapter库和依赖库如下

广告平台	adapter	依赖关系
SAAdSDK核心库	SAAdSDK
优推	SAYouTuiAdAdapter	'YouTuiAdSDK'，'2.15.0'
穿山甲（新版融合Gromore）	SANewCSJAdAdapter	'Ads-CN['BUAdSDK', 'CSJMediation'], '7.0.0.9'
优量汇	SAGDTAdAdapter	'GDTMobSDK', '4.15.50'
快手	SAKSAdAdapter	'KSAdSDK', '4.6.30.1'
百度联盟	SABaiduAdAdapter	'BaiduMobAdSDK', '5.400'
Mintegral	SAMintegralAdAdapter	'MintegralAdSDK', ''
Sigmob	SASigmobAdAdapter	'SigmobAd-iOS', ''
Funlink	SAFunlinkAdAdapter	'', ''
美数	SAMSAdAdapter	'MSMobAdSDK/MS','2.7.3.1'
泛为	SAPtgAdAdapter	'PTGAdFramework', '2.2.80'

SDK接入

远程pod库集成（推荐）

首先在podfile中添加

source 'https://github.com/CocoaPods/Specs.git'
source 'https://e.coding.net/gameley/lemon/Lemon-iOS-Specs.git'

如果要引入包含新版穿山甲的所有广告平台，在podfile中添加

# 包含新版穿山甲的所有广告平台
pod 'SAAdSDK/All-NewCSJ'

如果要引入某几家广告平台，比如优量汇、快手、百度3家，在podfile中添加

pod 'SAAdSDK/SAGDTAdAdapter'
pod 'SAAdSDK/SAKSAdAdapter'
pod 'SAAdSDK/SABaiduAdAdapter'

然后执行pod install即可。

手动集成

1.下载SAAdSDK文件。

SDK 下载地址：开发者可以从下载中心open in new window获取

2.在工程文件->general->Frameworks, Libraries, and Embedded Content-> 点击+ 添加：

SAAdSDK.xcframework
YTNativeEvolutionAd.xcframework

根据需要添加adn，如：

穿山甲、优量汇

SANewCSJAdAdapter.xcframework
SAGDTAdAdapter.xcframework

3.添加第三方依赖库。

GDTMobSDK
Ads-CN/BUAdSDK
Ads-CN/CSJMediation

按上一节所列表格对应关系添加framework、bundle文件和第三方依赖库

SDK初始化

在Appdelegate的application: didFinishLaunchingWithOptions方法中：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    SAAdSDKConfig *conf = [[SAAdSDKConfig alloc] init];
    conf.appId = 申请的应用ID（必填）;
    
    // 开始初始化
    [[SAAdSDK shared] setupWithConf: conf completion: ^(NSError *error) {
        if (error) {
            // 初始化失败
        } else {
            // 初始化成功
        }
    }];

    return YES;
}

说明：可能由于网络等原因，导致SDK在初始化过程中出现异常，导致初始化流程失败，但我们依然会在后面的过程中继续尝试使SDK可用。

SAAdSDK 方法说明

方法	说明
+VERSION	获取Mobit SDK版本号
-setupWithConf: completion	初始化Mobit SDK
-checkSDKInitStatusWithListener:	检测Mobit SDK初始化状态
-checkSDKInitStatus
-

SAAdSDKConfig 属性说明

属性	说明	是否必填
NSString *appId	应用ID	必填
BOOL debug	是否开启控制台日志打印，默认NO，开启后会在控制台输出SDK初始化、瀑布流广告加载流程等日志信息。开发者上线需要将其设置为NO。	可选
BOOL location	是否开启定位, default YES，当app获取到定位授权后，sdk会读取定位信息；设置为NO后，sdk不会再获取定位信息	可选
BOOL IDFA	是否收集idfa，default YES，当app获取到idfa授权后，sdk会读取idfa信息；设置为NO后，sdk不会再获取idfa信息	可选
BOOL keyEvent	是否上报关键行为，默认为NO	可选
NSArray<NSString > presetStrategies	预置策略信息，用于解决首次安装初始化时，拉去线上策略超时的问题。	可选
NSString *presetCsjStrategyPath	穿山甲-gromore平台预置策略，用于解决首次安装初始化时穿山甲-gromore SDK初始化速度过慢的问题。	可选
SAPreCacheConfig *preCacheConfig	初始化预缓存配置信息	可选
NSString *customIdfa	自定义idfa，开发者可以自行获取idfa传入，传入非空的字符串后，SDK将不会再获取idfa	可选
BOOL enablePersonalizedRecommendation	是否允许个性化广告推送功能，默认为YES	可选
BOOL enableShake	是否允许摇一摇广告，默认允许	可选

一、关于摇一摇广告开启和关闭的说明：

在SDK初始化时，设置config.

Mobit 预置策略和穿山甲预置策略

//如果使用预置策略
NSMutableArray *presetStrategies = [NSMutableArray array];

NSArray *jsonNames = @[@"file-name"];
for (NSString *jsonName in jsonNames) {
    NSString *path = [[NSBundle mainBundle] pathForResource:jsonName ofType:@"json"];
    NSString *strategy = [NSString stringWithContentsOfFile:path encoding:NSUTF8StringEncoding error:nil];
    if (strategy) {
        [presetStrategies addObject:strategy];
    }
}

conf.presetStrategies = presetStrategies;

// 如果要传入穿山甲Gromore平台的预置策略
conf.presetCsjStrategyPath = [[NSBundle mainBundle] pathForResource:@"file-name" ofType:@"json"];

初始化预缓存设置和方法说明

初始化预缓存会在SDK初始化完毕后，自动加载开启了初始化预缓存的瀑布流，并将加载成功后的广告缓存到内存中。目的是为了提高一些场景广告的加载速度。

方法	说明
- setRewardMuted:(BOOL)muted withSlotId:(NSString *)slotId;
- setRewardUserId:(NSString )userId withSlotId:(NSString )slotId;
- setRewardExtra:(NSString )extra withSlotId:(NSString )slotId;
- setInterstitialMuted:(BOOL)muted withSlotId:(NSString *)slotId;
- setFeedMuted:(BOOL)muted withSlotId:(NSString *)slotId;
- setFeedAdSize:(CGSize)size withSlotId:(NSString *)slotId;
- setFeedAdSizeToFit:(BOOL)sizeToFit withSlotId:(NSString *)slotId;

代码示例

// 如果在管理平台开启了初始化预缓存功能，需要设置预缓存配置
SAPreCacheConfig *preCacheConfig = [[SAPreCacheConfig alloc] init];
[preCacheConfig setRewardMuted:BOOL withSlotId:@"id"];
[preCacheConfig setInterstitialMuted:BOOL withSlotId:@"id"];
[preCacheConfig setFeedMuted:BOOL withSlotId:@"id"];
[preCacheConfig setFeedAdSize:CGSizeMake(width, height) withSlotId:@"id"];
[preCacheConfig setFeedAdSizeToFit:BOOL withSlotId:@"id"];

conf.preCacheConfig = preCacheConfig;

检测SDK初始化状态方法

当冷启动时初始化逻辑和首次加载广告的逻辑代码不方便写到一起时，sdk提供如下方法

if ([SAAdSDK.shared checkSDKInitStatus]) {
    // 初始化成功
    // 调用广告加载逻辑
} else {
    [SAAdSDK.shared checkSDKInitStatusWithListener:^(NSError * _Nullable error) {
        if (error) {
            // 初始化失败
        } else {
            // 初始化成功
            // 调用广告加载逻辑
        }
    }];
}

获取填充广告源信息

在广告加载成功后，可调用- (nullable SAAdSourceInfo *)getFillAdSourceInfo;方法获取SAAdSourceInfo对象，对象包含信息如下

typedef NS_ENUM(NSUInteger, SAAdSourceAdnType) {
    SAAdSourceAdnTypeUnknown,
    SAAdSourceAdnTypeKuaiShou,
    SAAdSourceAdnTypeYouLiangHui,
    SAAdSourceAdnTypeChuanShanJia,
    SAAdSourceAdnTypeGromore,
    SAAdSourceAdnTypeBaidu,
    SAAdSourceAdnTypeSigmob,
    SAAdSourceAdnTypeYouTui,
    SAAdSourceAdnTypeMintegral,
    SAAdSourceAdnTypeOther,
};

@interface SAAdSourceInfo : NSObject
/// 广告网络名称
@property (nonatomic, copy, readonly, nullable) NSString *platform;
/// 广告网络枚举
@property (nonatomic, assign, readonly) SAAdSourceAdnType platformType;
/// 代码位
@property (nonatomic, copy, readonly, nullable) NSString *code;
@end

获取瀑布流代码位失败信息

在广告加载成功和失败的回调中，可调用- (nullable NSArray<SAAdErrorInfo *> *)getAdErrorInfoList;方法获取SAAdErrorInfo对象数组，对象包含信息如下：

@interface SAAdErrorInfo : NSObject
/// 广告网络平台名称
@property (nonatomic, copy, readonly, nullable) NSString *platform;
/// 广告网络平台广告位
@property (nonatomic, copy, readonly, nullable) NSString *code;
/// 代码位错误信息
@property (nonatomic, strong, readonly, nullable) NSError *error;

@end

获取设备信息-IDFA

如果SAAdSDKConfig *conf; conf.IDFA = YES;，则要获取App Tracking Transparency权限，需要在Info.plist中增加字段NSUserTrackingUsageDescription和自定义文案描述：

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

请求用户权限：

#import <AppTrackingTransparency/AppTrackingTransparency.h>
if (@available(iOS 14.0, *)) {
    // 在-application:didFinishLaunchingWithOptions:方法
    // 或-sceneDidBecomeActive:方法中
    // 需要延时调用，否则不弹窗
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
        [self requestIDFA];
    });
}
- (void)requestIDFA API_AVAILABLE(ios(14.0)) {
    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
        // 获取权限类型
    }];
}

SKAdNetwork

是苹果提供的广告归因方案，穿山甲、优量汇、MTG有提供支持，如果需要，可以在Info.plist中增加字段SKAdNetworkItems和SKAN数组：

<key>SKAdNetworkItems</key>
<array>
  <dict>
    //穿山甲
    <key>SKAdNetworkIdentifier</key>
    <string>238da6jt44.skadnetwork</string>
  </dict>
  <dict>
    //MTG
    <key>SKAdNetworkIdentifier</key>
    <string>kbd757ywx3.skadnetwork</string>
  </dict>
  <dict>
    //优量汇
    <key>SKAdNetworkIdentifier</key>
    <string>f7s53z58qe.skadnetwork</string>
  </dict>
</array>