MW Logo

iOS SDK接入文档下载

SDK 下载      常见问题(FAQ)      论坛

请选择需要集成的功能模块

mLink
魔窗位
完整集成


一、快速集成

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

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是魔窗位的唯一标识,在魔窗后台设置,如图:

注意:当返回failure参数MWCampaignConfig为空时,代表该活动已过期或者该活动不存在,请开发者自行处理相应的活动窗体(比如隐藏掉,或者显示别的内容)。

(1)在app中添加魔窗位-简单版

发送参数:

  key : 魔窗位key

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

接收参数

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

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

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

示例:

魔窗需要在根视图控制器上弹出webView,如果view所在视图控制器是由present模态方式弹出的,需要调用以下方式绑定活动

(2)在app中添加魔窗位-升级版

发送参数:

  key : 魔窗位key

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

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

接收参数

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

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

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

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

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

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

示例:

(3)在app中添加魔窗位-支持A跳B,B返回A(魔窗位即A)

发送参数:

  key : 魔窗位key

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

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

接收参数

  callBackMLinkKey : mLink key ,当从B返回回来的时候,会根据mLink key来跳转到相应的页面

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

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

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

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

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

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

  MLinkCallBackParamas : callback 从B返回过来的时候,需要的相关参数

示例:

(4)使用自己的webView 展示魔窗位里面的内容

当在success callback 中拿到MWCampaignConfig 对象之中,在tap callback 中实现相关逻辑即可,可以是用webview 展示魔窗位中的内容,也可以登录等操作。

注意:
a. 只有魔窗位上投放的活动可以用webView 打开,才会在MWCampaignConfig对象中获取到activityUrl, 否则为nil。
b. 当使用自己的WebView打开活动的时候,需要修改UserAgent(新UserAgent=原UserAgent + SDK的UserAgent),用作数据监测和统计,其中SDK的UserAgent调用API来获取

示例:

2.2 魔窗位视图的曝光统计

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

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

2.3 魔窗位分享

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

2.2.1 微信分享

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

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

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

如图:

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

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

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

(4) 接收微信分享回调

用于接收微信分享回调。

2.4 通过API给活动传手机号

部分活动在玩的时候是需要用户填写手机号的,如果app本身有登录,已经知道了用户的手机号,这时只需要通过API把手机号传给SDK即可,无需用户在参加活动的时候再次填写手机号。

具体API及调用方式详见3.3设置用户信息

2.5 活动的区域定向

在魔窗后台配置的活动支持区域定向,默认使用IP定位,调用以下API也支持手动定位。

目前活动区域定向仅支持至地级市。

发送参数:

code:城市编码,请参照国家标准行政区划代码:http://files2.mca.gov.cn/www/201510/20151027164514222.htm

2.6 自动打开活动

调用此API,可以不需要用户点击魔窗位,而直接打开活动。

发送参数:
key 活动窗体的唯一标识,请在魔窗后台设置
targetView:显示该活动的view,该view的大小位置请自行设置

注意:在调用autoOpenWebViewWithKey这个API之前, 请先使用同一个魔窗位Key添加相应的魔窗位(如何添加魔窗位,详情见2.1),确保可以获取到相应的活动信息,否则不会生效。

2.7 活动相关通知

2.7.1 活动更新通知

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

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

(1) 启动App

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

NotificationName:MWUpdateCampaignNotification

2.7.2 活动页面打开关闭通知

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

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

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

(1) 活动详情页面即将打开通知

NotificationName:MWWebViewWillAppearNotification

(2) 活动详情页面关闭通知

NotificationName:MWWebViewDidDisappearNotification

2.8 判读魔窗位上是否有活动

(1)判断单个魔窗位上是否有活动

发送参数:魔窗位key

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

(2)批量判断魔窗位上是否有活动

发送参数:魔窗位keys

返回参数:有活动的魔窗位keys

2.9 自定义活动详情页导航条

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

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

2.9.1 按钮样式自定义

