MW Logo

iOS魔窗位SDK集成文档



一、集成准备

1.1 获取魔窗AppKey

登录魔窗后台管理(http://mgnt.magicwindow.cn/),按照步骤提示注册应用,并新建多个魔窗位,可获得AppKey和魔窗位Key。

1.2 导入SDK

导入SDK有以下两种方法,第一种使用Cocoapods安装SDK,第二种直接下载SDK并集成,选择其中一种即可。

注意: SDK中包含了微信分享SDK,如果您的工程里面也同样包含了微信分享SDK,请将重复的删除,保留最新版的微信分享SDK即可,不会影响SDK的正常使用。

1.2.1 使用Cocoapods安装SDK

使用Cocoapods可以方便的统一管理第三方库:https://cocoapods.org

安装Cocoapods,并在项目根目录下创建Podfile文件,在Podfile文件中添加如下内容:

pod 'MagicWindowSDK'
//如果使用bitcode,使用pod 'MagicWindowSDKBitcode'

在terminal下运行命令如下:

pod install

1.2.2 下载SDK并集成

(1) 下载SDK并集成

下载并解压最新版本SDK压缩包,解压后如下图:

将下载的SDK文件解压,拖动里面的mwSDK文件夹到工程中,如下图:

拖到工程中后,弹出以下对话框,勾选"Copy items into destination group's folder(if needed)",并点击“Finish“按钮, 如图:

注意:请务必在上述步骤中选择“Create groups for any added folders”单选按钮组。如果你选择“Create folder references for any added folders”,一个蓝色的文件夹引用将被添加到项目并且将无法找到它的资源。

(2) 添加依赖库

如果使用了Cocoapods集成的SDK,可以忽略此步骤

AdSupport.framework

CoreTelephony.framework

CoreGraphics.framework

CoreFoundation.framework

SystemConfiguration.framework

CoreLocation.framework

CFNetwork.framework

Security.framework

WebKit.framework

ImageIO.framework

libz.tbd

libsqlite3.0.tbd

libc++.tbd

(3) 设置Other Linker Flags

如果使用的是最新版本的微信分享SDK,需要在你的工程文件中选择Build Setting,在"Other Linker Flags"中加入"-Objc -all_load",详情见微信官方文档:

https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&id=open1419319164&token=&lang=zh_CN

1.3 初始化SDK

在AppDelegate中,增加头文件的引用:

#import "MWApi.h"

在 - (BOOL)application: didFinishLaunchingWithOptions:方法中调用registerApp方法来初始化SDK,如下代码所示:

注意:必须设置rootViewController,否则会导致无法弹出活动界面。如果您创建应用时使用storyBoard可以省略此步骤,系统会自动设置rootViewController。

二、魔窗位的设置

2.1 添加魔窗位

魔窗位(动态位置管理)是魔窗的核心功能,所有的活动和mLink都需要基于魔窗位展开。魔窗位可以是View,也可以是ImageView,可以放在App的任意位置,也有用户把魔窗位叫做“任意门”.

魔窗位Key是魔窗位的唯一标识,在魔窗后台设置,如图:

注意:
a. 当返回failure参数MWCampaignConfig为空时,代表该活动已过期或者该活动不存在,请开发者自行处理相应的活动窗体(比如隐藏掉,或者显示别的内容)。
b. 开发者确保显示魔窗位视图后,调用trackImpressionWithKey这个API通知SDK魔窗位视图已成功展示

发送参数:

  key : 魔窗位key

  Targetview : 展示魔窗位上投放活动的view

  TargetController : 展示魔窗位上投放活动的UIViewController

接收参数

  MWCampaignConfig对象,里面所有的数据和该活动对应,请在魔窗后台设置

  success : callback 当成功获取到该魔窗位上活动的时候会调用这个回调

  failure : callback 当获取到该魔窗位上活动失败的时候会调用这个回调

  tap : callback 当点击该魔窗位上活动的时候会调用这个回调,return YES 允许跳转,NO 不允许跳转

  mLinkHandler : callback 当活动类型为mlink的时候,点击的该活动的时候,会调用这个回调,return mlink需要的相关参数

  mLinkLandingPageHandler callback 当活动类型为mlink landing page的时候,点击的该活动的时候,会调用这个回调,return mlink landing page需要的相关参数

示例:

2.2 魔窗位视图的曝光统计

为魔窗位上广告和活动提供单独的曝光接口用于统计

注意:确定视图显示在window上之后再调用trackImpressionWithKey,不要太早调用,在tableview或scrollview中使用时尤其要注意。

2.3 信息流广告

(1) 导入头文件,设置代理

#import "MWAdNative.h"
#import "MWAdNativeView.h"
#import "MWAdNativeAdObject.h"
@interface ViewController : UIViewController<MWAdNativeDelegate>
@property (nonatomic, strong) MWAdNative *native;

(2) 请求广告,设置魔窗位key,用MWAdNative请求广告

- (void)loadAd
{
    if (self.native == nil)
    {
        self.native = [[MWAdNative alloc] initWithMWKey:@"魔窗位key" delegate:self];
    }
    //请求原生广告
    [self.native loadNativeAds];
}

(3) nativeAdsSuccessLoad回调函数表明请求广告成功

(NSArray *)nativeAds参数表示成功返回的广告数组。

MWAdNativeAdObject.h中可获取的属性见下表,可以通过以下属性返回广告字段。

//魔窗位key
@property (copy, nonatomic) NSString *mwKey;
//广告顺序
@property (assign, nonatomic) NSInteger adIndex;
//标题 text
@property (copy, nonatomic)  NSString *title;
//描述 text
@property (copy, nonatomic)  NSString *text;
//小图 url
@property (copy, nonatomic) NSString *iconImageURLString;
//大图 url
@property (copy, nonatomic) NSString *mainImageURLString;
//多图信息流的image url array
@property (strong, nonatomic) NSArray *morepics;
//品牌名称,若广告返回中无品牌名称则为空
@property (copy, nonatomic)  NSString *brandName;
//对返回的广告单元,需先判断MWADMaterialType再决定使用何种渲染组件
@property MWADMaterialType materialType;

(4) 创建信息流广告视图

魔窗SDK中提供了信息流广告视图样式,可以直接使用,也可以自定义信息流广告视图样式。

a. 使用魔窗的信息流广告视图样式

MWAdNativeView *adview = [[MWAdNativeView alloc] initAdViewWithFrame:CGRectMake(0, 0, CGRectGetWidth(self.view.frame), 0) Object:adObject];

MWAdNativeView的高度会自适应,可以通过adview.frame.size.height来获取实际的MWAdNativeView的视图高度

b. 自定义信息流广告视图

UILabel *brandLabel = [[UILabel alloc] initWithFrame:CGRectMake(85, 15, 212, 20)];
brandLabel.font = [UIFont fontWithName:brandLabel.font.familyName size:15];
UILabel *titleLabel = [[UILabel alloc] initWithFrame:CGRectMake(0, 10, 200, 10)];
titleLabel.textColor = [UIColor blueColor];
titleLabel.font = [UIFont fontWithName:titleLabel.font.familyName size:12];
UIImageView *iconImageView = [[UIImageView alloc] initWithFrame:CGRectMake(20, 5, 60, 60)];
UIImageView *mainImageView = [[UIImageView alloc] initWithFrame:CGRectMake(50, 80, 250, 250)];
UILabel *adLogoLabel = [[UILabel alloc] initWithFrame:CGRectMake(286, 318, 24, 12)];
UIImageView *imgview1 = [[UIImageView alloc] initWithFrame:CGRectMake(20, 80, 100, 100)];
UIImageView *imgview2 = [[UIImageView alloc] initWithFrame:CGRectMake(140, 80, 100, 100)];
UIImageView *imgview3 = [[UIImageView alloc] initWithFrame:CGRectMake(260, 80, 100, 100)];
MWAdNativeView *nativeAdView = [[MWAdNativeView alloc] initWithFrame:CGRectMake(0, 0, CGRectGetWidth(self.view.frame), 200) brandName:brandLabel title:titleLabel icon:iconImageView mainImage:mainImageView moreImages:@[imgview1,imgview2,imgview3]];
nativeAdView.adLogoLabel = adLogoLabel;
[nativeAdView addSubview:adLogoLabel];
nativeAdView.backgroundColor = [UIColor whiteColor];

(5) loadAndDisplayNativeAdWithObject: completion:加载和显示广告视图。

开发者确保显示视图后,调用trackImpression通知SDK广告视图已成功展示

- (void)nativeAdsSuccessLoad:(NSArray *)nativeAds
{
 [nativeAds enumerateObjectsUsingBlock:^(id  _Nonnull obj, NSUInteger idx, BOOL * _Nonnull stop) {
//取得每一条广告object
    MWAdNativeAdObject *object = obj;
//创建每一条的广告view
    MWAdNativeView *adview = [self newAdViewWithFrame:CGRectMake(0, 0, CGRectGetWidth(self.view.frame), 300) Object:object];
    [self.adviewArr addObject:adview];
    [adview loadAndDisplayNativeAdWithObject:object completion:^(NSString *error) {
        if (error == nil)
        {
            [self.tableView reloadData];
      //确定视图显示在window上之后再调用trackImpression,不要太早调用
      //如果是在tableView上,可以在tableViewCell展现时调用trackImpression
            [adview trackImpression];
        }
    }];
}];
}

(6) nativeAdsFailLoad:表明请求广告失败

- (void)nativeAdsFailLoad:(MWADFailReason) reason
{
NSLog(@"nativeAdsFailLoad,reason = %d",reason);
}

(7) nativeAdClicked:是广告点击函数

//广告被点击,打开后续详情页面
- (void)nativeAdClicked:(MWAdNativeView*)nativeAdView
{
    NSLog(@"nativeAdView clicked");
}

(8) didDismissLandingPage:是广告详情页被关闭

-(void)didDismissLandingPage:(MWAdNativeView *)nativeAdView
{
    NSLog(@"didDismissLandingPage");
}

2.4 魔窗位分享

SDK为投放到魔窗位上的活动提供分享功能,与App的分享功能可以并存。

2.4.1 微信分享

(1) 在微信开放平台申请并取得应用的AppID

登录微信开放平台(http://open.weixin.qq.com)注册应用并取得应用的AppID。

(2) 在魔窗管理后台配置应用的微信分享ID

如图:

(3) 在App中配置微信分享AppID

在URL Types中添加微信AppID。操作步骤如图所示:

在iOS9中,需要在info.plist中将微信的URL scheme列为白名单,否则影响分享功能的使用,配置如下所示:

2.5 判读魔窗位上是否有内容

(1) 判断单个魔窗位上是否有内容

发送参数:魔窗位key

返回参数:bool yes:该魔窗位上有内容;no:该魔窗位上没有内容

+(BOOL)isActiveOfmwKey:(NSString *)mwkey;

(2) 批量判断魔窗位上是否有内容

发送参数:魔窗位keys

返回参数:有内容的魔窗位keys

+(NSArray *)mwkeysWithActiveCampign:(NSArray *)mwKeys;

三、高级设置

3.1 魔窗位相关通知

3.1.1 魔窗位上内容更新通知

当内容有更新的时候(包括新增内容,关闭内容,更新内容信息等),SDK会发送MWUpdateCampaignNotification通知,当监听到这个通知的时候,开发者需要更新魔窗位上投放的活动展示信息。

目前SDK不会实时的发送MWUpdateCampaignNotification通知,发送通知机制如下:

(1) 启动App

(2) App退到后台超过5分钟,再次在前台打开App

NotificationName: MWUpdateCampaignNotification

3.1.2 内容页面打开关闭通知

当用户点击魔窗位的时候,会打开活动详情页面,即webview。

判断是否发送webview的相关通知

发送参数:enable,YES:打开,NO:关闭,默认为NO
返回参数:无
当状态为YES的时候,将收到以下两个通知

(1) 内容详情页面即将打开通知

NotificationName: MWWebViewWillAppearNotification

(2) 内容详情页面关闭通知

NotificationName: MWWebViewDidDisappearNotification

3.2 自定义魔窗位详情页导航条

是否自定义导航条,当为NO的时候,将使用魔窗自带的样式

发送参数:enable,YES:打开,NO:关闭,默认为NO
返回参数:无
当状态为YES的时候,可以自定义导航条,详情见MWApiObject.h文件

3.2.1 按钮样式自定义

示例:

3.2.2 标题样式自定义


四、基础指标统计

4.1 页面统计

统计某个页面的访问情况:

标记一次页面访问的开始

参数:name 页面名

标记一次页面访问的结束

参数:name 页面名

(注意:pageviewStartWithName和pageviewEndWithName要成对匹配使用才能正常统计页面情况)

4.2 计数统计

统计指定行为被触发的次数

(注意:eventId需要先在魔窗后台管理上注册,才能参与正常的数据统计)

4.3 设置用户信息

配置用户的基本信息

登录的时候,设置用户信息

退出登录的时候,取消当前的用户信息

(注意:设置MWUserProfile的时候,用户唯一标识mwUserId不能为空)

五、使用多渠道分析

如果你要对APP不同的发布渠道进行统计,不需要在魔窗后台创建多个APP,只需要设置不同的渠道即可。如果您只有App Store一个分发渠道,则不再需要做设定,我们会默认标记为App Store。

例如您在91助手发布,需要统计91渠道:

(注意:channelId需要先在魔窗后台管理上注册,才能参与正常的数据统计)

六、注意事项

6.1 如何防止app因获取IDFA被App Store拒绝

如果您的app使用魔窗SDK而未集成任何广告服务,但需要跟踪广告带来的激活行为,请按照下图填写App Store中的IDFA选项(勾选2,3,4):

(1)Serve advertisements within the app

服务app中的广告。如果你的app中集成了广告,你需要勾选这一项。

(2)Attribute this app installation to a previously served advertisement

跟踪广告带来的安装。

(3)Attribute an action taken within this app to a previously served advertisement

跟踪广告带来的用户的后续行为。

(4)Limit Ad Tracking setting in iOS

这一项下的内容其实就是对你的app使用idfa的目的做下确认,只要你选择了采集idfa,那么这一项都是需要勾选的。

6.2 支持ATS

苹果:2017 年1月1日后所有iOS应用必须启用ATS。

SDK已启用ATS。


七、FAQ

FAQ:https://github.com/magicwindow/mw-sdk-faq