示例:

2.9.2 标题样式自定义



mLink,可以将App中具体的内容页面作为一个服务(比如滴滴的打车服务),以链接的形式分享出来,通过这个链接,可以从外部唤起App并自动进入App中的指定服务页。

3.1 mLink基础配置

3.1.1 配置App的URL Scheme

iOS系统中App之间是相互隔离的,通过URL Scheme,App之间可以相互调用,并且可以传递参数。

选中Target-Info-URL Types,配置URL Scheme(比如: magicWindow)

在Safari中输入URL Scheme :// (比如: magicWinodw://) 如果可以唤起App,说明该URL Scheme 配置成功。

3.1.2 配置Universal link

Universal link是iOS9的一个新特性,通过Universal link, App可以无需打开Safari,直接从微信中跳转到App,真正的实现一键直达。如果使用URL Scheme的话,需要先打开Safari,用户体验变得很差,如果App未安装,还会出现错误对话框:

所以,我们强烈推荐配置Universal link,而通过魔窗来配置Universal link也变得非常的简便。

(1) 配置developer.apple.com的相关信息

登录 https://developer.apple.com,选择Certificate, Identifiers & Profiles,选择相应的AppID,开启Associated Domains

注意:当AppID重新编辑过之后,需要更新相应的provisioning Profiles。

(2) 在后台填写相关App的mLink配置信息

team ID可以从你的苹果开发账号页面获取,如图:

(3) 配置Xcode

在Xcode中选择相应的target,点击Capabilities tab,开启Associated Domains,在里面添加魔窗的域名(applinks:xxxx),域名的值在后台获取,请注意每次新注册的App分配的魔窗域名可能不一样。如图:

3.2 配置相关代码

3.2.1 接收URL

(1) 在AppDelegate中的openURL方法中调用,用来处理URL Scheme

示例如下:

注意:当需要在openURL这个方法中处理第三方回调的时候(比如支付宝回调,微信回调等),请注意区分,比如

(2) 在AppDelegate中的continueUserActivity方法中调用,用来处理Universal link

示例如下:

3.2.2 根据mLink key进行一键唤醒

当App接收到URL的时候,会根据mLink key进行匹配,当匹配成功,开发者可以在handler中根据params参数进行一键唤醒。

mLink key :mLink key是mLink服务的唯一标识,在魔窗后台设置,如图:

在AppDelegate中的didFinishLaunchingWithOptions方法中调用

示例如下:

3.2.3 获得最近一次的mLink短链接的渠道来源

3.2.4 A跳B,B返回A

示例如下:

3.3 返回浮层

支持两个App间互相跳转,用户可通过”返回浮层”随时从跳转方App返回来源方App

3.3.1 初始化返回浮层

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

#import " MWFloatView.h"

初始化

3.3.2 设置返回浮层滑动区域

3.3.3 展示返回浮层

3.3.4 设置返回应用A时所需参数

3.3.5 返回浮层的debug模式

3.3.6 示例



四、基础指标统计

4.1 页面统计

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

标记一次页面访问的开始

参数:name 页面名

标记一次页面访问的结束

参数:name 页面名

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

4.2 计数统计

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

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

4.3 设置用户信息

配置用户的基本信息

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

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

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


五、使用多渠道分析

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

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

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


六、注意事项

6.1系统定位

注:自iOS8起,系统定位功能进行了升级,开发者在使用定位功能之前,需要在info.plist里添加(以下二选一,两个都添加默认使用NSLocationWhenInUseUsageDescription):

NSLocationWhenInUseUsageDescription ,允许在前台使用时获取GPS的描述

NSLocationAlwaysUsageDescription ,允许永久使用GPS的描述

6.2 如何防止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.3 支持ATS

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

SDK已启用ATS。

6.4 如何验证SDK已经对接成功

如何验证SDK已经对接成功,请参看http://www.magicwindow.cn/doc/mlink-integration-validation.html



七、FAQ

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