├── images
├── a.jpg
├── b.jpg
└── c.jpg
├── README.md
├── .gitattributes
├── .gitignore
├── mraid_cn.md
└── mraid_en.md
/images/a.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/graypants/mraid_cn/HEAD/images/a.jpg
--------------------------------------------------------------------------------
/images/b.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/graypants/mraid_cn/HEAD/images/b.jpg
--------------------------------------------------------------------------------
/images/c.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/graypants/mraid_cn/HEAD/images/c.jpg
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # MRAID2.0中文版
2 |
3 | MRAID的全称是Mobile Rich Media Ad Interface Definitions，中文译为移动富媒体广告接口规范，目前最新版本为2.0。
4 |
5 | 原文是[PDF版](http://www.iab.net/mraid)，为了方便阅读，我将其手动转换为Markdown格式并翻译，希望对从事广告行业的技术小伙伴有所帮助。
6 |
7 | ## MRAID广告测试
8 |
9 | **Web Tester**
10 |
11 | MRAID有官方的[在线测试平台](http://webtester.mraid.org/)。
12 |
13 | **Android App**
14 |
15 | Google提供了一个[Android App](https://play.google.com/store/apps/details?id=com.google.ads.showcase&hl=en)用于测试MRAID广告，需要事先在手机上安装翻墙软件或者配置VPN。
16 |
17 | **iOS App**
18 |
19 | 暂未找到用于MRAID广告测试的第三方iOS App。
20 |
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
1 | # Auto detect text files and perform LF normalization
2 | * text=auto
3 |
4 | # Custom for Visual Studio
5 | *.cs diff=csharp
6 | *.sln merge=union
7 | *.csproj merge=union
8 | *.vbproj merge=union
9 | *.fsproj merge=union
10 | *.dbproj merge=union
11 |
12 | # Standard to msysgit
13 | *.doc diff=astextplain
14 | *.DOC diff=astextplain
15 | *.docx diff=astextplain
16 | *.DOCX diff=astextplain
17 | *.dot diff=astextplain
18 | *.DOT diff=astextplain
19 | *.pdf diff=astextplain
20 | *.PDF diff=astextplain
21 | *.rtf diff=astextplain
22 | *.RTF diff=astextplain
23 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | #################
2 | ## Eclipse
3 | #################
4 |
5 | *.pydevproject
6 | .project
7 | .metadata
8 | bin/
9 | tmp/
10 | *.tmp
11 | *.bak
12 | *.swp
13 | *~.nib
14 | local.properties
15 | .classpath
16 | .settings/
17 | .loadpath
18 |
19 | # External tool builders
20 | .externalToolBuilders/
21 |
22 | # Locally stored "Eclipse launch configurations"
23 | *.launch
24 |
25 | # CDT-specific
26 | .cproject
27 |
28 | # PDT-specific
29 | .buildpath
30 |
31 |
32 | #################
33 | ## Visual Studio
34 | #################
35 |
36 | ## Ignore Visual Studio temporary files, build results, and
37 | ## files generated by popular Visual Studio add-ons.
38 |
39 | # User-specific files
40 | *.suo
41 | *.user
42 | *.sln.docstates
43 |
44 | # Build results
45 |
46 | [Dd]ebug/
47 | [Rr]elease/
48 | x64/
49 | build/
50 | [Bb]in/
51 | [Oo]bj/
52 |
53 | # MSTest test Results
54 | [Tt]est[Rr]esult*/
55 | [Bb]uild[Ll]og.*
56 |
57 | *_i.c
58 | *_p.c
59 | *.ilk
60 | *.meta
61 | *.obj
62 | *.pch
63 | *.pdb
64 | *.pgc
65 | *.pgd
66 | *.rsp
67 | *.sbr
68 | *.tlb
69 | *.tli
70 | *.tlh
71 | *.tmp
72 | *.tmp_proj
73 | *.log
74 | *.vspscc
75 | *.vssscc
76 | .builds
77 | *.pidb
78 | *.log
79 | *.scc
80 |
81 | # Visual C++ cache files
82 | ipch/
83 | *.aps
84 | *.ncb
85 | *.opensdf
86 | *.sdf
87 | *.cachefile
88 |
89 | # Visual Studio profiler
90 | *.psess
91 | *.vsp
92 | *.vspx
93 |
94 | # Guidance Automation Toolkit
95 | *.gpState
96 |
97 | # ReSharper is a .NET coding add-in
98 | _ReSharper*/
99 | *.[Rr]e[Ss]harper
100 |
101 | # TeamCity is a build add-in
102 | _TeamCity*
103 |
104 | # DotCover is a Code Coverage Tool
105 | *.dotCover
106 |
107 | # NCrunch
108 | *.ncrunch*
109 | .*crunch*.local.xml
110 |
111 | # Installshield output folder
112 | [Ee]xpress/
113 |
114 | # DocProject is a documentation generator add-in
115 | DocProject/buildhelp/
116 | DocProject/Help/*.HxT
117 | DocProject/Help/*.HxC
118 | DocProject/Help/*.hhc
119 | DocProject/Help/*.hhk
120 | DocProject/Help/*.hhp
121 | DocProject/Help/Html2
122 | DocProject/Help/html
123 |
124 | # Click-Once directory
125 | publish/
126 |
127 | # Publish Web Output
128 | *.Publish.xml
129 | *.pubxml
130 |
131 | # NuGet Packages Directory
132 | ## TODO: If you have NuGet Package Restore enabled, uncomment the next line
133 | #packages/
134 |
135 | # Windows Azure Build Output
136 | csx
137 | *.build.csdef
138 |
139 | # Windows Store app package directory
140 | AppPackages/
141 |
142 | # Others
143 | sql/
144 | *.Cache
145 | ClientBin/
146 | [Ss]tyle[Cc]op.*
147 | ~$*
148 | *~
149 | *.dbmdl
150 | *.[Pp]ublish.xml
151 | *.pfx
152 | *.publishsettings
153 |
154 | # RIA/Silverlight projects
155 | Generated_Code/
156 |
157 | # Backup & report files from converting an old project file to a newer
158 | # Visual Studio version. Backup files are not needed, because we have git ;-)
159 | _UpgradeReport_Files/
160 | Backup*/
161 | UpgradeLog*.XML
162 | UpgradeLog*.htm
163 |
164 | # SQL Server files
165 | App_Data/*.mdf
166 | App_Data/*.ldf
167 |
168 | #############
169 | ## Windows detritus
170 | #############
171 |
172 | # Windows image file caches
173 | Thumbs.db
174 | ehthumbs.db
175 |
176 | # Folder config file
177 | Desktop.ini
178 |
179 | # Recycle Bin used on file shares
180 | $RECYCLE.BIN/
181 |
182 | # Mac crap
183 | .DS_Store
184 |
185 |
186 | #############
187 | ## Python
188 | #############
189 |
190 | *.py[co]
191 |
192 | # Packages
193 | *.egg
194 | *.egg-info
195 | dist/
196 | build/
197 | eggs/
198 | parts/
199 | var/
200 | sdist/
201 | develop-eggs/
202 | .installed.cfg
203 |
204 | # Installer logs
205 | pip-log.txt
206 |
207 | # Unit test / coverage reports
208 | .coverage
209 | .tox
210 |
211 | #Translations
212 | *.mo
213 |
214 | #Mr Developer
215 | .mr.developer.cfg
216 |
--------------------------------------------------------------------------------
/mraid_cn.md:
--------------------------------------------------------------------------------
1 | 互动广告局（简称IAB）
2 |
3 | 移动富媒体广告接口规范（MRAID）2.0版本
4 |
5 | 发布于2012年9月27日
6 |
7 | 最后修订时间2013年4月16日
8 |
9 | # 贡献者
10 | IAB MRAID的工作小组包括来自以下公司的代表：
11 |
12 | 24/7 Real Media, Inc. Medialets
13 | AccuWeather.com MediaMind
14 | AdMarvel Microsoft Advertising
15 | AdMeld Mixpo
16 | ADTECH Mocean Mobile
17 | Adobe Systems Inc. NBC Universal Digital Media
18 | AOL New York Times Co.
19 | CBS Interactive Nexage
20 | Celtra Pandora
21 | Crisp Media PointRoll
22 | Dow Jones & Company Rhythm NewMedia
23 | ESPN Spongecell
24 | FreeWheel Sprout
25 | Goldspot Media TargetSpot
26 | Google Time Inc.
27 | Greystripe Turner Broadcasting System, Inc.
28 | IDG Univision
29 | inMobi The Weather Channel
30 | Innovid Yahoo!, Inc.
31 | Jumptap
32 |
33 |
34 | # 感谢
35 | IAB感谢ORMMA.org API项目贡献者，给本文档提供了一个起点。ORMMA.org是一批行业思想领袖自2010年春季以来一起开发和测试的一组完整灵活的移动富媒体广告API。在IAB推出MRAID项目以前，ORMMA的贡献者包括：
36 |
37 | Adam Schuetz, AdMarvel Philippe Laporte, Goldspot Media
38 | Dennis Doughty, Jumptap Robert Hedin, The Weather Channel
39 | Jon Badenell, The Weather Channel Todd Pasternack, Pointroll
40 | Nathan Carver, Crisp Media Wook Chung, Google
41 | Neal Karasic, Jumptap Xavier Facon, Crisp Media
42 |
43 |
44 | # 关于MRAID
45 | 互动广告局（IAB）的成员和其它重要贡献者联合创建这份文档，对于移动富媒体广告来说，它是一份标准的接口规范。MRAID的目标是解决移动应用、不同广告服务器和不同富媒体平台之间已知的互操作性问题。
46 |
47 | ## IAB联系方式
48 |
49 | IAB移动营销中心高级总监：Joe Laszlo，mobile@iab.net
50 |
51 | # 内容提要
52 | 在过去的几年中，由于在移动应用上的富媒体展示广告已经变得越来越流行，各种创新型企业都公认：为移动广告服务创建一个投放生态系统将成为一项巨大的挑战。对于内容出版商和广告主来说，创新型的移动富媒体广告投放会导致许多令人兴奋的可能性，但是同时这也导致了效率低下，经常延缓和阻碍最佳的商业化内容。
53 |
54 | 简化移动应用广告创意设计者的流程会大大增加代理商将移动纳入其媒体购买清单的意愿。不管是哪个移动设备平台，应用程序或技术用于显示媒体，广告主想要看到让人惊叹的创意，批准它并且决定购买指定的移动媒体库存。
55 |
56 | # 规范
57 | 下列术语用于整个MRAID规范。
58 |
59 | **广告容器：**广告容器是一个显示广告创意的区域。它是一个提供屏幕区域的容器，我们称之为MRAID容器。它基于web视图，用于广告显示。SDK通常都会提供广告容器，但不是必须。应用程序可能包含来自一个SDK的多个广告容器。
60 |
61 | **关闭事件区：**在广告创意中有一块可以轻触的区域叫做关闭事件区，它会引发广告回到默认状态（在缩放式广告中）或者从屏幕中整个移除（在插播式广告中）。
62 |
63 | **关闭指引：**给用户一个视觉提醒，指示他们关闭事件区所在的位置。
64 |
65 | **控制器：**控制器是一段提供给广告设计者访问MRAID方法和事件的JavaScript代码。广告创意使用控制器执行和广告容器之间的交互，也可以间接的和App及设备交互。
66 |
67 | **设备独立像素（DIP）：**通过MRAID API在控制器和创意之间传递的所有长度值都是设备独立像素。
68 |
69 | DIP是从物理屏幕像素中抽象出来的，旨在简化App和内容开发跨不同屏幕分辨率的设备。
70 |
71 | 使用DIP意味着，例如：视网膜显示屏的iPhone和旧款iPhone将返回相同的尺寸，尽管它们之间有着不同的物理像素值。1 DIP大约相当于160分之一英寸（在大约160 DPI设备上的1设备像素）.
72 |
73 | 在iOS中，这些对应到“点”；Android中，对应到“设备独立像素”。
74 |
75 | 注意：只有视口比例为1.0时1 DIP才等于1 CSS像素。为了对应CSS像素和DIP，创意应使用如下公式：
76 |
77 | `css像素 * 视口比例 = DIP`
78 |
79 | **内嵌式广告：**伴随着其它内容一起出现在屏幕上的一种广告，例如网页上或者App内的一个banner。
80 |
81 | **插播式广告：**一种显示在内容上方的全屏广告——也被叫做“障碍物”或者“覆盖物”。这类广告必须驳回用户返回到内容的请求（译者注：也就是不允许用户自行关闭广告）。一些插播式广告可以出现在游戏关卡之间，或者一段视频剪辑的前后，再或者其他动态内容中。（在许多杂志类App中，滑动页面之间的广告在MRAID规范下被认为是内嵌式广告。）
82 |
83 | **物理像素：**设备屏幕的实际像素。例如，视网膜显示屏的iPhone的物理像素为960x640。MRAID API长度值总是使用DIP（上文定义的）来计算，而不是使用物理像素。
84 |
85 | **SDK：**软件开发工具包。集成在出版商App中启用广告容器的可重复使用代码（或类库）。SDK，正如其名，它不是一个可视化组件。
86 |
87 | **Web View：**基于HTML显示广告创意的视图。Web View用来执行渲染使用HTML和JavaScript编写的广告。
88 |
89 | 
90 |
91 | # 支持MRAID的基本须知
92 | 本章详细介绍了App中提供广告服务的SDK（MRAID兼容）的要求。
93 |
94 | 预计实现将分为两部分。第一部分为富媒体广告在App中的显示定义一个本地容器，第二部分为广告创建者定义一个JavaScript控制器交互用。本地容器封装一个支持HTML和JavaScript的Web View，比如iOS中的UIWebView，控制器充当一个桥梁可以将本地功能集成到基于HTML的广告中。具体实现或许有所不同。
95 |
96 | 在规划时，关键的设计考虑因素：
97 |
98 | * 在应用程序发布者和广告卖家允许的情况下，以一致的方式访问设备的本机功能（方向、位置、加速度等。）
99 | * 行业标准的广告开发（HTML和JavaScript）
100 | * 渐进式的复杂度（简单的事情很简单，复杂的事情是可能的，但更难）
101 |
102 | ## 技术受众
103 | 规范文档本质上是技术性的，但这并不妨碍我们创新。这份文档适用于出版商或SDK供应商，并解决广告设计者的需求。
104 | >### 本地App开发者
105 | 在这份规范中对于本地App开发者没有任何要求。为了集成广告到他们的App中，本地App开发者应遵循SDK开发者提供的说明。
106 | >### SDK开发者
107 | SDK搭建者有责任考虑这些提案以外的问题。（参考“超出范围”）如上所述，预计SDK开发者将提供两个接口用于实现这些提案：SDK提供一个用于本地App开发者集成用的容器和一个给广告设计者直接使用的控制器。
108 | >本文档概述了广告设计者所需的控制器要求。作者意图是：对于现有的SDK，本文的概念可以通过一个外部层来管理。
109 | >### 广告设计者
110 | 这份文档对于广告设计者来说，除了使用标准的web，没有创意相关的要求。使用本规范中方法的广告设计者，能够提供给消费者跨平台和出版商的丰富的媒体体验。
111 |
112 | 对于广告设计者来说，意识到调用本机设备的设计必须是异步的，这一点很重要。对于大多数web开发者，这种情况类似于AJAX编程。
113 |
114 | ## 视觉窗口和默认的容器设置
115 | 创意设计者应注意需要了解他们正在运行的程序可能会覆盖默认的web视图设置。他们应通过查询MRAID控制器来了解，就像他们为了解环境而查询一个网页。这些设置包括容器的高、宽、比例以及用户是否可以改变容器比例。
116 |
117 | 虽然MRAID并不在Web视图之上建立任何新参数或控制器，我们也建议创意应当检查和调整参数，因为笔者认为创意或许想有一个不同于默认的容器设置。
118 |
119 | ## 超出范围
120 | 每个MRAID实现提供给开发者唯一的功能集。这份文档为交互操作概述了一个最小的功能集，它并不定义那些可能是SDK中的一部分的功能，例如：
121 |
122 | * 从广告服务器，广告网络或本地资源检索广告
123 | * 报告
124 | * IDE集成
125 | * 安全/隐私
126 | * 国际化
127 | * 错误报告
128 | * 日志
129 | * 结算和付款
130 | * 广告尺寸和广告行为（MRAID不定义广告尺寸或者用户和广告互动过程中，广告如何移动和改变）
131 | * 为缓存或者离线使用下载资源到本地文件系统
132 |
133 | 显而易见，SDK开发者必须为广告单元实现在指定区域渲染Web内容的能力。对于大部分环境来说，这个功能作为一个Web View组件已经可用，虽然开发者可能必须开发额外的功能以支持这些规范。
134 |
135 | 作者的意图是：供应商（SDK提供者）不限于只开发API中概括的功能。他们应当不断创新、不断推出区别于市场上已有功能的新特性。这些其它特性必须在MRAID命名空间之外实现。
136 |
137 | 从跨MRAID兼容的SDK意义上来讲，一个除了MRAID特性只使用SDK特定功能的广告，已没有必要成为一个MRAID广告。
138 |
139 | ## 标准Web技术
140 | 对于交互操作，只有web兼容的语言应被用于标记和脚本语言。本文假定使用HTML/JavaScript/CSS。广告设计者应当能够在浏览器上开发和测试广告单元。如果广告设计者使用的标记、样式、方法只兼容一种浏览器（例如WebKit CSS3），那么这个广告应针对性的用于兼容的设备。
141 |
142 | 当可以统一提供新的web标准时，我们鼓励广告设计者们使用它们。这可能包括像短信和电话这样的草案，以及一些广泛实施，但尚未完成的HTML5规范。设计师需要知道，在这种情况下，预期的协议和实现，可能不是真的跨所有设备和平台交互。
143 |
144 | ## 广告服务器需知
145 | 用于传输富媒体广告的服务器应当支持使用JavaScript的HTML广告。
146 |
147 | ## 广告渲染需知
148 | ### 显示HTML广告——广告容器
149 | MRAID兼容的广告容器必须能显示任何HTML广告。容器应调用HTML与JavaScript渲染引擎渲染广告。在本文中，渲染引擎将被称作“Web View”。Web View需要尽可能的体现设备的浏览器特性。比如，iOS开发者或许会使用UIWebView。一个给定的App视图可以有一个或多个广告视图容器，它们都将相互独立的运行而互不干涉。
150 |
151 | ## 广告设计者需知
152 | ### 控制富媒体广告显示——广告控制器
153 | 希望使用MRAID的广告设计者，在广告加载时，必须尽早的通过调用mrad.js脚本标识出来。调用mraid.js会通知SDK向素材中注入MRAID javascript代码。
154 |
155 | MRAID保持在后台运行，把控制广告显示的权利留给广告设计者，但是当（或者如果）广告需要访问MRAID特性和功能时，MRAID又是可用的以便创意使用MRAID API。不管是广告设计者还是App开发者，创意和富媒体SDK之间的内部交互对他们都是不可见的。
156 |
157 | 一个不利用任何设备特性的广告根本不需要使用MRAID API。然而，如果广告不调用MRAID，它将得到SDK的默认解决方案。广告因为一些原因使用MRAID API的情况：
158 |
159 | * 打开一个嵌入式的Web浏览器
160 | * 检测广告是否可见
161 | * 展开一个广告，比如从banner变成更大尺寸
162 | * 点击广告内触发一个动作
163 |
164 | 我们鼓励广告设计者依靠MRAID来实现上述效果。
165 |
166 | ## 生存周期实例
167 | ### 简单型广告生存周期实例
168 | 非富媒体广告（例如基本的banner）可以选择性地调用MRAID。如果广告没有通过mraid.js脚本标签调用MARID，那么应用程序或者SDK通常会处理此类广告以使它们正常展示。
169 |
170 | 如果广告设计者更想使用MRAID标准容器，而不是SDK默认容器，那么他们可能希望为这种简单的HTML广告调用mraid.js。在这种情况下，广告设计者必须确保对于任何链接都使用`mraid.open()`打开，以保证统一的行为。
171 |
172 | ### MRAID展开式广告生存周期实例
173 | 在富媒体广告生存周期实例中，广告设计者使用JavaScript API和本地层通信，和设备及操作系统的功能交互。
174 | 
175 | 举个例子，当用户点击广告时，广告使用MRAID API请求当前广告可以展开。SDK（虽然它不是MRAID规范的一部分）应通知APP广告即将展开，以便于App停止任何事情，用户此时将不能和App交互。SDK随后调整Web View，占据设备的整个屏幕或者广告完全展开后的大小。展开的广告容器会在右上角保留一片空白，作为MRAID强制性关闭事件区，如果广告指定，允许提供创意内的关闭指引，否则应用默认关闭指引。
176 |
177 | 当用户完成展开式广告后，他们点击关闭按钮使广告回到它们原始大小，显示广告的banner状态，同时通知App它可以继续运行。
178 |
179 | ### MRAID插播式广告生存周期
180 | 插播式广告生存周期和展开式广告生存周期非常类似。无论广告容器在屏幕是否可见，广告都可以使用MRAID API查询它，在采取其它行动之前一直等到广告容器在屏幕上可见。和展开式广告一样，展开的广告容器会在右上角保留一片空白，作为MRAID强制性关闭事件区，如果广告指定，允许提供创意内的关闭指引，否则应用默认关闭指引。当用户完成插播式广告后，他们可以点击关闭按钮，在这种情况下广告的状态将变为hidden，注销所有事件监听，同时通知App继续运行。
181 |
182 | ## MRAID版本
183 | 采用MRAID标准在整个广告社区是一项高优先级的事务，并且对于移动富媒体广告跨平台的成功有着至关重要的作用。出于这个原因，IAB发布具有完整功能集的MRAID版本。这将以统一的方式呈现给SDK供应商们符合标准的MRAID API，防止仅实现一部分标准可能出现的碎片继承。
184 |
185 | 维护完全向后兼容是MRAID项目的一个关键目标。一个MRAID2.0兼容的SDK应能够毫无问题的运行一个MRAID1.0广告，一个MRAID1.0兼容的SDK应能够处理一个MRAID2.0广告中MRAID1.0兼容的特性。
186 |
187 | 在已经确定的两个MRAID版本中，IAB和其MRAID工作组集中在六个关键目标：
188 |
189 | * __高互用性__ —— 开发运行在一个MRAID容器中的广告可以运行在多个平台和操作系统的MRAID容器中。
190 | * __优雅降级__ —— 利用MRAID特性开发的广告也有能力根据需要优雅降级。将来，当获取设备功能访问权变成MRAID标准的一部分时，这一点尤其重要。
191 | * __渐进的复杂性__ —— 广告设计使用的API应该是简单的，只在必要时增加复杂性。
192 | * __广告改变大小和（或者）打开新页面都以统一的方式，最好都在嵌入式浏览器中进行__ —— 关于广告展开和打开App内嵌浏览器（或者内嵌浏览器不存在时，在本地浏览器中），MRAID规定统一的与富媒体SDK之间通信的方式。
193 | * __消费者一致的退出广告体验__ —— MRAID广告始终有统一的退出控制，用户由此可以记住他们退出广告的体验，返回到他们来时的应用程序或内容中。
194 | * __对出版商来说是灵活的__ —— 虽然MRAID兼容的SDK必须支持所有MRAID特性，但是App发布者或广告卖家可以自由的允许或禁止启用MRAID特性的广告。也就是说，MRAID支持富媒体广告特性，但并不规定所有富媒体广告卖家必须支持所有这些功能。
195 |
196 | ### 1.0版本
197 | MRAID1.0中的方法和事件，满足了富媒体广告最低级别的要求，主要用于显示一个在固定容器中可改变大小的HTML广告（例如，把一个广告从banner扩展到更大尺寸或全屏）和插播式广告。
198 |
199 | ### 2.0版本
200 | MRAID2.0继承了MRAID1.0的特性，在展开式广告之上，给广告设计者们更多的控制权，并且提供了一个新的方法`resize()`，它允许在广告创意中出现更微妙更有趣的尺寸变化。
201 |
202 | 另外，MRAID2.0规定了关于查询设备某个功能的标准方式，提出视频创意的统一处理方法，并且解决了目前HTML5没有很好实现的两个本地特性：向设备日历中添加一个条目和在设备相册中存储图片。
203 |
204 | 对于可以使用MRAID2.0 API开发的广告示例，请看附录部分。
205 |
206 | # 接口需求和定义
207 | 这个列表概括了MRAID2.0下广告设计者可以访问的所有方法和事件。MRAID2.0（即不在MRAID1.0中）中新增的方法和事件通过星号标识。
208 |
209 | **方法**
210 |
211 | addEventListener getVersion
212 | createCalendarEvent* isViewable
213 | close open
214 | expand playVideo*
215 | getCurrentPosition* removeEventListener
216 | getDefaultPosition* resize*
217 | getExpandProperties setExpandProperties
218 | getMaxSize* setResizeProperties*
219 | getPlacementType storePicture*
220 | getResizeProperties* supports*
221 | getScreenSize* useCustomClose
222 | getState getOrientationProperties*
223 | setOrientationProperties*
224 |
225 |
226 | **事件**
227 |
228 | error stateChange
229 | ready viewableChange
230 | sizeChange*
231 |
232 |
233 | ## 标识
234 | 广告必须标识它们自己是MRAID兼容的。完成这项工作通过尽早的加入MRAID脚本引用，而且最好在MRAID函数被创意引用之前。换言之，MRAID标识脚本必须被MRAID兼容的容器或SDK最先识别出来。
235 |
236 | **MRAID**脚本引用
237 |
238 | MRAID标签遵循HTML JavaScript语法，以便完整的网页结构和HTML片段都可以被标识为MRAID广告。mraid.js作为一个脚本被引入到文档中，或者使用HTML标签，或者使用JavaScript代码。MRAID示例广告（见[www.iab.net/mraid](http://www.iab.net/mraid)）说明了脚本引用标签应该被放置在什么位置。
239 |
240 | ``
241 |
242 | 虽然MRAID广告需要像这样通过mraid.js脚本尽早的标识它们自己，以便容器可以注入MRAID类库，但是广告设计者也应避免为了其它目的在广告创意中使用“mraid.js”字符串，因为这样做可能会导致容器或者SDK错误的注入多个MRAID类库副本。
243 |
244 | ## 初始化
245 | MRAID管理广告和容器之间的交互，并且标识容器是兼容MRAID规范的。广告设计者必须为MRAID包含JavaScript引用，但是实际的JavaScript类库由容器提供，容器的职责是在脚本引入后确保它们对广告尽早的可用，并且通过触发ready事件来发送准备完成信号。
246 |
247 | 下面分步骤总结了从广告初始化加载到MRAID容器注入API类库的动作。
248 |
249 | 1. 通过尽早的调用MRAID脚本标签``，标识它们自己为MRAID广告。
250 | 2. SDK（或者MRAID兼容）容器
251 |
252 | a. 选择性的检测脚本调用
253 |
254 | b. 始终为MRAID广告提供MRAID JavaScript桥接
255 |
256 | c. 提供一个状态为loading并且具有查询状态能力的受限MRAID对象
257 |
258 | 3. 如果广告使用createElement，需要等mraid.js完成加载
259 | 4. 如果MRAID状态等于loading，那么广告使用`mraid.addEventListener('ready')`监听ready事件
260 | 5. SDK（或容器）完成向Web View中初始化MRAID类库
261 |
262 | a. 改变MRAID状态为为default，同时StateChange事件被触发
263 |
264 | b. 触发MRAID ready事件
265 |
266 | 6. 广告的ready事件监听器被触发，广告JavaScript代码此时可以使用MRAID API
267 |
268 | **ready**事件
269 |
270 | 当容器完全加载、初始化完成并且准备好来自广告创意的任何调用时，ready事件触发。
271 |
272 | 在广告创意被加载之前，MRAID兼容的容器负责准备API方法。这会阻止一种情况：因为API方法不可用导致的广告不能为ready事件注册监听。虽然容器可以立即加载所有MRAID，但在广告加载过程中，容器至少要尽早准备好支持getState和addEventListener，否则将没有办法为广告注册ready事件。在容器可能仍然需要较多的时间初始化设置或者准备额外功能的事件中，只有当容器为任意MRAID请求完全准备好时，ready才应被触发。
273 |
274 | 在执行任何富媒体操作之前，广告应该总是试图等待ready事件。因为一些时间问题，比如要在广告注册监听之前触发ready事件，广告设计者可以配合getState()方法来使用ready事件。
275 |
276 | 例子
277 |
278 | ```
279 | function showMyAd() {
280 | ...
281 | }
282 | if (mraid.getState() === 'loading') {
283 | mraid.addEventListener('ready', showMyAd);
284 | } else {
285 | showMyAd();
286 | }
287 | ```
288 |
289 | “ready”
290 |
291 | 参数：
292 | · none
293 | 侧面影响：
294 | · 使MRAID JavaScript类库对广告单元可用
295 | 返回值：
296 | · none
297 | 触发事件：
298 | · none
299 |
300 |
301 | **getVersion**方法
302 |
303 | getVersion方法允许广告在显示前确认基础功能集。版本号必须符合MRAID规范（例如1.0或者2.0），不是供应商的SDK版本号。
304 |
305 | getVersion() -> String
306 |
307 | 参数：
308 | · none
309 | 返回值
310 | · String – MRAID兼容的SDK版本号或者IAB针对性认证的SDK版本号。举个例子，对于本文的版本号，getVersion()讲返回“2.0”
311 |
312 |
313 | ## 初始显示
314 | 当其它资源在后台加载时，广告设计者最好提供一段简单的HTML，比如一个`![]()
`标签，用于他们广告的初始化显示。在JavaScript使用控制器请求调用额外功能时，这段HTML将显示在容器中。最后，一旦所有的资源准备完成，初始显示用的HTML可能就会完全被富媒体广告替代，这些视创意的需求而定。
315 |
316 | ## 事件处理
317 | 事件处理是MRAID的关键概念。Web层和原生层的通信本质上异步的。通过事件处理，广告设计者能够监听指定的事件，并且可以根据需要响应这些事件。MRAID主张广播式事件，在保证最大一致性的同时，支持最广泛的功能性/灵活性。
318 |
319 | 控制器开放这些方法。
320 |
321 | **addEventListener**方法
322 |
323 | 使用本方法为指定事件订阅一个指定的处理方法。这样，多个监听器就可以订阅一个指定事件，一个监听器可以处理多个事件。在同一时间，一个广告可能注册不止一个监听器，前提是广告必须允许这样做。MRAID2.0支持的事件：
324 |
325 |
326 |
327 | | 事件 |
328 | 描述 |
329 |
330 |
331 | | ready |
332 | 报告初始化完成 |
333 |
334 |
335 | | error |
336 | 报告发生错误 |
337 |
338 |
339 | | stateChange |
340 | 报告状态变化 |
341 |
342 |
343 | | viewableChange |
344 | 报告显示状态变化 |
345 |
346 |
347 | | sizeChange |
348 | 报告广告的尺寸信息变化 |
349 |
350 |
351 |
352 | addEventListener(event, listener)
353 |
354 | 参数：
355 | · event – String 要监听的事件名称
356 | · listener – 执行监听的函数
357 | 返回值：
358 | · none
359 | 侧面影响
360 | · none
361 |
362 |
363 | **removeEventListener**方法
364 |
365 | 使用本方法从指定事件退订处理方法。当事件监听器不再有用时，它们应当被移除以避免出错。如果没有指定监听器方法，那么正在监听事件的所有方法将被移除。
366 |
367 | removeEventListener(event, listener)
368 |
369 | 参数：
370 | · event – Strign 事件名称
371 | · listener – 要被移除的函数
372 | 返回值：
373 | · none
374 | 触发事件：
375 | · none
376 |
377 |
378 | ## 错误处理
379 | 当容器中发生错误，包含事件错误诊断信息的“error”事件会被触发。对于不同类型的错误，可以使用任意多个监听器进行监控，并且根据需要进行响应。
380 |
381 | **error**事件
382 |
383 | 每当容器错误发生时，error事件就被触发。该事件包含错误发生时的描述，以及，在适当的时候，包含导致错误的操作名称（没有关联动作时，动作参数为null）。而JavaScript错误依然由广告设计师全权负责。
384 |
385 | “error” -> function(message, action)
386 |
387 | 参数：
388 | · message: String 错误描述
389 | · action: String 引发错误的动作
390 | 经由什么触发：
391 | · 任何出错
392 |
393 | 广告设计者需要注意：错误可以通过底层SDK/容器以异步或同步的方式来处理。
394 |
395 | MRAID规范没有定义错误事件中的“message”部分，并且主要适用于广告发布前的创意调试，错误的“action”部分始终是广告尝试使用并导致错误的方法名称。原则上讲，任何MRAID方法都可能引发错误，因此广告设计者在使用错误监听器时应监听下列所有可能的错误动作：
396 |
397 | addEventListener getVersion
398 | createCalendarEvent isViewable
399 | close open
400 | expand playVideo
401 | getCurrentPosition removeEventListener
402 | getDefaultPosition resize
403 | getExpandProperties setExpandProperties
404 | getMaxSize setResizeProperties
405 | getPlacementType storePicture
406 | getResizeProperties supports
407 | getScreenSize useCustomClose
408 | getState
409 |
410 | 虽然任何MRAID方法都可能导致错误，在实践中，使用resize、添加一张图片到相册或者添加一个事件到日历，是最易产生错误的MRAID方法。广告设计者们在使用这些方法时，应该格外注意添加错误监听器，来检查在执行resize、storePhoto、createCalendarEvent动作时是否发生错误，以便于广告创意有可能采取应对措施。
411 |
412 | ## 控制广告显示
413 | 除了广告初始化显示，广告设计者或许会有各种理由需要控制广告显示。
414 |
415 | * 为了减少传输时间，App可能会在后台加载广告视图，这样广告虽然在请求，但对用户却并不可见。
416 | * 广告可能扩展到超出应用程序内容的默认大小。
417 | * 一旦用户交互完成，广告可能返回到默认尺寸。
418 |
419 | **getState**方法，**stateChange**事件
420 |
421 | 每个广告容器（或者Web View）都有下列其中之一的状态：
422 |
423 |
424 |
425 | | 状态 |
426 | 描述 |
427 |
428 |
429 | | loading |
430 | 容器还没有准备好和MRAID实现交互 |
431 |
432 |
433 | | default |
434 | 应用程序和SDK设定好广告容器的初始位置和大小 |
435 |
436 |
437 | | expanded |
438 | 广告容器已展开覆盖到应用程序内容的最顶层 |
439 |
440 |
441 | | resized |
442 | 广告容器已通过MRAID2.0 resize()方法改变大小 |
443 |
444 |
445 | | hidden |
446 | 插播式广告转变为关闭后的状态。在被支持的情况下，banner广告转变为关闭后的状态 |
447 |
448 |
449 |
450 | getState方法返回广告容器的当前状态，返回广告容器是否处于其默认状态，是否是固定位置，是否处于展开或缩放状态，是否是更大的位置，或者是否是隐藏的。
451 |
452 | 当状态被广告或者环境以程序方式改变时，会触发stateChange事件。当广告视图在default、expanded、resized、hidden状态之间改变时（这些状态都是在调用expand(), resize(), close()产生的）触发stateChange事件。容器或SDK也可以关闭广告作为用户或系统操作的结果，比如从后台恢复运行。
453 |
454 | 任何MRAID广告在同一时间只能有一个状态。这个规定意味着，在two-part展开式广告中，所有的Web View都只有一种状态。只要是在屏幕上展开的视图，使用getState()都将返回“expanded”。
455 |
456 | 调用expand(), resize(), close()对于状态的影响定义如下表：
457 |
458 | 如何阅读：创意的初始状态在表格最左列；当使用一个MRAID方法时，可以从方法名那列往下查到状态如何变更。举个列子，如果广告的状态是“expanded”并且同时使用了close()方法，那么这个广告的状态变为“default”。
459 |
460 |
461 |
462 | | 初始状态 |
463 | expand() |
464 | resize() |
465 | close() |
466 |
467 |
468 | | loading |
469 | 无影响 |
470 | 无影响 |
471 | 无影响 |
472 |
473 |
474 | | default |
475 | 对于banner广告，状态变为“expanded”，插播式广告则无影响 |
476 | 对于banner广告，状态变为“resized”，插播式广告则无影响 |
477 | 对于banner广告，状态变为“hidden”（如果SDK/容器支持的话），插播式广告状态则变为“hidden” |
478 |
479 |
480 | | expanded |
481 | 无影响（仍然保持“expanded”状态） |
482 | 引发错误；（仍然保持“expanded”状态） |
483 | 状态变为“default” |
484 |
485 |
486 | | resized |
487 | 状态变为“expanded” |
488 | 状态变为“resized”（也就是说，事件监听器将监听到一个新的stateChange事件，尽管事件触发后状态依旧是“resized”） |
489 | 状态变为“default” |
490 |
491 |
492 | | hidden |
493 | 无影响 |
494 | 无影响 |
495 | 无影响 |
496 |
497 |
498 |
499 | 在two-piece展开式广告中，一种新类型广告，展开后的Web View从“loading”状态开始直到MRAID可用，紧接着“ready”事件被触发，然后广告的状态变为“expanded”。two-piece广告中的banner（第一片）同样也将它的状态从“default”变为“expanded”。
500 |
501 | 对于插播式广告，Web View从“loading”到“default”，当广告关闭时，状态变为“hidden”。
502 |
503 | getState() -> String
504 |
505 | 参数：
506 | · none
507 | 返回值：
508 | · String: "loading"或"default"或"expanded”或“resized”或“hidden”
509 | 相关事件：
510 | · stateChange
511 |
512 |
513 | “stateChange” -> function(state)
514 |
515 | 参数：
516 | · state - String, "loading"或"default"或"expanded”或“resized”或“hidden”
517 | 经由触发：
518 | · expand()方法、resize()方法、close()方法或者App
519 |
520 |
521 | **getPlacementType()**方法
522 |
523 | 为了提高效率，广告设计师有时会在banner广告和插播式广告放置点全都使用简单的创意。所以创意应能够知道他们的放置类型，并因此引发不同的行为，每个广告容器都有一个放置类型，来确定广告是嵌入在内容中显示（即banner）还是作为插播覆盖到内容上（比如在App内容传输过程中）。容器返回放置类型的值以便于创意在需要时引发不同的行为。容器并不确定banner是否能展开（这个由创意决定），因此不会专门为展开式广告返回一个放置类型。
524 |
525 |
526 |
527 | | 值 |
528 | 描述 |
529 |
530 |
531 | | inline |
532 | 默认的放置类型是嵌入到内容中显示（即banner） |
533 |
534 |
535 | | interstitial |
536 | 这种广告放置类型是覆盖在内容上面 |
537 |
538 |
539 |
540 | getPlacementType应该总是返回广告最初显示时设定的值。也就是说，在two-part展开式广告中，如果调用getPlacementType，第二部分（展开的部分）应当同样返回“inline”。
541 |
542 | getPlacementType() -> String
543 |
544 | 参数：
545 | · none
546 | 返回值：
547 | · String: "inline", "interstitial"
548 | 相关事件：
549 | · none
550 |
551 |
552 | **isViewable**方法，**viewableChange**事件
553 |
554 | 除了广告容器的状态，有一种情况是广告容器可能作为App缓存区的一部分已经在屏幕之外加载以帮助提供流畅的用户体验。在插播式广告中或者采用滚动视图的App中，这种方式格外流行，比如在游戏关卡之间。
555 |
556 | isViewable方法返回广告容器当前是否在屏幕上。当广告从屏幕上离开时会触发viewableChange事件，反之亦然。对于two-piece展开式广告，当广告状态为expanded时，isViewable将基于可见的expanded piece返回一个值。
557 |
558 | 广告在任何情况下都有可能在屏幕之外加载，最佳实践是：广告检查自身可见状态或者在采取任何行动之前注册viewableChange监听事件。
559 |
560 | 注意：MRAID并不定义在屏幕上构成广告可见性的最小像素或百分比阀值。（IAB内部目前有一个进行中的项目，为App中的广告尺寸建立指导方针，可能会引入可见性阀值）
561 |
562 | isViewable() -> boolean
563 |
564 | 参数：
565 | · none
566 | 返回值：
567 | · boolean -
568 | true：容器在屏幕上并且对用户可见；
569 | false：容器不在屏幕上并且不可见
570 | 相关事件：
571 | · viewableChange
572 |
573 |
574 | “viewableChange” -> function(boolean)
575 |
576 | 参数：
577 | · boolean -
578 | true：容器在屏幕上并且对用户可见；
579 | false：容器不在屏幕上并且不可见
580 | 经由触发：
581 | · 应用程序视图控制器的改变
582 |
583 |
584 | 下面是一个在行动之前同时考虑到“ready”和“isViewable”的广告示例。
585 |
586 | ```
587 | // Wait for the SDK to become ready
588 | if (mraid.getState() === 'loading') {
589 | mraid.addEventListener('ready', onSdkReady);
590 | } else {
591 | onSdkReady();
592 | }
593 |
594 | function onSdkReady() {
595 | // Wait for the ad to become viewable for the first time
596 | if (mraid.isViewable()) {
597 | showMyAd();
598 | } else {
599 | mraid.addEventListener('viewableChange',function(viewable) {
600 | if (viewable) {
601 | mraid.removeEventListener('viewableChange', arguments.callee);
602 | showMyAd();
603 | }
604 | });
605 | }
606 | }
607 |
608 | function showMyAd() {
609 | ...
610 | }
611 | ```
612 |
613 | ## 改变广告尺寸
614 |
615 | MRAID2.0包含三种截然不同的方式，用于广告改变尺寸。目前最简单的方式就是使用open()方法，它适用于那些需要在新浏览器窗口（通常是App内嵌浏览器，但是也有可能是设备原生浏览器）加载、为了点击率的网站。
616 |
617 | expand()方法适用于那些用简单直接的方式覆盖到应用内容上的广告。
618 |
619 | 除了这些，resize()方法适用于那些需要精细缩小或放大的广告，与其所运行的App进行对话。这个方法允许广告设计者完全自由的控制和权衡：创意和App/容器同时需要额外的方法和监听器，以在不同的放置点有恰当的响应。
620 |
621 | ### rezie(), expand(), open()之间的区别
622 |
623 | 虽然这些方法都是相关联的，但他们提倡渐进的复杂性。也就是说，简单的操作应当是简单的，但是复杂的结果仍然可行。理解rezie(), expand(), open()之间的区别有助于广告设计者根据需要选择更好的方法。
624 |
625 | open()
626 |
627 | * 最低通用标准
628 | * 用于广告主的着陆页或迷你站
629 | * 打开一个新的URL，通常是App内嵌浏览器，然而也有可能是设备原生浏览器
630 | * 总是全屏
631 | * 没有附加属性
632 |
633 | expand()
634 |
635 | * 简单的接口
636 | * 生硬的广告体验
637 | * 全屏
638 | * 少量的附加属性
639 | * 支持one-part或two-part创意
640 | * 在固定位置（右上角）有MRAID强制性关闭事件区
641 | * 对于创意相对定位
642 |
643 | rezie()
644 |
645 | * 灵活的接口
646 | * 连续，非模态的广告体验
647 | * 没有默认值，尺寸可变大变小
648 | * 必须的附加属性
649 | * 有MRAID强制性广告关闭区，但是广告设计者可以在创意内改变这个区域的位置
650 | * 可能是绝对定位
651 | * 支持调整大小时指定方向
652 |
653 |
654 | 这个表格总结了这些方法之间的区别。
655 |
656 |
657 |
658 | | 属性 |
659 | open() |
660 | expand() |
661 | resize() |
662 |
663 |
664 | | 模态的 |
665 | Y |
666 | Y |
667 | N |
668 |
669 |
670 | | 强制关闭控制 |
671 | N |
672 | Y |
673 | Y |
674 |
675 |
676 | | 浏览者停留在广告里 |
677 | N |
678 | Y |
679 | Y |
680 |
681 |
682 | | two-part创意 |
683 | n/a |
684 | Y |
685 | N |
686 |
687 |
688 | | one-part创意 |
689 | n/a |
690 | Y |
691 | Y |
692 |
693 |
694 | | 与屏幕对齐 |
695 | n/a |
696 | Y |
697 | N |
698 |
699 |
700 | | 给一些小创意提供背景 |
701 | n/a |
702 | Y |
703 | N |
704 |
705 |
706 | | 向上增大尺寸 |
707 | n/a |
708 | Y |
709 | Y |
710 |
711 |
712 | | 向下减小尺寸 |
713 | n/a |
714 | N |
715 | Y |
716 |
717 |
718 | | 应用程序的最大区域 |
719 | n/a |
720 | N |
721 | Y |
722 |
723 |
724 | | 完成必须回调 |
725 | n/a |
726 | N |
727 | Y |
728 |
729 |
730 | | 支持方向 |
731 | n/a |
732 | N |
733 | Y |
734 |
735 |
736 | | 创意能控制尺寸改变后的广告 |
737 | n/a |
738 | N |
739 | Y |
740 |
741 |
742 | | App能返回默认状态 |
743 | n/a |
744 | N |
745 | Y |
746 |
747 |
748 |
749 | 在MRAID2.0标准中，创建半屏非模态扩展必须使用resize()方法。下列表格反映出expand的“isModal”属性被强烈反对使用。MRAID2.0规范下，非全屏展开式创意中调用expand()必须要求Web View容器是空白的，采用覆盖或者将下层App变模糊来突显广告，也就是说，扩展式广告本质是模态的。从这种意义上来讲，模态半屏式广告在MRAID2.0中是不允许的。
750 |
751 |
752 |
753 | |
754 | 模态 |
755 | 非模态 |
756 |
757 |
758 | | 全屏 |
759 | 使用expand() |
760 | 不可能 |
761 |
762 |
763 | | 半屏 |
764 | 不可能 |
765 | 使用resize() |
766 |
767 |
768 |
769 | ## Open：在浏览器窗口中打开外部移动站点
770 |
771 | 如果广告需要打开一个外部移动站点或者迷你站，对于一个标准的MRAID广告，可以调用open方法，它将会打开一个浏览器窗口用于查看外部HTML。只要有可能，open操作将通过一个App内嵌浏览器打开。
772 |
773 | **open**方法
774 |
775 | 调用open方法会显示一个App内嵌浏览器用于载入一个外部URL。在那些不允许内嵌浏览器的设备平台上，open方法使用本地浏览器载入外部URL。
776 |
777 | 注意：open方法应仅用于那些非MRAID广告的外部网页。外部页面不会载入MRAID兼容的SDK，因此在内嵌浏览器中调用close方法将没有任何效果。它只能通过用户选中浏览器窗口的关闭按钮来关闭，需要特殊实现。
778 |
779 | 使用这个方法用于打开浏览器来载入外部网页。依赖于实现，有可能会打开一个外部浏览器。为了保持MRAID不跳出的广告体验，使用expand方法替代open。
780 |
781 | 本地浏览器的控制“回退、前进、刷新、关闭”将一直显示。为了报表，open方法可能会被SDK供应商作为一个报告事件来使用。
782 |
783 | open(URL)
784 |
785 | 参数：
786 | · URL - String, 网页URL
787 | 返回值：
788 | · None
789 |
790 |
791 | ## 超链接
792 |
793 | 当用户在MRAID广告中点击一个HTML超链接（通过``标签定义），会有两种可能：目标页面可以在现有的Web View中载入，或者目标页内容可以打开一个独立的浏览器窗口并在那里载入这个链接。兼容MRAID的SDK可以选择两种方式的任何一种，因此广告设计者们应避免使用内嵌超链接和`window.location`。对于一个标准MRAID广告，指定链接要在单独的浏览器中打开页面时，`mraid.open()`才是恰当的方法。在广告视图中加载新网页后可以离开广告并没有被写入MRAID规范中，App此时也许处在不可用状态。
794 |
795 | ## 处理Call-to-Action事件
796 |
797 | 富媒体广告超过迷你站，实现多种call-to-action事件接口。这些事件可能作为一个锚点或脚本函数执行。它意味着容器或SDK不能仅仅监听浏览器接口。必须还要支持可编程的接口/点击（例如`window.location`改变）
798 |
799 | ## Expand：简单的，模态的，增加广告的尺寸
800 |
801 | 对于那些需要用相对简单的方式改变大小的广告创意，通常是从横幅扩大至全屏大小，expand方法提供了一种简单的方式来传达给容器。
802 |
803 | **expand**方法
804 |
805 | expand方法将引发已存在的Web View（对于one-part创意）或者新的Web View（对于two-part创意），以最高层级（例如，在一个比任何App内容都要高的z-index值）打开。展开后的视图要么包含一个全新的HTML文档（如果指定URL），要么继续使用原先默认位置的文档。当广告处于展开状态时，默认位置通常会被隐藏或者让浏览者难以访问，因此当展开状态可用时，默认位置不应该有任何动作。因而，一个完整的创意实现允许广告设计者使用one-part广告（banner和面板是同一个创意的一部分）和two-part广告（banner和面板分别是独立的HTML创意）
806 |
807 | expand方法可以改变广告容器大小，同时将状态从default或resized更改为expanded，然后触发stateChange事件。在one-piece广告和two-piece广告案例中，多次调用expand()将被忽略，也不会影响其状态（仍然保持expanded状态）
808 |
809 | 一个展开后的视图必须覆盖屏幕所有可用区域，尽管广告创意或许不需要（比如，通过透明或非透明遮罩）。展开后的广告总是模态的，在此期间，容器自然的应阻止新的来自loading的广告，以便于用户可以不中断的完成与广告创意之间的任何交互。其它个别应用程序的难点，比如使用多个窗口对象构建App，或者定时改变内容的z-order，当实现expand方法时，SDK供应商必须考虑这些问题。
810 |
811 | 展开后的视图必须允许终端用户可以关闭当前创意。这一点在下文关闭可扩展型广告和插播式广告的描述中被进一步论述。
812 |
813 | 在屏幕的什么位置上放置展开后的广告，尤其当展开后的视图可以被放置在多个位置时，这些由广告设计者决定。对于全屏扩展广告，所有MRAID兼容的SDK将给予完整的设备屏幕空间，同时定位广告以便于它完全可见。
814 |
815 | 当广告的尺寸比设备屏幕的尺寸更大或更小时，SDK将调整Web View的尺寸同设备和App所允许的最大尺寸一致。创意不会按比例的缩小或增大到设备屏幕的大小；而是在展开的Web View之内，通过css position来增大广告创意。
816 |
817 | 
818 |
819 | 当不传入URL参数调用expand方法时，当前视图将被重用，简化报告和广告制作。原有的素材不用重新加载，也不需要记录额外的展示次数。one-part创意允许这种定义。
820 |
821 | 当传入URL参数调用expand方法时，将使用一个新的视图。two-part创意允许这种定义。应用two-part扩展型广告时，第二部分（通过URL指向的）必须是一个完整的HTML页面（不是HTML片段/碎片），同时必须单独的从SDK/容器请求mraid.js（假设它需要MRAID）。不管广告展开后的部分是否请求mraid.js，控制器总是会提供关闭控制（可选的，取决于如何设置expandProperties）和关闭指引。
822 |
823 | expand([URL])
824 |
825 | 参数：
826 | · URL (可选): 本文中的URL会在一个新的遮罩视图中显示。如果传入null或者不使用此参数，当前广告的主体会在同一个Web View中使用
827 | 返回值：
828 | · none
829 | 触发事件：
830 | stateChange
831 |
832 |
833 | ## 控制expand属性
834 | expand属性是为了给广告设计者提供额外的功能。广告设计者可以通过设置expand属性来限制广告素材的宽和高，不管创意是否提供了自定义的关闭指引。expandProperties保存在一个可读写的JavaScript对象中。广告设计者也可以通过方向属性单独的控制展开式广告的方向。
835 |
836 | expand属性只能在expand()方法调用之前设置。当广告处于expanded状态时，设置expand属性将没有效果。
837 |
838 | ```
839 | expandProperties object = {
840 | “width” : integer,
841 | “height” : integer,
842 | “useCustomClose” : boolean,
843 | “isModal” : boolean (read only)
844 | }
845 | ```
846 |
847 | 属性：
848 |
849 | * width：integer —— 创意的宽度，默认为全屏后的宽。
850 | * height：integer —— 创意的高度，默认为全屏后的高。注意在设置前得到的宽高属性值实际上就是屏幕的宽高值。这允许那些想使用App或设备尺寸信息的广告设计者，在有必要时进行调整。
851 | * useCustomClose: boolean —— 为true时，广告容器不再显示默认的关闭图标，依赖广告创意自定义关闭指引；为false时（默认），显示默认关闭图标。此属性有一个完全相同功能的useCustomClose方法（下文描述），方便广告创建者使用。
852 | * isModal: boolean —— 为true时，广告容器是模态的；为false时，广告容器是非模态的。这是一个只读属性。注意在MRAID1.0中，它的值可以是false，但在MRAID2.0中永远返回true。
853 |
854 | **getExpandProperties** 方法
855 |
856 | getExpandProperties方法返回完整的含有expand属性的JavaScript对象。
857 |
858 | 使用此方法来获取属性扩展广告。
859 |
860 | getExpandProperties() -> JavaScript Object
861 |
862 | 参数：
863 | · none
864 | 返回值：
865 | · { ... } - this object contains the expand properties
866 | 触发事件:
867 | · none
868 |
869 |
870 | **setExpandProperties** 方法
871 |
872 | setExpandProperties设置整个含有expand属性的JavaScript对象。
873 |
874 | setExpandProperties(properties)
875 |
876 | 使用这个方法设置广告的展开属性，包括广告创意的最大宽度和高度。
877 |
878 |
879 | 参数：
880 | · properties: JavaScript Object { ... } —— 这个对象包含广告的宽高值，更多属性参考properties对象.
881 | 返回值：
882 | · none
883 | 触发事件：
884 | · none
885 |
886 |
887 | ## 控制方向属性
888 | 对于展开式广告和插播式广告，orientation属性对象为广告设计者提供了更多的控制权。orientationProperties保存在一个可读写的JavaScript对象中。orientationProperties只影响处于expanded状态的展开式广告或插播式广告。一个处于default状态的banner不能使用orientationProperties来阻止App重新定向，或者强迫App切换到一个不同的方向布局。缩放式广告可以使用orientation属性，但是它们将不会产生任何作用。
889 |
890 | ```
891 | orientationProperties object = {
892 | "allowOrientationChange" : boolean,
893 | "forceOrientation" : "portrait|landscape|none"
894 | }
895 | ```
896 |
897 | * allowOrientationChange: boolean —— 如果设置为true，广告容器将允许基于设备取向的变化；如果设置为false，则忽略这种变化（例如：即使设备改变方向，Web View也不会改变）。默认值是true。不管allowOrientationChange如何设定，广告创意通过设置forceOrientation的值总是可以改变它们的方向。
898 | * forceOrientation: string —— 可以设置portrait、landscape、none其中一个值。如果设置了forceOrientation的值，不管设备的方向如何，视图都必须以特定方向打开。也就是说，如果用户在横屏模式下观看广告，并且点击展开它，如果广告设计者把forceOrientation的属性设置为portrait，那么广告将以竖屏模式打开。默认值为none。
899 |
900 | 为了能更精细的控制广告行为，在广告处于expanded之后，无论方向属性是什么，广告设计者都可以改变它的值。这种广告或许在横屏模式启动，但指引用户改变方向来玩一个游戏。游戏需求倾向于，除非用户完成它，否则不允许用户改变方向。MRAID兼容的SDK必须能够接受各处用户交互的方向属性改变
901 |
902 | 举个例子：
903 |
904 | ```
905 | mraid.setOrientationProperties ( {"allowOrientationChange":true} );
906 | mraid.expand()
907 | /* user changes to landscape, starts game */
908 | mraid.setOrientationProperties ( {"allowOrientationChange": false } );
909 | /* user is done with game */
910 | mraid.setOrientationProperties ( {"allowOrientationChange":true} );
911 | ```
912 |
913 | **getOrientationProperties** 方法
914 |
915 | getOrientationProperties方法返回完整的含有orientation属性的JavaScript对象。
916 |
917 | 使用这个方法为展开式广告的展开部分或者插播式广告获取方向属性。
918 |
919 | getOrientationProperties() -> JavaScript Object
920 |
921 | 参数：
922 | · none
923 | 返回值：
924 | · { ... } —— 这个对象包含orientation属性。
925 | 触发事件：
926 | · none
927 |
928 |
929 | **setOrientationProperties** 方法
930 |
931 | setOrientationProperties设置JavaScript方向属性对象。
932 |
933 | setOrientationProperties(properties)
934 |
935 | 使用这个方法设置广告的方向属性。
936 |
937 |
938 | 参数：
939 | · properties: JavaScript Object { ... } —— 这个对象包含allowOrientationChange和forceOrientation的值。
940 | 返回值：
941 | · none
942 | 触发事件：
943 | · none
944 |
945 |
946 | ## 关闭展开式广告和插播式广告
947 |
948 | MRAID兼容的SDK必须提供给终端用户关闭广告的能力。这个要求保证了即使广告出错，用户也能回到内容中去。广告设计者通过close()方法（下文描述），能够自己决定是否提供额外的设计元素用于关闭广告。MRAID从两个方面来区分关闭功能：
949 |
950 | * 关闭事件区：广告创意上的一个可点击区域，能使广告关闭回到它默认状态。对于所有MRAID展开式广告和插播式广告，关闭事件区是必须的，它由容器提供并出现在容器的右上角。
951 | * 关闭指引：给用户一个视觉提醒，指示他们关闭事件区所在的位置。容器会在广告关闭区提供一个默认的关闭指引。创意设计者还可以使用他们自定义的关闭图标，此时他们应禁止默认关闭指引。
952 |
953 | MRAID要求在容器右上角预留的关闭事件区是50x50的可触控区域。预留可点击区域为广告设计者运行跨App和富媒体供应商提供了一致性。供应商/App出版商的控制关闭指引一般默认设计到左边。广告设计者可以自行选择是否为默认关闭功能提供指引。如果广告设计者在创意中引入关闭指引，他们必须这样指定：通过useCustomClose()方法，或者在expandProperties()中设置useCustomClose属性。如果广告设计者不提供自定义关闭图标，容器将提供默认关闭指引。容器提供的可触控区域将被放置在一个比其它App或广告内容更高层级的位置，并且对终端用户永远可用。
954 |
955 | **对于two-part广告：** 如果调用expand方法时传入URL参数（即two-part广告），那么关闭广告后必须显示原有内容。当广告变为展开状态时如果App暂停，那么应通知App扩展状态发生了改变。
956 |
957 | **对于one-part广告：** 如果展开式或插播式广告视图是使用容器提供的关闭事件区关闭的，那么stateChange事件依旧会被触发同时通知App扩展状态发生了改变。展开的广告必须一直监听stateChange事件，并且在必要时进行调整。
958 |
959 | **close** 方法
960 |
961 | close方法会使广告容器回到初始状态。对于处在expanded或resized状态的广告，调用close方法会将广告状态变为default。对于处在default状态的插播式广告，调用close方法会将广告状态变为hidden。在本规范中，对于处在default状态的横幅广告，调用close产生的影响特意留下没有定义。它依赖于特定实现，可能被忽略，或者产生一个错误，再或者将横幅广告的状态变为hidden。因此，一般不建议广告设计者在横幅广告中调用mraid.close()方法。广告设计者或许可以把它当做MRAID强制关闭要求的一个附加方法来使用。它也会触发stateChage事件。
962 |
963 | 注意：如果一个广告多次调用resize()或者在expand()之后调用resize()，调用close()方法会将创意返回到它默认状态（横幅）。它不是简单的撤销最近的resize()或expand()调用。
964 |
965 | close()
966 |
967 | 参数：
968 | · none
969 | 返回值：
970 | · none
971 | 触发事件：
972 | · stateChange
973 |
974 |
975 | **useCustomClose** 方法
976 |
977 | 尽管MRAID要求所有的实现容器必须提供一个含默认关闭图标的可点击区域，但对于广告创建者来说，使用他们自己设计的关闭指引也是可能的。
978 |
979 | 这个方法作为expand属性中一个同名属性的快捷方法。设置useCustomClose属性或者调用此方法，两者具有相同的效果，可以互换着使用。如果一个广告通过expand属性和此方法都设置了useCustomClose，任何较晚的调用将覆盖较早的设置。他们通知容器停止使用默认的关闭指引。
980 |
981 | 对于展开式广告，设计者不需要调用此方法，通常在setExpandProperties()方法中设定useCustomClose属性即可。
982 |
983 | 对于那些无法调用expand方法的独立插播式广告，但是仍然要求具有MRAID强制关闭选项，广告设计者应在ready事件完成后立即调用该方法。
984 |
985 | 广告设计者应该清楚直到useCustomeClose方法被调用或者属性被设置之前，MRAID兼容的SDK必须显示默认的关闭指引。
986 |
987 | useCustomClose(boolean)
988 |
989 | 参数：
990 | · true —— 广告创意提供它们自己设计的关闭指引
991 | · false —— 将会显示容器为关闭指引提供的默认图片
992 | 返回值：
993 | · none
994 | 触发事件：
995 | · none
996 |
997 |
998 | ## Resize：可完成复杂的广告尺寸变化
999 |
1000 | 广告创意需要进行连续的尺寸变化，或非模态的改变尺寸到小于全屏尺寸，通过调用resize方法能够实现。正如expand那样，resize方法工作在一个z-index值比App内容更高的层级，因而被放置在App内容之上，也不用占用或重新定位App内容。
1001 |
1002 | **resize** 方法
1003 |
1004 | resize方法使用现有的HTML文档来改变Web View的大小。像expand()一样，resize()引起的尺寸改变也发生在视图的最高层级，所以不会自动转移或以其他方式重新定位底层内容。那些想支持内容移动广告（像“推-下”）的App出版商，可以使用resize这样做，但是必须单独的实现响应resize的移动App内容。
1005 |
1006 | 调用resize方法会使广告状态从default变为resized，并且触发stateChange事件。创意可以多次调用resize方法。额外的调用也会触发stateChange事件，尽管状态仍然是resized。处于expanded状态时，调用resize会导致错误，并且不会改变状态。
1007 |
1008 | 注意：那些展开至全屏（或更大尺寸）的广告创意不应使用resize，这类广告创意应该总是使用expand。调用resize永远会产生非模态的尺寸变化，并且App的一部分对终端用户总是可见。
1009 |
1010 | 使用此方法来请求默认广告视图调整它们的大小到所需尺寸和屏幕位置。有一点需要注意的是：resize()依赖存储在resize属性对象中的参数。因此，在试图调用resize()之前，创意必须通过setResizeProperties()方法设置他们的参数。在setResizeProperties属性之前调用resize将产生错误。
1011 |
1012 | 容器会通知App广告创意的resize请求，以便于App可以对改变作出适当的反应。举个例子：某个积分出版商监听resize()调用以实现像“推-下”这样的广告。如果resize是有效的，那么sizeChange将被触发。如果参数超出指定范围，那么error事件会捕获这个异常。
1013 |
1014 | resize()
1015 |
1016 | 参数：
1017 | · none
1018 | 返回值：
1019 | · none
1020 | 触发事件：
1021 | · sizeChange, stateChange
1022 | 侧面影响：
1023 | · 改变状态
1024 |
1025 |
1026 | **调整尺寸后的广告关闭控制**
1027 |
1028 | 像展开后的广告一样，对于浏览广告的人来说，调整尺寸后的广告必须有办法能使广告回到它默认状态。MRAID从两个方面来区分关闭功能：
1029 |
1030 | * 关闭事件区：广告创意上的一个可点击区域，能使广告关闭回到它默认状态。对于所有MRAID缩放式广告，关闭事件区是必须的，它由容器提供并由创意指定位置。
1031 | * 关闭指引：给用户一个视觉提醒，指示他们关闭事件区所在的位置。对于缩放式广告，容器不会在关闭事件区提供关闭指引。相反的，广告创意必须总是提供它们的自定义关闭图标。
1032 |
1033 | 因此MRAID兼容的SDK必须始终要在广告创意上提供给容器50x50的关闭事件区域（点击后使广告回到默认状态）。虽然必须要有这个关闭事件区，但是广告设计者可以自行指定它在广告上的位置。如果广告设计者选择不为关闭事件区指定位置，那么容器会把它定位到缩放式广告的右上角。
1034 |
1035 | 缩放式广告在调整自身大小时必须保证关闭事件区在屏幕上能出现。如果容器/SDK检测到一个将导致关闭事件区离开屏幕的缩放请求，容器/SDK会返回错误，并忽略resize操作（即：保留广告的当前状态）。这个要求也意味着，为了保证在缩放后的创意上有关闭事件区空间，缩放式广告最低要求50x50像素.
1036 |
1037 | 对于resize()，不像expand()那样，容器会提供一个默认关闭指引。它更期待广告设计者在创意中自己引入关闭指引。
1038 |
1039 | 虽然点击关闭控制是强制性的，但是通过close()方法，广告设计者可以自由的采用其它方式来关闭广告。
1040 |
1041 | **resizeProperties** 对象
1042 |
1043 | ```
1044 | resizeProperties object = {
1045 | “width” : integer,
1046 | “height” : integer,
1047 | “offsetX” : integer,
1048 | “offsetY” : integer,
1049 | “customClosePosition” : string,
1050 | “allowOffscreen” : boolean
1051 | }
1052 | ```
1053 |
1054 | 注释：
1055 |
1056 | * width: integer —— （必须）创意的像素宽
1057 | * height: integer —— （必须）创意的像素高
1058 | * offsetX: —— （必须）TODO
1059 | * offsetY: —— （必须）TODO
1060 | * customClosePosition: string —— （可选）"top-right"、"center"、"bottom-left"、"bottom-right"、“top-center”或者“bottom-center”。表示相对于缩放的创意，容器提供的关闭事件区的原点位置。如果没有指定或者不是这些选项之一，默认取"top-right"。
1061 | * allowOffscreen: —— （可选）告诉容器是否应该允许缩放创意绘制完整/部分的超出屏幕。
1062 | * **True (default)**: 容器不应试图定位缩放创意。
1063 | * False: 容器应尽量重新调整缩放创意来适应getMaxSize()的取值。
1064 |
1065 | 当allowOffscreen设置为false时，SDK会尽可能的移动默认（banner）广告容器以保证缩放的创意适应屏幕。举个例子，如果一个在屏幕最上方的广告，想往上扩展50像素，那么SDK将先把默认（banner）广告向下移动50像素，然后再执行resize。这种情况下如何allowOffscrren设置为true，广告展开后的部分将超出屏幕的顶部。
1066 |
1067 | allowOffscreen并不能解决所有的定位问题。比如，如果一个广告在横屏方向成功的缩放，但随后由于方向改变为纵向，变得比屏幕的尺寸大，此时设置为false的allowOffscreen将没有效果，同样的，容器/SDK也没有办法成功的将横向创意重定向成适合竖向屏幕。
1068 |
1069 | 注意width、height、offsetX和offsetY是必须的，他们没有默认属性值。如果广告创意视图在设置这四个属性之前调用resize()，容器会保留广告处于当前状态并返回错误。
1070 |
1071 | **getResizeProperties** 方法
1072 |
1073 | getResizeProperties返回完整的含有resize属性的JS对象。
1074 |
1075 | 使用此方法获取广告缩放后的属性。
1076 |
1077 | getResizeProperties() -> JavaScript Object
1078 |
1079 | 参数：
1080 | · none
1081 | 返回值：
1082 | · { ... } - 包含resize属性的JS对象
1083 | 触发事件：
1084 | · none
1085 |
1086 |
1087 | **setResizeProperties** 方法
1088 |
1089 | 使用此方法来设置广告的缩放属性，特别是width和height属性。
1090 |
1091 | 参数：
1092 | · properties: JavaScript Object { ... } —— 这个对象包含要缩放广告的宽和高、关闭位置、偏移方向（都以DIP为单位）、广告是否可以缩放到离开屏幕。更多信息见resizeProperties对象。
1093 | 返回值：
1094 | · none
1095 | 触发事件：
1096 | · none
1097 |
1098 |
1099 | QA需要仔细的测试缩放型广告。像下面这样，广告给容器设置一个不可能的参数，会触发error事件并且resize不会执行。比如说，如果某个广告设置allowOffscreen为false，但是设置了比实际适合屏幕尺寸要大的宽和高，那么就会发生错误。
1100 |
1101 | ## 检测屏幕和广告的位置及大小
1102 |
1103 | MRAID2.0引入了几个能使广告监测它自身展开到哪儿和展开到多大的方法，还有它可以展开的最大尺寸。广告设计者可以使用这些特性来增强广告的灵活性，以便在不同设备或不同屏幕尺寸的设备上有不同的行为。
1104 |
1105 | **getCurrentPosition** 方法
1106 |
1107 | getCurrentPosition方法返回广告视图当前的位置和尺寸，以DIP为单位。
1108 |
1109 | getCurrentPosition() -> JavaScript Object
1110 |
1111 | 参数：
1112 | · none
1113 | 返回值：
1114 | · JavaScript Object - {x, y, width, height}：
1115 | x=从getMaxSize方法定义的矩形左边开始的偏移量（DIP为单位）
1116 | y=从getMaxSize方法定义的矩形顶部开始的偏移量（DIP为单位）
1117 | width=当前容器的宽。
1118 | height=当前容器的高。（都是以DIP为单位）
1119 | 关联事件：
1120 | · none
1121 |
1122 |
1123 | **getMaxSize** 方法
1124 |
1125 | getMaxSize方法返回广告可以展开到或缩放到的最大尺寸（宽和高都以DIP为单位）。如果App在设备上全屏运行（即：覆盖状态栏），最大尺寸即是全屏的大小。如果App以小于全屏尺寸在设备上运行，因为屏幕要为状态栏或其他App外部元素保留区域，所以getMaxSize将返回包含App视图（它定义了广告所能调整大小的最大空间）的尺寸。
1126 |
1127 | getMaxSize() -> JavaScript Object
1128 |
1129 | 参数：
1130 | · none
1131 | 返回值：
1132 | · JavaScript Object, {width, height} —— 视图可以增长到的最大宽和高
1133 | 关联事件：
1134 | · none
1135 |
1136 |
1137 | **sizeChange** 事件
1138 |
1139 | 当广告的尺寸在App界面内发生改变时会触发sizeChange事件。它可能是设备方向改变或调用resize或调用expand方法产生的结果。都是以DIP为单位。
1140 |
1141 | 当广告的Web View的显示状态发生改变时，触发此事件。
1142 |
1143 | sizeChange -> function(width, height)
1144 |
1145 | 参数：
1146 | · width - Number: 视图的宽。
1147 | · height - Number: 视图的高。
1148 | 经由触发：
1149 | · 缩放、展开、关闭、方向改变或者在App注册尺寸相关事件监听器后导致广告视图尺寸发生改变时触发。
1150 |
1151 |
1152 | **getDefaultPosition** 方法
1153 |
1154 | 不管视图处于何种状态时调用，getDefaultPosition方法都将返回默认广告视图的位置和尺寸（DIP为单位）。
1155 |
1156 | 使用此方法获取默认广告视图的位置和尺寸。
1157 |
1158 | getDefaultPosition() -> JavaScript Object
1159 |
1160 | 参数：
1161 | · none
1162 | 返回值：
1163 | · JavaScript Object - {x, y, width, height}：
1164 | x=从getMaxSize左边开始的偏移量（DIP为单位）；
1165 | y=从getMaxSize顶部开始的偏移量（DIP为单位）；
1166 | width=当前容器的宽；
1167 | height=当前容器的高；
1168 |
1169 |
1170 | **getScreenSize** 方法
1171 |
1172 | getScreenSize方法基于当前方向，以DIP为单位，返回正在运行广告设备的实际像素宽和高。有一点需要注意的是：如果设备从横屏转为竖屏，ScreenSize将发生改变（反之亦然）。另外一点需要注意的是：getScreenSize返回设备屏幕的总计尺寸，包含操作系统给状态栏/系统栏的预留区域，或那些可以被App或广告覆盖的其它区域。设计师寻找能够检查创意还有多少屏幕可用区域时，getMaxSize比getScreenSize更好。
1173 |
1174 | getScreenSize() -> JavaScript Object
1175 |
1176 | 参数：
1177 | · none
1178 | 返回值：
1179 | · {width, height}
1180 | 关联事件：
1181 |
1182 |
1183 | ## 离线请求和指标
1184 |
1185 | 当设备没有网络连接时，富媒体广告也可以工作，要完成这项任务需要有本地存储和延迟转发功能，衡量用户会在什么时候和广告交互以及如何交互。
1186 |
1187 | MRAID有潜力提供通用的API以促进存储和广告效果转发，以及其它一些从App返回到广告服务器的指标。然而，除非测量方法和指标本身是标准化的（比如正在进行的IAB/MMA/MRCAPP内广告度量指南），在这之前向MRAID中添加测量功能都为时过早。
1188 |
1189 | MRAID工作组希望这些特性能被评估，并且有可能添加到MRAID中，成为以后MRAID发布版的一部分。
1190 |
1191 | ## 访问本地功能
1192 |
1193 | 在广告设计中，对于图像需求，基础功能，甚至日益递增的被真正富媒体广告所需要的高级广告功能清单， MRAID都鼓励尽可能的使用标准Web技术。围绕着本地特性，MRAID扮演的角色是帮助富媒体广告发现设备有什么本地功能可以支持，并且填补那些没有普及可用的功能，或者HTML5/Webkit中没有完全稳定和统一的特性。
1194 |
1195 | **supports** 方法
1196 |
1197 | supports方法允许广告询问设备支持的指定功能。
1198 |
1199 | 一个MRAID兼容的SDK，在任何设备中都必须能够提供以下功能列表中哪一项是可用的。然而，个别出版商实现的SDK可能会导致和出版商政策相冲突的停用功能/特性。
1200 |
1201 |
1202 |
1203 | | 值 |
1204 | 描述 |
1205 |
1206 |
1207 | | sms |
1208 | 设备支持使用短消息功能：按照协议发送一个短消息 |
1209 |
1210 |
1211 | | tel |
1212 | 设备支持使用电话功能拨打电话：按协议 |
1213 |
1214 |
1215 | | calendar |
1216 | 设备可以创建一个日历项 |
1217 |
1218 |
1219 | | storePicture |
1220 | 设备支持MRAID storePicture方法 |
1221 |
1222 |
1223 | | inlineVideo |
1224 | 设备可以使用<video>标签播放HTML5视屏文件，并且按着video标签中指定的尺寸（宽和高）播放。这里并不需要以全屏方式播放视频。 |
1225 |
1226 |
1227 |
1228 | supports(feature) -> Boolean
1229 |
1230 |
1231 | 参数：
1232 | · String 要检测特性的名称（sms, tel, calendar, storePicture, inlineVideo）
1233 | return values:
1234 | · Boolean
1235 | true —— 支持该功能，并且getter和事件都是可用的。
1236 | false —— 当前设备不支持本功能。
1237 |
1238 |
1239 | ## 用设备的物理特性工作
1240 |
1241 | 大多数设备都有几种不同类型的传感器可以报告该设备的各种物理特性，例如它的位置，指向，取向，和运动轨迹。当前，在HTML5中，访问这些特性中的大部分功能已成为标准（或者在不远的将来），在这种情况下，开放的标准提供访问设备的功能或特性，MRAID标准推迟到开放标准之后。
1242 |
1243 | **设备方向**
1244 |
1245 | 广告创意应能通过HTML5请求设备或容器的方向，和MRAID实现一致的跨设备。对于Android和iOS5.0之后的版本，它们原本就支持，然而，为了在合适的时机触发窗口方向改变，早期的iOS实现需要SDK供应商提供部分代码调整。
1246 |
1247 | 为了兼容MRAID2.0，SDK需要为iOS5.0以前的苹果设备部署这类代码修改。虽然SDK供应商可以使用他们钟情的任何技术方案来达到此目的，下面的示例代码提供了解决这个问题的一种方法。
1248 |
1249 | ```
1250 | (void)didRotateFromInterfaceOrientation:(UIInterfaceOrientation) fromInterfaceOrientation {
1251 |
1252 | if (UIInterfaceOrientationIsPortrait(newOrientation) ||
1253 | UIInterfaceOrientationIsLandscape(newOrientation)) {
1254 | NSInteger degrees = 0;
1255 | switch (self.interfaceOrientation) {
1256 | case UIInterfaceOrientationPortrait:
1257 | degrees = 0;
1258 | break;
1259 | case UIInterfaceOrientationLandscapeLeft:
1260 | degrees = 90;
1261 | break;
1262 | case UIInterfaceOrientationLandscapeRight:
1263 | degrees = -90;
1264 | break;
1265 | case UIInterfaceOrientationPortraitUpsideDown:
1266 | degrees = 180;
1267 | break;
1268 | default:
1269 | // Don't care about this orientation.
1270 | return;
1271 | }
1272 | // Update the window.orientation property then trigger
1273 | // onorientationchange().
1274 | NSString *javascript = [NSString stringWithFormat:
1275 | // Create the 'window.orientation' read-only property.
1276 | @"window.__defineGetter__('orientation',function(){return %i;});"
1277 | // Dispatch the 'orientationchange' event. This also calls
1278 | // 'window.onorientationchange()'.
1279 | @"(function(){"
1280 | @"var event = document.createEvent('Events');"
1281 | @"event.initEvent('orientationchange', true, false);"
1282 | @"window.dispatchEvent(event);"
1283 | @"})();",
1284 | degrees];
1285 | [self.webView stringByEvaluatingJavaScriptFromString:javascript];
1286 | }
1287 |
1288 | }
1289 | ```
1290 |
1291 | 广告设计者不能依靠window.orientation来确定设备是否处于横屏还是竖屏模式。window.orientation的值意在表示相对于标准方向轴的屏幕位置，即：基于DeviceOrientationEvent报告的值。但是，标准的方向不一定就是横屏模式（高比宽大）。的确，在Android宽屏平板电脑上，比如三星Galaxy Tab 10.1，当设备处于竖屏模式（宽比高大）时，window.orientation的值为零.
1292 |
1293 | 广告设计者应替代使用mraid.getScreenSize()方法来取得设备当前屏幕的宽和高。
1294 |
1295 | ## 存储图片
1296 |
1297 | 富媒体广告设计者可能会想添加一张图片到他们正在运行设备的相册。对于某些功能，这很实用，比如存储用于未来兑换用的优惠券。
1298 |
1299 | **storePicture** 方法
1300 |
1301 | 调用storePicture方法会在设备相册中放任一张图片。图片可能是本地或者从网络下载的。为了确保用户注意到图片将添加到他们的设备相册，在每张图片的添加过程中，MRAID要求SDK/容器使用操作系统层级的处理器显示模型对话框询问用户确认或取消添加图片。如果设备没有本地添加图片确认处理器，SDK应把设备看做为不支持storePicture。
1302 |
1303 | 此方法用于存储图片或通过URI指定的其它媒体类型。
1304 |
1305 | MRAID兼容的容器支持通过HTTP重定向（为了跟踪统计）添加图片；然而他们倒是没必要支持meta重定向。
1306 |
1307 | 如果因为任何原因引起的添加图片失败或用户取消添加，将引发错误。
1308 |
1309 | storePicture(URI)
1310 |
1311 | 参数：
1312 | · URI - String：图片或其他媒体资源的URI
1313 | 关联事件：
1314 | · none
1315 |
1316 |
1317 | ## 创建日历事件
1318 |
1319 | createCalendarEvent方法打开设备的界面用于创建一个新的日历事件。当界面展开时，广告暂停。为了确保创建日历事件始终是用户发起和授权的，MRAID兼容的容器必须调用设备的本机“创建日历事件”接口，预先填充由广告提供的数据。当设备不支持这种“创建日历事件”接口时，SDK应视为设备不支持添加日历事件。
1320 |
1321 | 应按照W3C日历规范编写JS对象作为数据提供给日历事件。参考附录部分。
1322 |
1323 | 如果尝试创建日历事件失败或用户取消创建，将引发错误。
1324 |
1325 | createCalendarEvent(parameters)
1326 |
1327 | 参数：
1328 | · parameters: JavaScript Object {…} —— 对象包含日历事件所需的条目，根据W3C规范指定的日历条目编写。参考附录。
1329 | 返回值：
1330 | · none
1331 | 关联事件：
1332 | · none
1333 |
1334 |
1335 | 比如，以下在2012.12.21号为玛雅预言世界末日添加一个日历事件，选择位置为“任意地点”，起始日期为东部时间凌晨，结束日期为东部时间2012.12.22凌晨。
1336 |
1337 | ```
1338 | createCalendarEvent({
1339 | description: “Mayan Apocalypse/End of World”,
1340 | location: ‘everywhere’,
1341 | start: ‘2012-12-21T00:00-05:00,
1342 | end: ‘2012-12-22T00:00-05:00’
1343 | })
1344 | ```
1345 |
1346 | ## 处理视频
1347 |
1348 | 移动设备上的视频播放要么通过行内播放（在当前Web View里，App中或移动网页），要么通过打开本地播放器播放。对于大部分App的广告来说，首选行内播放：它较少的破坏观者体验，同时，使用Web View播放可以通过HTML5报告有关创意被观看了多少次的指标。当视频在本地播放器中观看时，这些指标通常都难以获取或不可用。
1349 |
1350 | 广告设计者必须牢记：设备/操作系统限制可能会阻止行内视频播放（尤其在设备运行Android2.x版本和早期版本的情况下）。
1351 |
1352 | 然而，在有可能的情况下，MRAID兼容的容器最好支持行内播放，同时允许广告设计者指定视频创意是以行内播放还是单独播放。广告设计者可以使用“supports(inlineVideo)”方法确定运行创意的设备是否显示行内视频。
1353 |
1354 | 为了使内嵌式视频能够播放并且自动播放，MRAID兼容的SDK应向Web View中插入必要的开启标签，这依赖于设备的操作系统类型。
1355 |
1356 | 对于iOS设备，必须使用下列标签：
1357 |
1358 | * webView.mediaPlaybackRequiresUserAction = NO;
1359 | * webView.allowsInlineMediaPlayback = YES;
1360 |
1361 | 对于Android设备（Honeycomb，Ice Cream Sandwich，还有它们之后的版本），SDK必须请求硬件加速，这些依赖于问题中的视图和它是如何被添加到WindowManager中的：
1362 |
1363 | * getWindow().setFlags(WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED, WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED);
1364 |
1365 | 对于Android2.x和早期设备，是不可能播放行内视频的；playVideo方法始终只调用本地播放器。
1366 |
1367 | **playVideo** 方法
1368 |
1369 | 使用此方法通过设备的本机外部播放器在设备上播放视频。需要注意的是，对于操作系统已有的外部播放器，这纯粹是一种便利的方法，并不意味着一个独立的、基于SDK的视频播放器。要播放行内（对于支持该功能的设备）视频，使用HTML5标签。
1370 |
1371 | playVideo(URI)
1372 |
1373 | 参数：
1374 | · URI - String, 视频地址或视频流
1375 | 返回值：
1376 | · none
1377 |
1378 |
--------------------------------------------------------------------------------
/mraid_en.md:
--------------------------------------------------------------------------------
1 |
2 | Interactive Advertising Bureau
3 |
4 | Mobile Rich-media Ad Interface Definitions (MRAID) v.2.0
5 |
6 | Released September 27, 2012,
7 |
8 | Revised With Clarifications April 16, 2013
9 |
10 | # Contributors
11 | The IAB MRAID Working Group includes representatives from the following companies:
12 |
13 | 24/7 Real Media, Inc. Medialets
14 | AccuWeather.com MediaMind
15 | AdMarvel Microsoft Advertising
16 | AdMeld Mixpo
17 | ADTECH Mocean Mobile
18 | Adobe Systems Inc. NBC Universal Digital Media
19 | AOL New York Times Co.
20 | CBS Interactive Nexage
21 | Celtra Pandora
22 | Crisp Media PointRoll
23 | Dow Jones & Company Rhythm NewMedia
24 | ESPN Spongecell
25 | FreeWheel Sprout
26 | Goldspot Media TargetSpot
27 | Google Time Inc.
28 | Greystripe Turner Broadcasting System, Inc.
29 | IDG Univision
30 | inMobi The Weather Channel
31 | Innovid Yahoo!, Inc.
32 | Jumptap
33 |
34 |
35 | # Acknowledgement
36 | The IAB acknowledges the contributors to the ORMMA.org API project, which provided a starting point for this document. ORMMA.org is a group of industry thought leaders who have worked together since Spring 2010 to develop and test a complete and versatile mobile rich media ad API. Contributors to ORMMA at the point the IAB launched the MRAID project included:
37 |
38 | Adam Schuetz, AdMarvel Philippe Laporte, Goldspot Media
39 | Dennis Doughty, Jumptap Robert Hedin, The Weather Channel
40 | Jon Badenell, The Weather Channel Todd Pasternack, Pointroll
41 | Nathan Carver, Crisp Media Wook Chung, Google
42 | Neal Karasic, Jumptap Xavier Facon, Crisp Media
43 |
44 |
45 | # About MRAID
46 | The Interactive Advertising Bureau (“IAB”), its members and other significant contributors joined together to create this document, a standard interface specification for mobile rich media ads. The goal of the Mobile Rich-media Ad Interface Definition (MRAID) project is to address known interoperability issues between publisher mobile applications, different ad servers and different rich media platforms.
47 |
48 | ## IAB Contact Information
49 |
50 | Joe Laszlo, Senior Director, IAB Mobile Marketing Center of Excellence, mobile@iab.net
51 |
52 | # Executive Summary
53 | As rich media display advertising in mobile applications and on the mobile web has become more popular over the last several years, various innovative companies have accepted the challenge of creating an ecosystem for mobile ad serving. Innovation in mobile rich media ad serving has led to many exciting possibilities for content publishers and advertisers, but it has also created inefficiencies that often delay and inhibit the optimal monetization of content.
54 |
55 | Simplifying the process for designers of mobile in-app ad creatives significantly increases the likeliness that agencies will leverage mobile into their media buys. Advertisers want to review compelling creative, approve it and decide to buy a specific inventory of mobile media, regardless of which device platform, application, or technology is used to display the media.
56 |
57 | # Definitions
58 | The following terms are used throughout the MRAID specification.
59 |
60 | **Ad View/Container:** The constrained area which displays the ad creative. The container provides the area on the screen, the MRAID controller, and the web-based view for the ad to display. Ad Containers are usually, though not necessarily, provided by SDKs. An app may contain multiple Ad Containers from a single SDK.
61 |
62 | **Close Event Region:** The close event region is a tappable area on the ad creative that will cause the ad to return to its default state (in the case of an expandable/resizeable ad) or be removed from the screen (in the case of an interstitial).
63 |
64 | **Close Indicator:** The close indicator is the visual cue to the user as to the location of the close event region.
65 |
66 | **Controller:** The JavaScript code that provides ad designers access to MRAID methods and events. The ad creative uses the controller to perform advertising-related interactions with the Ad Container, and, indirectly, with the application and the device.
67 |
68 | **Density-Independent Pixels:** All length values passed between the container and the creative through the MRAID API are in density-independent pixels.
69 |
70 | Density-independent pixels are an abstraction from physical screen pixels meant to simplify application and content development across devices of different screen densities.
71 |
72 | Using density-independent pixels means that, for example, retina display iPhones and older iPhones will return the same dimensions/measures, despite having different numbers of physical pixels. 1 density-independent pixel corresponds roughly 1/160 of an inch (1 device pixel on a device with roughly 160 DPI).
73 |
74 | On iOS, these should map to “points”; on Android, to “density-independent pixels”.
75 |
76 | Note: One density-independent pixel will match 1 CSS pixel only if the viewport scale is 1.0. To map between CSS pixels and density-independent pixels, the creative should use the following formula:
77 |
78 | `css_pixels * viewport_scale = density_independent_pixels`
79 |
80 | **Inline Ad:** An ad that appears onscreen accompanied by other kinds of content, e.g., a banner on a web page or in an app.
81 |
82 | **Interstitial Ad:** A full page modal ad that displays on top of content -- a "roadblock" or "overlay." The ad must be dismissed for the user to return to the publisher content. Such ads can appear between levels of a game, or before or after a video clip or other dynamic content. (An ad that is in-between pages and swipes into view like in many magazine apps, is considered an inline ad under MRAID.)
83 |
84 | **Physical Pixels:** The actual pixels on a device screen. For example, a retina-display iPhone measures 960x640 physical pixels. MRAID API length values are always calculated in density-independent pixels (defined above) NOT physical pixels.
85 |
86 | **SDK:** Sofware Development Kit. The reusable piece of code (library) integrated into publisher apps to enable advertisements/Ad Containers. An SDK, by itself, is not a visual component.
87 |
88 | **Web View:** The HTML-based viewer that displays the ad creative. The web view is used to perform rendering of HTML- and Javascript-enabled ads.
89 |
90 | 
91 |
92 | # General Requirements for Supporting MRAID
93 | This section details the requirements of an in-app ad-serving SDK that is MRAID compliant.
94 |
95 | It is expected that an implementation would be in two parts. The first part defines a native container for rich media ads to display in apps and the second part defines a JavaScript controller for ad creatives to interact with. The native container encapsulates an HTML and JavaScript enabled web view, such as iOS’s UIWebView, and the controller serves as a bridge that can integrate HTML-based ads with the native capabilities. Actual implementations may vary.
96 |
97 | When planning, key design considerations are:
98 |
99 | * Access to the device’s native features (orientation, location, acceleration, etc.) in a consistent manner, where allowed by the app publisher/ad seller.
100 | * Industry standard Ad development (HTML and JavaScript)
101 | * Progressive complexity (simple things are simple, complex things are possible but harder)
102 |
103 | ## _Technical Audience_
104 | The specifications are technical by nature, but are not intended to limit innovation. This document is intended for Publishers or SDK vendors and addresses the needs of the Ad Designers.
105 | >### Native Application Developer
106 | There are no requirements in this specification for app developers. They should follow the instructions provided by their SDK developer for integrating ads into their application.
107 | >### SDK Developer
108 | SDK builders have a number of responsibilities outside this recommendation. (See “out-of-scope.”) As mentioned, it is expected that the SDK developer will provide two interfaces to implement these recommendations: a container for the native developer to integrate via the SDK and a controller for the ad designer to use directly.
109 | >This document outlines the requirements of the controller needed by the ad designer. It is the intention of the writers that these concepts can be managed with a facade layer for existing SDKs.
110 | >### Ad Designer
111 | There are no creative requirements in this document for ad designers besides the use of web standards. Ad designers who use the methods in this specification can provide consumers with a rich media experience across platforms and publishers.
112 |
113 | It is important for ad designers to recognize that calls to the native device must be asynchronous by design. For most web developers, this is analogous to AJAX programming.
114 |
115 | ## _Viewport and Default Container Set-Up_
116 | Creative designers should be aware of the need to understand and potentially override the default settings of the web view in which they are running. They should do this by querying an MRAID container just as they would query a web page to understand the environment there. These settings include height and width of the container, scale, and whether the user can change the scale of the container.
117 |
118 | While MRAID does not establish any new parameters or controls over the web view, it is recommended that the creative should check and adjust the parameters, since the author of said creative might wish to set them differently from the default container settings..
119 |
120 | ## _Out of Scope_
121 | Each MRAID implementation provides unique features sets to developers. This document outlines a minimum set of features for interoperability and does not define features that may also be part of an SDK such as
122 |
123 | * Retrieving the ad from Ad Server, Ad Network, or local resources
124 | * Reporting
125 | * IDE integrations
126 | * Security / Privacy
127 | * Internationalization
128 | * Error reporting
129 | * Logging
130 | * Billing and payments
131 | * Ad dimensions and ad behavior
132 | * Downloading of assets to the local file system for caching or off-line use
133 |
134 | Of course, the SDK developer must implement the ability to render web content in the area intended for the ad unit. For most environments, this capability is already available as a web view component although the developer may have to develop additional functions to support these specifications.
135 |
136 | It is the intent of the writers that vendors are not limited to delivering only the features outlined in the API. They should continue to innovate and present features that differentiate them in the marketplace. These other features must be implemented outside the MRAID namespace.
137 |
138 | An ad that uses SDK-specific features in addition to MRAID features would not necessarily be an MRAID ad anymore in the sense of working across all MRAID-compliant SDKs.
139 |
140 | ## _Standard Web Technologies_
141 | For interoperability, only web compatible languages should be used for markup and scripting languages. This document assumes HTML/JavaScript/CSS. The ad designer should be able to develop and test the ad unit in a web browser. If designers use tags, styles and functions which are compatible with only one browser (such as CSS3 on WebKit), then the ad should be targeted to compatible devices.
142 |
143 | When newer web standards can provide consistency, ad designers are encouraged to use them. This may include protocols like sms: and tel:, as well as some widely implemented portions of the as-yet unfinished HTML5 specification. Designers need to be aware that in these cases, the expected protocols and implementations may not be truly interoperable across all devices and platforms.
144 |
145 | ## _Ad Server Requirements_
146 | The ad server used to traffic rich media ads should support HTML ads with JavaScript.
147 |
148 | ## _Requirements for Ad Rendering_
149 | ### Display of HTML Ads – Ad View Container
150 | An MRAID-compatible container must display any HTML ad. The container should invoke an HTML with JavaScript rendering engine for rendering ads. In this document, that engine will be called the "web view". Whenever possible, the web view should incorporate the capabilities of the device web browser. For example, iOS developers may use UIWebView. A given App view can have one or more ad view containers that will all act independently of one another.
151 |
152 | ## _Requirements for Ad Designers_
153 | ### Display Control for Rich Media Ads – Ad Controller
154 | An ad designer that expects his/her ad to make use of MRAID must indicate that by invoking the mraid.js script as soon as possible as the ad loads. This signals the SDK to inject the MRAID javascript into the creative.
155 |
156 | MRAID remains in the background, leaving the ad designer in control of the ad display, but is available so that the creative can use the MRAID API when/if the ad needs to access MRAID features and functionalities. The internal interaction between the creative and the rich media SDK is hidden from both the Ad designer and the App developer.
157 |
158 | An ad that does not utilize any device features does not need to use the MRAID API at all. However if the ad does not invoke MRAID, it will get the SDK’s default solution. Some of the things an ad uses MRAID’s API for are:
159 |
160 | * Opening an embedded web browser
161 | * Detecting whether the ad is viewable or not
162 | * Expanding an ad that grows from a banner to a larger size
163 | * Clicking within an ad triggering an action
164 |
165 | Ad designers are encouraged to rely on MRAID’s capabilities to achieve the above effects.
166 |
167 | ## _Lifecycle Examples_
168 | ### Simple Ad Lifecycle Example
169 | Non-rich-media ads (e.g., basic banners) can optionally invoke MRAID. If the ad does not invoke MRAID via the mraid.js script tag, then it will behave however the application/SDK normally handles such ads.
170 |
171 | Ad designers may wish for such simple HTML ads to invoke mraid.js, if they want to use the MRAID-standard container rather than the SDK’s default container. In that case, the ad designer should make sure to use mraid.open() for any links to ensure consistent behavior.
172 |
173 | ### Lifecycle of an MRAID Expandable Ad Example
174 | In a rich media ad lifecycle example, the Ad Designer uses the JavaScript API to communicate with the native layer and interact with features of the device and OS.
175 | 
176 | As an example, when the user touches the ad, the ad uses the MRAID API to request that the ad can expand. The SDK should (though this is not part of the MRAID specification) notify the app that the ad is expanding so that it can stop anything that the user will not be able to interact with. The SDK then resizes the web view to take up the entire screen of the device or the full size of the expanded ad. The container reserves a space at the top right corner of the expanded ad container for an MRAID-enforced close event region, and will either supply the close indicator or, if the ad specifies, will allow the ad to supply the indicator in creative.
177 |
178 | When the user is done with the expanded ad, they click a close button that causes the ad to resize to its original size, display the ad’s banner state, and notify the app that it can resume.
179 |
180 | ### Lifecycle of an MRAID Interstitial Ad
181 | The case of an interstitial ad is very similar. The ad can use the MRAID API to query the container as to whether it is visible onscreen or not, waiting until it is on before it takes other actions. As with an expandable, the container reserves a space at the top right corner of the expanded ad for an MRAID-enforced close event region, and will either supply the close indicator or, if the ad specifies, will allow the ad to supply the indicator in creative. When the user is done with the interstitial, they can tap the close button, which in this case changes the ad’s state to “hidden,” unregisters any event listeners, and notifies the app to resume.
182 |
183 | ## _MRAID Versions_
184 | The adoption of MRAID throughout the ad community is a high priority and essential for the success of mobile rich media advertising across platforms. For this reason, IAB is releasing the full feature set of MRAID in versions. This will allow SDK vendors to meet the compliance standards of the MRAID API in a consistent way and prevent possible fragmentation inherit in implementing only a portion of the standard.
185 |
186 | Maintaining full backwards compatibility in MRAID is a key goal of this project. An MRAID 2.0-compliant SDK should be able to run an MRAID 1.0 ad with no problems whatsoever, and an MRAID 1.0-compliant SDK should be able to handle the MRAID 1.0-compliant features of an MRAID 2.0 ad.
187 |
188 | In establishing both versions of MRAID, the IAB and its MRAID working group have focused on six key goals:
189 |
190 | * __High interoperability__ – ads developed to run in one MRAID container can run on MRAID containers of multiple platforms and operating systems.
191 | * __Graceful degradation__ – ads developed to take advantage of all the MRAID features also have the capacity to downgrade gracefully as needed. This will be especially important as gaining access to device functionalities becomes part of MRAID’s scope in the future.
192 | * __Progressive complexity__ – ad design using the API should be simple, adding complexity only as necessary.
193 | * __Consistent means for ads to change size and/or open new pages, preferably in an embedded browser__ –MRAID provides ads a consistent way to communicate with rich media SDKs regarding their need to expand, and open an app’s embedded browser (or in the native browser if an embedded browser does not exist).
194 | * __Consistent means for a consumer to exit an ad__ – MRAID ads will always have a consistent control by which a user can indicate that they wish to exit out of the ad experience and return to the app/content they were in.
195 | * __Flexibility for publishers__ – although MRAID-compliant SDKs must support all MRAID capabilities, app publishers/ad sellers are free to allow or disallow ads that make use of the features MRAID enables. That is, MRAID enables rich media ad features, but does not dictate that all sellers of rich media ads must support all those features.
196 |
197 | ### Version 1
198 | The methods and events included in MRAID Version 1 provide a minimum level of requirements for rich media ads, primarily to display HTML ads that can change size in a fixed container (e.g., expand from banner to larger/full screen size), and interstitial ads.
199 |
200 | ### Version 2
201 | MRAID Version 2 extends the capabilities of MRAID Version 1 to give ad designers more control over expandable ads, and provides a new method, resize() that permits more subtle and interesting size changes in ad creatives as well.
202 |
203 | In addition, MRAID v.2 provides a standard way to query a device regarding certain capabilities, offers consistent handling of video creative, and addresses two native capabilities not well implemented by HTML5 at present: adding an entry to the device calendar and storing an image in the device photo roll.
204 |
205 | For examples of ads that can be developed using the MRAID Version 2 API, please see the addendum.
206 |
207 | # Interface Requirements and Definitions
208 | This list outlines all the methods and events that ad designers will have access to under MRAID v2.0. Methods and events new in MRAID v2.0 (e.g., that were not in MRAID v1) are indicated by an asterisk below.
209 |
210 | **Methods**
211 |
212 | addEventListener getVersion
213 | createCalendarEvent* isViewable
214 | close open
215 | expand playVideo*
216 | getCurrentPosition* removeEventListener
217 | getDefaultPosition* resize*
218 | getExpandProperties setExpandProperties
219 | getMaxSize* setResizeProperties*
220 | getPlacementType storePicture*
221 | getResizeProperties* supports*
222 | getScreenSize* useCustomClose
223 | getState getOrientationProperties*
224 | setOrientationProperties*
225 |
226 |
227 | **Events**
228 |
229 | error stateChange
230 | ready viewableChange
231 | sizeChange*
232 |
233 |
234 | ## _Identification_
235 | It is required that ads identify themselves as being MRAID compliant. This is done by adding an MRAID script reference as soon as possible the creative and well before any MRAID functions are referenced in the creative. In other words, the MRAID identification script reference must be identifiable as soon as possible by any MRAID-compliant container or SDK.
236 |
237 | **MRAID** script reference
238 |
239 | The MRAID tag follows HTML Javascript syntax so that both fully formed web pages and HTML fragments can be identified as MRAID ads. mraid.js will be included as a script in the document either using an HTML tag or as javascript. MRAID sample ads ([www.iab.net/mraid](http://www.iab.net/mraid)) illustrate where the script tag should be positioned.
240 |
241 | ``
242 |
243 | While MRAID ads need to identify themselves as such via the mraid.js script in a timely fashion so that the container can inject the MRAID libraries, ad designers should avoid using the string “mraid.js” for any other purpose in an ad creative, as doing so may lead containers/SDKs to mistakenly inject multiple copies of the MRAID libraries.
244 |
245 | ## _Initialization_
246 | MRAID governs interactions between the ad and the container and identifies the container as compatible with these specifications. Ad designers must include the JavaScript identification reference for MRAID, but the actual JavaScript libraries are supplied by the container, and it is the responsibility of the container to ensure they are available to the ad in a timely fashion after the script reference is made, and to signal as such by firing the ready event.
247 |
248 | The following summarizes step-by-step the actions that the ad and MRAID container take in the initial loading of the ad and the injection of MRAID API libraries.
249 |
250 | 1. Ad identifies itself as MRAID as early as possible by invoking MRAID script tag.``
251 | 2. SDK/MRAID-compatible Container
252 |
253 | a. Optionally detects the script call
254 |
255 | b. Always provides the MRAID JavaScript bridge for MRAID ads
256 |
257 | c. Provides limited MRAID object with an MRAID State = “loading” and the ability to query the state
258 |
259 | 3. If the ad uses createElement, needs to wait for mraid.js to finish loading
260 | 4. If MRAID State=”loading” then ad listens for “ready” event with mraid.addEventListener('ready')
261 | 5. SDK/Container finishes initializing MRAID library into the webview
262 |
263 | a. Changes the MRAID state to “default” and the StateChange Event is triggered
264 |
265 | b. Fires the MRAID “ready” event
266 |
267 | 6. Ad's "ready" event listener is triggered and ad JavaScript can now use the MRAID APIs
268 |
269 | **ready** event
270 |
271 | The ready event triggers when the container is fully loaded, initialized, and ready for any calls from the ad creative.
272 |
273 | It is the responsibility of the MRAID-compliant container to prepare the API methods before the ad creative is loaded. This prevents a condition where the ad cannot register to listen for the ready event because the API methods are unavailable. While the container may load all of MRAID at once, at a minimum the container must be prepared to support the getState and addEventListener capabilities as early as possible in the ad loading process; otherwise there will be no way for the ad to register for the ready event. In the event that the container may still need more time to initialize settings or prepare additional features, ready should only fire when the container is completely prepared for any MRAID request.
274 |
275 | The ad should always attempt to wait for the ready event before executing any rich media operations. Because of timing issues, such as the ready event firing before the ad has registered to listen, ad designers should use the ready event in conjunction with the getState() method.
276 |
277 | Example
278 |
279 | ```
280 | function showMyAd() {
281 | ...
282 | }
283 | if (mraid.getState() === 'loading') {
284 | mraid.addEventListener('ready', showMyAd);
285 | } else {
286 | showMyAd();
287 | }
288 | ```
289 |
290 | “ready”
291 |
292 | parameters:
293 | · none
294 | side effects:
295 | · MRAID JavaScript library available to ad unit
296 | return values:
297 | · none
298 | event triggered:
299 | · none
300 |
301 |
302 | **getVersion** method
303 |
304 | The getVersion method allows the ad to confirm a basic feature set before display. This version number must correspond with the MRAID version specification (e.g., 1.0 or 2.0) and not the vendor’s SDK version.
305 |
306 | getVersion() -> String
307 |
308 | parameters:
309 | · none
310 | return values:
311 | · String – the MRAID version that this SDK is certified against by the IAB, or that this SDK is compliant with. For example, for the current version of MRAID, getVersion() will return “2.0.”
312 |
313 |
314 | ## _Initial Display_
315 | It is up to the ad designer to provide simple HTML, such as an `![]()
` tag, for the initial display of their ad while other assets are loaded in the background. This HTML will be displayed in the Container while JavaScript uses the Controller to request and invoke additional capabilities. Ultimately, the initial HTML display may be completely replaced by a rich media ad once all assets are ready, depending on the creative requirements.
316 |
317 | ## _Event Handling_
318 | Event handling is a key concept of MRAID. Communicating between the web layer and native layer is asynchronous by nature. Through event handling, the ad designer is able to listen for particular events and respond to those events on an as-needed basis. MRAID advocates broadcast-style events to support the broadest range of features/flexibility with the greatest consistency.
319 |
320 | The controller exposes these methods.
321 |
322 | **addEventListener** method
323 |
324 | Use this method to subscribe a specific handler method to a specific event. In this way, multiple listeners can subscribe to a specific event, and a single listener can handle multiple events. An ad may register for more than one listener at a time, and it is required that ads be permitted to do so. The events supported by MRAID v.2 are:
325 |
326 |
327 |
328 | | value |
329 | description |
330 |
331 |
332 | | ready |
333 | report initialize complete |
334 |
335 |
336 | | error |
337 | report error has occurred |
338 |
339 |
340 | | stateChange |
341 | report state changes |
342 |
343 |
344 | | viewableChange |
345 | report viewable changes |
346 |
347 |
348 | | sizeChange |
349 | report a change in size of the ad |
350 |
351 |
352 |
353 | addEventListener(event, listener)
354 |
355 | parameters:
356 | · event – string, name of event to listen for
357 | · listener – function to execute
358 | return values:
359 | · none
360 | side effects:
361 | · none
362 |
363 |
364 | **removeEventListener** method
365 |
366 | Use this method to unsubscribe a specific handler method from a specific event. Event listeners should always be removed when they are no longer useful to avoid errors. If no listener function is specified, then all functions listening to the event will be removed.
367 |
368 | removeEventListener(event, listener)
369 |
370 | parameters:
371 | · event – string, name of event
372 | · listener – function to be removed
373 | return values:
374 | · none
375 | events triggered:
376 | · none
377 |
378 |
379 | ## _Error Handling_
380 | When an error in the container occurs, the "error" event is triggered with diagnostic information about the event. Any number of listeners can monitor for errors of different types and respond as needed.
381 |
382 | **error** event
383 |
384 | This event is triggered whenever a container error occurs. The event contains a description of the error that occurred and, when appropriate, the name of the action that resulted in the error (in the absence of an associated action, the action parameter is null). JavaScript errors remain the full responsibility of the ad designer.
385 |
386 | “error” -> function(message, action)
387 |
388 | parameters:
389 | · message: String, description of the type of error
390 | · action: String, name of action that caused error
391 | triggered by:
392 | · anything that goes wrong
393 |
394 | Ad designers should note that errors can be handled on either a synchronous or an asynchronous basis by the SDK/container.
395 |
396 | While the “message” part of the error event is not defined by the MRAID specification and mainly intended for pre-flight debugging of creative, the “action” part of the error is always the name of the method that the ad tried to use that led to the error. In principle, any MRAID method may trigger an error, so ad designers using an error event listener should listen for the following as potential error actions:
397 |
398 | addEventListener getVersion
399 | createCalendarEvent isViewable
400 | close open
401 | expand playVideo
402 | getCurrentPosition removeEventListener
403 | getDefaultPosition resize
404 | getExpandProperties setExpandProperties
405 | getMaxSize setResizeProperties
406 | getPlacementType storePicture
407 | getResizeProperties supports
408 | getScreenSize useCustomClose
409 | getState
410 |
411 | While any MRAID method may lead to an error, in practice using resize, adding an image to a device’s photo album or adding an event to a calendar are the most likely MRAID methods to generate errors. Ad designers using those methods should be particularly diligent about adding an error listener to check whether an error occurs on a resize, storePhoto, or createCalendarEvent action, so that the ad creative can potentially take a different action.
412 |
413 | ## _Controlling Ad Display_
414 | Besides the initial display, the ad designer may have a number of reasons to control the display.
415 |
416 | * An application may load views in the background to help with latency issues so that an ad is requested, but not visible to the user.
417 | * The ad may expand beyond the default size over the application content.
418 | * The ad may return to the default size once user interaction is complete.
419 |
420 | **getState** method, **stateChange** event
421 |
422 | Each ad container (or Webview) has a state that is one of the following:
423 |
424 |
425 |
426 | | value |
427 | description |
428 |
429 |
430 | | loading |
431 | the container is not yet ready for interactions with the MRAID implementation |
432 |
433 |
434 | | default |
435 | the initial position and size of the ad container as placed by the application and SDK |
436 |
437 |
438 | | expanded |
439 | the ad container has expanded to cover the application content at the top of the view hierarchy |
440 |
441 |
442 | | resized |
443 | the ad container has changed size via MRAID 2.0’s resize() method |
444 |
445 |
446 | | hidden |
447 | the state an interstitial ad transitions to when closed. Where supported, the state a banner ad transitions to when closed |
448 |
449 |
450 |
451 | The getState method returns the current state of the ad container, returning whether the ad container is in its default, fixed position or is in an expanded or resized, larger position, or hidden.
452 |
453 | The stateChange event fires when the state is changed programmatically by the ad or by the environment. This event is triggered when the Ad View changes between default, expanded, resized, and hidden states as the result of an expand(), resize(), or a close(). The container or SDK may also close an ad as the result of a user or system action, such as resuming from background.
454 |
455 | Any MRAID ad can have only one state at a time. In the case of two-part expandable ads, this requirement means there is only one state for both web views. For as long as the expanded view is onscreen, using getState() will return “expanded.”
456 |
457 | The effect on state from calling expand(), resize(), and close() are defined in this table.
458 |
459 | How to read: the initial state of the creative is in the left-most column; how the state changes when an MRAID method is used can be found by looking down the column for that method. So for example, if the ad’s state is “expanded” and the close() method is used, the ad’s state changes to “default.”
460 |
461 |
462 |
463 | | Initial state |
464 | expand() |
465 | resize() |
466 | close() |
467 |
468 |
469 | | loading |
470 | no effect |
471 | no effect |
472 | no effect |
473 |
474 |
475 | | default |
476 | For a banner, state changed to “expanded” For an interstitial, no effect |
477 | For a banner, state changed to “resized” For an interstitial, no effect |
478 | For a banner, state changed to “hidden” (if supported by SDK/container) For an interstitial, state changed to “hidden” |
479 |
480 |
481 | | expanded |
482 | no effect (state remains “expanded”) |
483 | triggers an error; state remains “expanded” |
484 | state changed to “default” |
485 |
486 |
487 | | resized |
488 | state changed to “expanded” |
489 | state changed to “resized” (that is, an event listener will hear a new stateChange event, even though the state is still “resized” after the event fires) |
490 | state changed to “default” |
491 |
492 |
493 | | hidden |
494 | no effect |
495 | no effect |
496 | no effect |
497 |
498 |
499 |
500 | In the case of a two-piece expandable, the new, expanded web view starts in the “loading” state briefly until MRAID is available, upon which the “ready” event is fired and the state of the ad then transitions to “expanded.” The banner (the first piece) of the two-piece ad also changes its state, from “default” to “expanded.”
501 |
502 | For an interstitial ad, the web view goes from “loading” to “default,” and when the interstitial is closed, the state changes to “hidden.”
503 |
504 | getState() -> String
505 |
506 | parameters:
507 | · none
508 | return values:
509 | · String: "loading", "default", "expanded”, “resized,” or “hidden”
510 | related events:
511 | · stateChange
512 |
513 |
514 | “stateChange” -> function(state)
515 |
516 | parameters:
517 | · state - String, either "loading", "default", "expanded", “resized”, or “hidden”
518 | triggered by:
519 | · expand, resize, close, or the app
520 |
521 |
522 | **getPlacementType()** method
523 |
524 | For efficiency, ad designers sometimes flight a single piece of creative in both banner and interstitial placements. So that the creative can be aware of its placement, and therefore potentially behave differently, each ad container has a placement type determining whether the ad is being displayed inline with content (i.e. a banner) or as an interstitial overlaid content (e.g. during a content transition). The container returns the value of the placement to creative so that creative can behave differently as necessary. The container does not determine whether a banner is an expandable (the creative does) and thus does not return a separate type for expandable.
525 |
526 |
527 |
528 | | value |
529 | description |
530 |
531 |
532 | | inline |
533 | the default ad placement is inline with content in the display (i.e. a banner) |
534 |
535 |
536 | | interstitial |
537 | the ad placement is over laid on top of content |
538 |
539 |
540 |
541 | getPlacementType should always return the placement that it initially displayed in.That is, in the case of two-part expandables, the second, expanded part should also see “inline” if it does a getPlacementType.
542 |
543 | getPlacementType() -> String
544 |
545 | parameters:
546 | · none
547 | return values:
548 | · String: "inline", "interstitial"
549 | related events:
550 | · none
551 |
552 |
553 | **isViewable** method, **viewableChange** event
554 |
555 | In addition to the state of the ad container, it is possible that the container is loaded off-screen as part of an application's buffer to help provide a smooth user experience. This is especially prevalent in apps that employ scrolling views or in interstitial ads, for example between levels of a game.
556 |
557 | The isViewable method returns whether the ad container is currently on or off the screen. The viewableChange event fires when the ad moves from on-screen to off-screen and vice versa. For a two-piece expandable ad, when the ad state is expanded, isViewable will return an answer based on the viewability of the expanded piece of the ad.
558 |
559 | In any situation where an ad may be loaded offscreen, it is a good practice for the ad to check on its viewable state and/or register for viewableChange before taking any action.
560 |
561 | Note that MRAID does not define a minimum threshold percentage or number of pixels of the ad that must be onscreen to constitute “viewable.”(The IAB currently has a project underway to establish guidelines for in-app ad measurement, potentially including a viewability threshold, is currently underway within the IAB.)
562 |
563 | isViewable() -> boolean
564 |
565 | parameters:
566 | · none
567 | return values:
568 | · boolean -
569 | true: container is on-screen and viewable by the user;
570 | false: container is off-screen and not viewable
571 | related events:
572 | · viewableChange
573 |
574 |
575 | “viewableChange” -> function(boolean)
576 |
577 | parameters:
578 | · boolean -
579 | true: container is on-screen and viewable by the user;
580 | false: container is off-screen and not viewable
581 | triggered by:
582 | · a change in the application view controller
583 |
584 |
585 | Below is an example of an ad that takes into account both “Ready” and “isViewable” before taking action.
586 |
587 | ```
588 | // Wait for the SDK to become ready
589 | if (mraid.getState() === 'loading') {
590 | mraid.addEventListener('ready', onSdkReady);
591 | } else {
592 | onSdkReady();
593 | }
594 |
595 | function onSdkReady() {
596 | // Wait for the ad to become viewable for the first time
597 | if (mraid.isViewable()) {
598 | showMyAd();
599 | } else {
600 | mraid.addEventListener('viewableChange',function(viewable) {
601 | if (viewable) {
602 | mraid.removeEventListener('viewableChange', arguments.callee);
603 | showMyAd();
604 | }
605 | });
606 | }
607 | }
608 |
609 | function showMyAd() {
610 | ...
611 | }
612 | ```
613 |
614 | ## _Changing the Size of an Ad_
615 |
616 | MRAID v2 includes three distinct ways for an ad to change its size. By far the simplest is to use the open() method, which is intended for click-throughs where an entire web site is loaded in a new browser window (generally this will be a browser running within the app, but it may be the device’s native browser).
617 |
618 | The expand() method is intended for ads that expand in a fairly simple, straightforward way to cover the content of the application.
619 |
620 | In addition to these, the resize() method is intended for ads that grow or shrink in more subtle ways, in a dialogue with the app in which it is running. This method allows designers complete freedom and control – with the trade-off that additional methods and listeners are required for both the ad creative and the app/container to react appropriately in different placements.
621 |
622 | ### Differences between resize(), expand(), and open()
623 |
624 | Although these methods are related, they promote an approach of progressive complexity. That is, simple operations should be simple, but sophisticated efforts are still be possible. Understanding the distinction between resize(), expand() and open() helps ad designers choose the best method for their needs.
625 |
626 | open()
627 |
628 | * lowest common denominator
629 | * used for advertiser landing pages or microsites
630 | * opens a new URL, generally in a browser window within the app, however may open in the device’s native browser
631 | * always full screen
632 | * no additional properties
633 |
634 | expand()
635 |
636 | * simple interface
637 | * maintains ad experience
638 | * full screen
639 | * few additional properties
640 | * support for one-part or two-part creatives
641 | * MRAID-enforced tap-to-close area in fixed (top right) location
642 | * relative alignment for creatives
643 |
644 | resize()
645 |
646 | * flexible interface
647 | * continuous, non-modal ad experience
648 | * no default values, can change to larger or smaller sizes
649 | * additional properties and methods required
650 | * one-part creatives only
651 | * MRAID-enforced tap-to-close area, but ad designer can change the close area’s position within the creative area.
652 | * absolute positioning possible
653 | * supports direction of resizing
654 |
655 | This table summarizes the differences between these methods.
656 |
657 |
658 |
659 | | property |
660 | open() |
661 | expand() |
662 | resize() |
663 |
664 |
665 | | modal |
666 | Y |
667 | Y |
668 | N |
669 |
670 |
671 | | MRAID-enforced close control |
672 | N |
673 | Y |
674 | Y |
675 |
676 |
677 | | viewer stays within ad experience |
678 | N |
679 | Y |
680 | Y |
681 |
682 |
683 | | two-part creatives |
684 | n/a |
685 | Y |
686 | N |
687 |
688 |
689 | | one-part creatives |
690 | n/a |
691 | Y |
692 | Y |
693 |
694 |
695 | | aligned to screen |
696 | n/a |
697 | Y |
698 | N |
699 |
700 |
701 | | background provided for small creatives |
702 | n/a |
703 | Y |
704 | N |
705 |
706 |
707 | | size up |
708 | n/a |
709 | Y |
710 | Y |
711 |
712 |
713 | | size down |
714 | n/a |
715 | N |
716 | Y |
717 |
718 |
719 | | app-defined max area |
720 | n/a |
721 | N |
722 | Y |
723 |
724 |
725 | | callback required to complete |
726 | n/a |
727 | N |
728 | Y |
729 |
730 |
731 | | supports directionality |
732 | n/a |
733 | N |
734 | Y |
735 |
736 |
737 | | creative can control position of resized ad |
738 | n/a |
739 | N |
740 | Y |
741 |
742 |
743 | | app can return to default state |
744 | n/a |
745 | N |
746 | Y |
747 |
748 |
749 |
750 | In MRAID 2.0 the creation of partial-screen non-modal expansions requires using the resize() method. The deprecation of the expand property “isModal” is reflected in this usage chart. Under MRAID 2.0, calling expand() using expanded creative that is smaller than the size of the full screen requires the container web view blank out, cover, or otherwise obscure the underlying app to make it very clear to the end user that the expanded ad is modal in nature. In that sense, modal, partial screen ads are not allowed in MRAID 2.0.
751 |
752 |
753 |
754 | |
755 | Modal |
756 | Non-modal |
757 |
758 |
759 | | Full Screen |
760 | OK - Use expand() |
761 | Not possible |
762 |
763 |
764 | | Partial Screen |
765 | Not possible |
766 | OK - Use resize() |
767 |
768 |
769 |
770 | ## _Open: Open an External Mobile Web Site in a Browser Window_
771 |
772 | If the ad needs to open an external mobile web site, or micro site, from an MRAID ad, it can call the open method which will open a browser window to view the external HTML content. Wherever possible, this will be via an embedded browser in the application.
773 |
774 | **open** method
775 |
776 | The open method will display an embedded browser window in the application that loads an external URL. On device platforms that do not allow an embedded browser, the open method invokes the native browser with the external URL.
777 |
778 | _Note: This should be used only for external web pages that are not MRAID ads. The displayed page will not load the app’s MRAID-compliant SDK and so the close method will not have any effect on the embedded browser. It can only be closed by the user selecting the close control for the window, which is implementation specific._
779 |
780 | Use this method to open an HTML browser to an external web page. This may launch an external browser, depending on the implementation. To remain within an MRAID ad experience, use the expand() method instead.
781 |
782 | The native browser controls – back, forward, refresh, close – will always be present. For reporting, open() may be used by SDK vendors as a reportable event.
783 |
784 | open(URL)
785 |
786 | parameters:
787 | · URL - String, the URL of the web page
788 | return values:
789 | · None
790 |
791 |
792 | ## _Hyperlinks_
793 |
794 | When the user clicks on an HTML hyperlink (defined by an `` tag) in an MRAID ad, there are two possibilities: the linked page could load in the existing ad web view, or the content could open a separate browser window and load the indicated HTML link there. MRAID-compliant SDKs can opt for either strategy, so ad designers should avoid using inline hyperlinks and window.location changes. mraid.open() is the appropriate and correct way for an MRAID ad to specify that a link should open a page in a separate browser. Loading a new web page in the ad view that is not written to the MRAID spec can leave the ad, and possibly the app, in an unusable state.
795 |
796 | ## _Handling Call-to-Action Events_
797 |
798 | A rich media ad implements multiple call-to-action events beyond the tap to microsite. These events may be executed as anchor links or scripted functions. This means a container or SDK cannot just listen for taps in the browser. It must support programmatic taps/clicks (e.g., window.location changes) as well.
799 |
800 | ## _Expand: Simple, Modal, Increase in Size of the Ad_
801 |
802 | For ad creative that changes size in a relatively simple manner, typically expanding from banner to full-screen size, the expand method provides a simple way to communicate this to the container.
803 |
804 | **expand** method
805 |
806 | The expand method will cause an existing web view (for one-part creatives) or a new web view (for two-part creatives) to open at the highest level (e.g., at a higher z-index value than any app content) in the view hierarchy. The expanded view can either contain a new HTML document if a URL is specified, or it can reuse the same document that was in the default position. While an ad is in an expanded state, the default position will generally be obscured or inaccessible to the viewer, so the default position should take no action while the expanded state is available. Thus a complete implementation allows for ad designers to use one-part ads (where the banner and panel are part of one creative) and two-part ads (where the banner and panel are separate HTML creatives).
807 |
808 | The expand method may change the size of the ad container, and will move state from "default" or “resized” to "expanded" and fire the stateChange event. In the case of both one-piece ads and two-piece ads, calling expand() multiple times will be ignored, and multiple expand calls have no effect on state (which remains “expanded”).
809 |
810 | An expanded view must cover all available screen area even though the ad creative may not (e.g. via a transparent or opaque overlay). The expanded ad is always modal, and naturally the container should prevent new ads from loading during the expand state so that the user can complete any desired interactions with the ad creative without interruption. Other application-specific difficulties such as poorly built apps with multiple window objects, or timers that change the content z-order, must be considered by vendors when implementing the expand method.
811 |
812 | An expanded view must provide an end-user with the ability to close the expanded creative. These requirements are discussed further in the description of closing expandable and interstitial ads, below.
813 |
814 | Placement of the expanded ad on screen, especially when the expanded view can be placed in multiple locations, is left to the ad designer. For full-screen expands, all MRAID compliant SDKs will grant the full device screen space and will position the ad so it is fully visible.
815 |
816 | When the ad size is greater or smaller than the screen size of the device, the SDK will size the web view to be identical to the maximum size allowed by the device and app. The creative will not be scaled down or up to the size of the device’s screen; rather it will be up to the ad creative to position itself appropriately within the expanded web view via CSS.
817 |
818 | 
819 |
820 | When the expand method is called without the URL parameter, the current view will be reused, simplifying reporting and ad creation. The original creative is not reloaded and no additional impressions are recorded. Implementing this definition allows for one-part creatives.
821 |
822 | When the expand method is called with the URL parameter, a new view will be used. Implementing this definition allows for two-part creatives. When a two-part expandable is used, the second part (pointed to by the URL) must always be a complete HTML page (not a snippet/fragment), and must separately request mraid.js from the SDK/container (assuming it needs MRAID). Whether the expanded part of the ad requests mraid.js or not, the container will always supply the close control and (optionally, depending on how expandProperties are set) the close indicator.
823 |
824 | expand([URL])
825 |
826 | parameters:
827 | · URL (optional): The URL for the document to be displayed in a new overlay view. If null or a non-URL parameter is used, the body of the current ad will be used in the current webview.
828 | return values:
829 | · none
830 | events triggered:
831 | stateChange
832 |
833 |
834 | ## _Controlling Expand Properties_
835 | The expand properties object is intended to provide additional features to ad designers. Expand properties that can be set by the ad designer are limited to the width and height of the ad creative, and whether the creative is supplying its own close indicator. The expandProperties are held in a JavaScript object that can be written and read by the ad. Ad designers can also control the orientation of an expandable ad via orientation properties, set separately.
836 |
837 | Expand properties can only be set BEFORE the ad calls expand(). Changes after the ad is in its expanded state will be ignored.
838 |
839 | ```
840 | expandProperties object = {
841 | “width” : integer,
842 | “height” : integer,
843 | “useCustomClose” : boolean,
844 | “isModal” : boolean (read only)
845 | }
846 | ```
847 |
848 | properties:
849 |
850 | * width : integer – width of creative, default is full screen width.
851 | * height : integer – height of creative, default is full screen height. Note that when getting the expand properties before setting them, the values for width and height will reflect the actual values of the screen. This will allow ad designers who want to use application or device values to adjust as necessary.
852 | * useCustomClose : boolean – true, container will stop showing default close graphic and rely on ad creative’s custom close indicator; false (default), container will display the default close graphic. This property has exactly the same function as the useCustomClose method (described below), and is provided as a convenience for creators of expandable ads.
853 | * isModal : boolean – true, the container is modal for the expanded ad; false, the container is not modal for the expanded ad; this property is read-only and cannot be set by the ad designer. Note that while this could be false in MRAID 1.0, in MRAID v2.0 will always return “true.”
854 |
855 | **getExpandProperties** method
856 |
857 | The getExpandProperties method returns the whole JavaScript Object expandProperties object.
858 |
859 | Use this method to get the properties for expanding an ad.
860 |
861 | getExpandProperties() -> JavaScript Object
862 |
863 | parameters:
864 | · none
865 | return values:
866 | · { ... } - this object contains the expand properties
867 | events triggered:
868 | · none
869 |
870 |
871 | **setExpandProperties** method
872 |
873 | The setExpandProperties method sets the whole JavaScript object.
874 |
875 | setExpandProperties(properties)
876 |
877 | Use this method to set the ad's expand properties, including the maximum width and height of the ad creative.
878 |
879 |
880 | parameters:
881 | · properties: JavaScript Object { ... } - this object contains the width and height of the expanded ad. For more info see properties object.
882 | return values:
883 | · none
884 | events triggered:
885 | · none
886 |
887 |
888 | ## _Controlling Orientation Properties_
889 | The orientation properties object is intended to provide ad designers with additional control over expandable and interstitial ads. The orientationProperties are held in a JavaScript object that can be written and read by the ad. The orientationProperties object only affects the expanded state of an expandable ad, or an interstitial ad. A banner in its default state cannot use orientationProperties to prevent the app from reorienting or force the app to switch to a different orientation layout. Resizeable ads can use orientationproperties, but they won’t have any effect.
890 |
891 | ```
892 | orientationProperties object = {
893 | "allowOrientationChange" : boolean,
894 | "forceOrientation" : "portrait|landscape|none"
895 | }
896 | ```
897 |
898 | * allowOrientationChange : boolean -- If set to “true” then the container will permit device-based orientation changes; if set to false, then the container will ignore device-based orientation changes (e.g., the web view will not change even if the orientation of the device changes). Default is “true.” The ad creative is always able to request a change of its orientation by setting the forceOrientation variable, regardless of how allowOrientationChange is set.
899 | * forceOrientation : string – can be set to a value of “portrait,” landscape,” or “none.” If forceOrientation is set then a view must open in the specified orientation, regardless of the orientation of the device. That is, if a user is viewing an ad in landscape mode, and taps to expand it, if the ad designer has set the forceOrientation orientation property to “portrait” then the ad will open in portrait orientation. Default is “none.”
900 |
901 | To enable finer control over ad behavior, an ad designer can change the setting of either of the orientation properties after the ad is in an expanded state. This way an ad may start in portrait but instruct the user to change orientation to play a game. The game requires tilting so no orientation changes should be allowed until the user is done. MRAID-compliant SDKs must be able to accept changes to orientation properties throughout a user’s interaction with an expandable ad.
902 |
903 | For example:
904 |
905 | ```
906 | mraid.setOrientationProperties ( {"allowOrientationChange":true} );
907 | mraid.expand()
908 | /* user changes to landscape, starts game */
909 | mraid.setOrientationProperties ( {"allowOrientationChange": false } );
910 | /* user is done with game */
911 | mraid.setOrientationProperties ( {"allowOrientationChange":true} );
912 | ```
913 |
914 | **getOrientationProperties** method
915 |
916 | The getOrientationProperties method returns the whole JavaScript object orientationProperties object.
917 |
918 | Use this method to get the properties for the orientation of the expanded part of an expandable, or an interstitial ad.
919 |
920 | getOrientationProperties() -> JavaScript Object
921 |
922 | parameters:
923 | · none
924 | return values:
925 | · { ... } - this object contains the orientation properties
926 | events triggered:
927 | · none
928 |
929 |
930 | **setOrientationProperties** method
931 |
932 | The setOrientationProperties method sets the JavaScript orientationProperties object.
933 |
934 | setOrientationProperties(properties)
935 |
936 | Use this method to set the ad's orientation properties.
937 |
938 |
939 | parameters:
940 | · properties: JavaScript Object { ... } - this object contains the values for allowOrientationChange and forceOrientation.
941 | return values:
942 | · none
943 | events triggered:
944 | · none
945 |
946 |
947 | ## _Closing Expandable and Interstitial Ads_
948 |
949 | An MRAID-compliant SDK must provide an end-user with the ability to close an expanded or interstitial ad. This is a requirement to ensure that users are always able to return to the publisher content even if an ad has an error. The ad designer may optionally provide additional design elements to close the expanded or interstitial view via the close() method, described below. MRAID differentiates two aspects to a “close” feature:
950 |
951 | * Close Event Region: The close event region is a tappable area on the ad creative that will cause the ad to close and return to its default state. The close event region is required and supplied by the container in the top-right corner of all MRAID expandable and interstitial ads.
952 | * Close Indicator: The close indicator is the visual cue to the user as to the location of the close event region. By default the container will supply a close indicator superimposed on the close event region. Optionally, the creative designer can use their own close indicator graphic, in which case they can suppress the default close indicator.
953 |
954 | MRAID requires the location reserved for the close event region be a 50x50 clickable area in the top-right corner of the ad container. Reserving this location provides consistency for ad designers running campaigns across apps and rich media vendors. The default design of the container-controlled close indicator is left to the vendor/app publisher. Ad designers may optionally choose to provide the indicator for the default close capability.If the ad designer builds the close indicator into the creative they must specify so via the useCustomClose() method, or as a convenience by setting useCustomClose in the expandProperties() object. If the ad designer does not provide its own close indicator graphic within the creative, the container will supply its default close indicator. This container-supplied tappable area will be placed at a higher level than other app or ad content, and must always be available to the end user.
955 |
956 | **For Two-Part Ads:** If expand was used with a URL parameter (e.g., a two-part ad), then closing the ad must display the original content. If the app was suspended when the ad changed to the expand state, then the app should be notified of the expansion status change.
957 |
958 | **For One-Part Ads:** If the expanded or interstitial ad view was closed using the container-supplied close event region, then the stateChange event is still fired and the app still notified of the expansion status change. Expanded ads must always listen for the stateChange event and adjust as necessary.
959 |
960 | **close** method
961 |
962 | The close method will cause the ad container to downgrade its state. For ads in an expanded or resized state, the close() method moves the ad to a default state. For interstitial ads in a default state, the close() method moves to a hidden state. For banners in a default state, the effect of calling close() is deliberately left undefined by the MRAID specification. Depending on the implementation, it may be ignored, cause an error, or change the state of the banner to “hidden.” As a result it is generally not recommended that ad designers use mraid.close() in a banner. This method may be used by ad designers as an addition to the MRAID-enforced close ability. It will also fire the stateChange event.
963 |
964 | Note that if an ad employs multiple resize() calls or a resize() followed by an expand(), close() changes the creative back to its default, banner state. It does NOT simply undo the most recently called resize() or expand().
965 |
966 | close()
967 |
968 | parameters:
969 | · none
970 | return values:
971 | · none
972 | event triggered:
973 | · stateChange
974 |
975 |
976 | **useCustomClose** method
977 |
978 | Although MRAID requires all implementing containers to provide a clickable area with a default “close” indicator graphic, it is possible for ad creators to use their own designs for the close indicator.
979 |
980 | This method serves as a convenience method to the expand property of the same name. Setting the property or calling this method both have the same effect and can be used interchangeably. If an ad sets useCustomClose via both expand properties AND this method, whichever is invoked later will override the earlier setting. They signal the container to stop using the default close indicator.
981 |
982 | For expanded ads, the designer does not need to call this method and would normally set the useCustomClose property in setExpandProperties().
983 |
984 | For a stand-alone interstitial where there is no call to expand(), but there is still a requirement of an MRAID-enforced close control, the ad designer should call this method immediately after the Ready event.
985 |
986 | Ad designers should be clear that an MRAID-compliant SDK is required to show the default close indicator until the useCustomClose method is called and/or the property is set.
987 |
988 | useCustomClose(boolean)
989 |
990 | parameters:
991 | · true – ad creative supplies its own design for the close indicator
992 | · false – container default image should be displayed for the close indicator
993 | return values:
994 | · none
995 | events triggered:
996 | · none
997 |
998 |
999 | ## _Resize: Enables Sophisticated Ad Size Changes_
1000 |
1001 | Ad creative that needs to engage in a succession of size changes, or to change size non-modally to less-than-fullscreen size, has the ability to do so by calling resize. As with expand, the resize method operates at a higher z-index than the app content, and so is positioned above the underlying content, and so does not push or reposition the app content.
1002 |
1003 | **resize** method
1004 |
1005 | The resize method will cause the existing web view to change size using the existing HTML document. Like expand(), resize() size changes happen at highest level in the view hierarchy, and so do not automatically shift or otherwise reposition underlying content. App publishers that want to support content-shifting ads like “push-downs” can do so using resize but must implement the repositioning of app content in response to the resize independently.
1006 |
1007 | The resize method will move the state from "default" to "resized" and fire the stateChange event. Resize can be called multiple times by the creative. Additional calls to resize will also trigger the stateChanged event although the state value will remain “resized.” Calls to resize from an “expanded” state will trigger an error event and not change the state.
1008 |
1009 | _Note: resize should not be used for ad creative that expands to full-screen (or larger) size: for such creative executions expand() should always be used. Resize will always result in a non-modal size change, and some portion of the app should always remain visible to the end user._
1010 |
1011 | Use this method to request a resize of the default ad view to a desired size and screen position. Note that resize() relies on parameters that are stored in the resizeProperties JavaScript object. Thus the creative must set those parameters via the setResizeProperties() method BEFORE attempting to resize(). Calling resize() before setResizeProperties will result in an error.
1012 |
1013 | The container will notify the app of the resize request so that the app can react to the change as appropriate. For example, a publisher integration may listen for resize() calls to implement behavior like a “push-down” ad. If the resize is valid, then the sizeChange event is fired. If the parameters are out of range, then the error event identifies the exception.
1014 |
1015 | resize()
1016 |
1017 | parameters:
1018 | · none
1019 | return values:
1020 | · none
1021 | events triggered:
1022 | · sizeChange, stateChange
1023 | side effects:
1024 | · changes state
1025 |
1026 |
1027 | **Close Control for Resized Ads**
1028 |
1029 | As with expandable ads, resized ads must have a way for the person viewing the ad to return the ad to its default state. MRAID differentiates two aspects to a “close” feature:
1030 |
1031 | * Close event region: The close event region is a tappable area on the ad creative that will cause the ad to close/collapse back to its default state. The close event region is required and supplied by the container in a creative-specified location for all MRAID resizable ads.
1032 | * Close Indicator: The close indicator is the visual cue to the user as to the location of the close event region. For resized ads, the container does NOT supply a close indicator superimposed on the close event region. Instead, FOR RESIZED ADS, THE CREATIVE MUST ALWAYS SUPPLY ITS OWN CLOSE INDICATOR GRAPHIC.
1033 |
1034 | MRAID-compliant SDKs must therefore always supply containers with a 50x50 close event region located on the ad creative, tapping on which will return the ad to its default state. While this close event region must be present, the ad designer can specify where on the ad the control should be located. If the ad designer opts not to specify a location for the close event region then by default the container will position it at the top right corner of the resized ad container.
1035 |
1036 | A resized ad must position itself such that the entire close event region appears onscreen. If the container/SDK detects that a request to resize will result in the close event region being offscreen, the container/SDK should return an error, and ignore the resize (e.g., leave the ad in its current state). This requirement also means that a resized ad must be at least 50x50 pixels, to ensure there is room on the resized creative for the close event region.
1037 |
1038 | Unlike the case of expand(), for resize() the container will not supply a close indicator.Rather, it is expected that the ad designer will include a close indicator in the creative.
1039 |
1040 | While the tappable close control is mandatory, ad designers are free to include other ways to close a resized ad, by using MRAID’s close() method.
1041 |
1042 | **resizeProperties** object
1043 |
1044 | ```
1045 | resizeProperties object = {
1046 | “width” : integer,
1047 | “height” : integer,
1048 | “offsetX” : integer,
1049 | “offsetY” : integer,
1050 | “customClosePosition” : string,
1051 | “allowOffscreen” : boolean
1052 | }
1053 | ```
1054 |
1055 | Notes:
1056 |
1057 | * width : (required) integer – width of creative in pixels
1058 | * height : (required) integer – height of creative in pixels
1059 | * offsetX: (required) is the horizontal delta from the banner's upper left-hand corner where the upper left-hand corner of the expanded region should be placed; positive integers for expand right; negative for left
1060 | * offsetY: (required) is the vertical delta from the banner's upper left-hand corner where the upper left-hand corner of the expanded region should be placed; positive integers for expand down; negative for up
1061 | * customClosePosition: (optional) string – either "top-left", "top-right", "center", "bottom-left", "bottom-right," “top-center,” or “bottom-center” indicates the origin of the container-supplied close event region relative to the resized creative. If not specified or not one of these options, will **default to top-right**.
1062 | * allowOffscreen: (optional) tells the container whether or not it should allow the resized creative to be drawn fully/partially offscreen
1063 | * **True (default)**: the container should not attempt to position the resized creative
1064 | * False: the container should try to reposition the resized creative to always fit in the getMaxSize() area
1065 |
1066 | When allowOffscreen is set to False, the SDK will do its best to move the default (banner) ad container to ensure that the resized creative fits on the screen. For example, if ad is on the top of the screen, and ad wants to resize upwards by 50 pixels, then the SDK will move the default (banner) ad 50 pixels down and then execute the resize. If allowOffscreen is set to true in this case, the resized portion of the ad will extend off the top of the screen.
1067 |
1068 | allowOffscreen cannot solve all positioning issues. For example, if an ad successfully resizes in landscape orientation, but then becomes larger than the size of the screen due to an orientation change to portrait, the setting of allowOffscreen to false will have no effect, as there is no way the container/SDK can successfully reposition a landscape creative to fit on a portrait screen.
1069 |
1070 | Note that width, height, offsetX and offsetY are required and have no default properties. If the ad creative attempts to call resize() before setting these four properties, the container will leave the ad in its current state and return an error.
1071 |
1072 | **getResizeProperties** method
1073 |
1074 | The getResizeProperties method returns the whole JavaScript object resizeProperties object.
1075 |
1076 | Use this method to get the properties for resizing an ad.
1077 |
1078 | getResizeProperties() -> JavaScript Object
1079 |
1080 | parameters:
1081 | · none
1082 | return values:
1083 | · { ... } - this object contains the resize properties
1084 | events triggered:
1085 | · none
1086 |
1087 |
1088 | **setResizeProperties** method
1089 |
1090 | Use this method to set the ad's resize properties, in particular the width and height of the resized ad creative.
1091 |
1092 | parameters:
1093 | · properties: JavaScript Object { ... } - this object contains the width and height of the resized ad, close position, offset direction (all in density-independent pixels), and whether the ad can resize offscreen. For more info see properties object.
1094 | return values:
1095 | · none
1096 | events triggered:
1097 | · none
1098 |
1099 |
1100 | Resize ads should be QA tested carefully. Ads that set parameters that are impossible for the container to follow will result in an error event being triggered and the resize will not take place. For example, an error will occur if an ad sets allowOffscreen to “false” but sets the width and height of the resize to be too big to actually fit on the screen.
1101 |
1102 | ## _Checking Position and Size of the Screen and Ad_
1103 |
1104 | MRAID v2.0 includes several methods enabling an ad to check where and how large it is, and the maximum size it can expand to. Ad designers can use these capabilities to give their ads increased flexibility to behave differently on different devices and/or differently sized screens.
1105 |
1106 | **getCurrentPosition** method
1107 |
1108 | The getCurrentPosition method will return the current position and size of the ad view, measured in density-independent pixels.
1109 |
1110 | getCurrentPosition() -> JavaScript Object
1111 |
1112 | parameters:
1113 | · none
1114 | return value:
1115 | · JavaScript Object - {x, y, width, height}:
1116 | x=number of density-independent pixels offset from left edge of the rectangle defining getMaxSize();
1117 | y=number of density-independent pixels offset from top of the rectangle defining getMaxSize();
1118 | width=current width of container;
1119 | height=current height of container (both measured in density-independent pixels)
1120 | related events:
1121 | · none
1122 |
1123 |
1124 | **getMaxSize** method
1125 |
1126 | The getMaxSize method returns the maximum size (in density-independent pixel width and height) an ad can expand or resize to. If the app runs full-screen on the device (e.g., covers the status bar), the max size will be the full screen dimensions. If the app runs at less than full screen on the device, due to screen area reserved for a status bar or other elements outside the app, then the max size will return the size of the view that contains the app (which defines the maximum space the ad may resize within).
1127 |
1128 | getMaxSize() -> JavaScript Object
1129 |
1130 | parameters:
1131 | · none
1132 | return value:
1133 | · JavaScript Object, {width, height} - the maximum width and height the view can grow to
1134 | related events:
1135 | · none
1136 |
1137 |
1138 | **sizeChange** event
1139 |
1140 | The sizeChange event fires when the ad’s size within the app UI changes. This can be the result of an orientation change of the device or calls to the resize or expand methods. Measurements are in density-independent pixels.
1141 |
1142 | This event is triggered when the display state of the ad’s web view changes.
1143 |
1144 | sizeChange -> function(width, height)
1145 |
1146 | parameters:
1147 | · width - Number: the width of the view
1148 | · height - Number: the height of the view
1149 | triggered by:
1150 | · a change in the view size as the result of a resize, expand, close, orientation, or the app after registering a "size" event listener.
1151 |
1152 |
1153 | **getDefaultPosition** method
1154 |
1155 | The getDefaultPosition method returns the position and size of the default ad view, measured in density-independent pixels, regardless of what state the calling view is in.
1156 |
1157 | Use this method to get the location and size of the default ad view.
1158 |
1159 | getDefaultPosition() -> JavaScript Object
1160 |
1161 | parameters:
1162 | · none
1163 | return values:
1164 | · JavaScript Object - {x, y, width, height}:
1165 | x=number of density-independent pixels offset from left of getMaxSize();
1166 | y=number of density-independent pixels offset from top of getMaxSize();
1167 | width=current width of container;
1168 | height=current height of container
1169 |
1170 |
1171 | **getScreenSize** method
1172 |
1173 | The getScreenSize method returns the current actual pixel width and height, based on the current orientation, in density-independent pixels, of the device on which the ad is running. Note that the ScreenSize will change if the device is turned from portrait to landscape mode (and vice versa). Note also that getScreenSize will return the TOTAL size of the device screen, including area (if any) reserved by the OS for status/system bars or other functions, which cannot be overridden by the app or the ad. Designers seeking to enable creative to check how much usable screen real estate is available should use getMaxSize rather than getScreenSize.
1174 |
1175 | getScreenSize() -> JavaScript Object
1176 |
1177 | parameters:
1178 | · none
1179 | return values:
1180 | · {width, height}
1181 | related event:
1182 |
1183 |
1184 | ## _Offline Requests and Metrics_
1185 |
1186 | Rich Media Ads that can work while the device is without network connectivity need the ability to store and later forward metrics about how and when users interact with the ad.
1187 |
1188 | MRAID has the potential to provide common APIs to facilitate storing and forwarding of ad impression delivery, view, and other metrics from the app back to the ad server. However, until measurement methodologies and the metrics themselves are standardized (for example by the ongoing IAB/MMA/MRC In-App Ad Measurement Guidelines project), adding measurement functionality to MRAID would be premature.
1189 |
1190 | The MRAID working group expects that this capability will be evaluated and potentially added to MRAID as part of a future release.
1191 |
1192 | ## _Access to Native Features_
1193 |
1194 | MRAID encourages the use of standard web technologies in ad design as much as possible for presentation needs, basic functions, and even an increasing list of the advanced ad functionalities required for truly rich media advertising. MRAID’s role around access to native features is to help rich media ads discover what capabilities a device will support, and to fill in any gaps in capability not widely available, or not fully stabilized and consistent, within HTML5/Webkit.
1195 |
1196 | **supports** method
1197 |
1198 | The supports method allows the ad to interrogate the device for support of specific features.
1199 |
1200 | An MRAID compliant SDK must be able to deliver all of these functionalities on any device that is capable of them. However, individual publisher implementations of the SDK may result in deactivating features/capabilities that conflict with publisher policies.
1201 |
1202 |
1203 |
1204 | | value |
1205 | description |
1206 |
1207 |
1208 | | sms |
1209 | the device supports using the sms: protocol to send an SMS message |
1210 |
1211 |
1212 | | tel |
1213 | the device supports initiating calls using the tel: protocol |
1214 |
1215 |
1216 | | calendar |
1217 | the device can create a calendar entry |
1218 |
1219 |
1220 | | storePicture |
1221 | the device supports the MRAID storePicture method |
1222 |
1223 |
1224 | | inlineVideo |
1225 | The device can playback HTML5 video files using the |
1226 |
1227 |
1228 |
1229 | supports(feature) -> Boolean
1230 |
1231 |
1232 | parameters:
1233 | · String, name of feature
1234 | return values:
1235 | · Boolean –
1236 | true, the feature is supported and getter and events are available;
1237 | false, the feature is not supported on this device
1238 |
1239 |
1240 | ## _Working with the Device's Physical Characteristics_
1241 |
1242 | Most devices have several different kinds of sensors that can report on various physical characteristics of the device, such as its location, the direction it is pointing, its orientation, and its motion. Access to most of these capabilities is standardized in HTML5 at present (or will be in the near future), and where an open standard provides access to a device feature or capability, MRAID defers to the open standard.
1243 |
1244 | **Device Orientation**
1245 |
1246 | Ad creative should be able to request the orientation of a device/web container via HTML5 with consistent results across devices and MRAID implementations. For Android implementations and iOS versions after 5.0 this happens automatically; however, earlier iOS implementations require a code tweak on the part of the SDK vendor in order to window orientation changes fire events properly.
1247 |
1248 | To be compliant with MRAID 2.0, an SDK needs to deploy a code modification of this sort for pre-iOS 5.0 Apple devices. While SDK vendors can use whatever technical solution they prefer to achieve this, the following sample code offers an example of a means to address this issue.
1249 |
1250 | ```
1251 | (void)didRotateFromInterfaceOrientation:(UIInterfaceOrientation) fromInterfaceOrientation {
1252 |
1253 | if (UIInterfaceOrientationIsPortrait(newOrientation) ||
1254 | UIInterfaceOrientationIsLandscape(newOrientation)) {
1255 | NSInteger degrees = 0;
1256 | switch (self.interfaceOrientation) {
1257 | case UIInterfaceOrientationPortrait:
1258 | degrees = 0;
1259 | break;
1260 | case UIInterfaceOrientationLandscapeLeft:
1261 | degrees = 90;
1262 | break;
1263 | case UIInterfaceOrientationLandscapeRight:
1264 | degrees = -90;
1265 | break;
1266 | case UIInterfaceOrientationPortraitUpsideDown:
1267 | degrees = 180;
1268 | break;
1269 | default:
1270 | // Don't care about this orientation.
1271 | return;
1272 | }
1273 | // Update the window.orientation property then trigger
1274 | // onorientationchange().
1275 | NSString *javascript = [NSString stringWithFormat:
1276 | // Create the 'window.orientation' read-only property.
1277 | @"window.__defineGetter__('orientation',function(){return %i;});"
1278 | // Dispatch the 'orientationchange' event. This also calls
1279 | // 'window.onorientationchange()'.
1280 | @"(function(){"
1281 | @"var event = document.createEvent('Events');"
1282 | @"event.initEvent('orientationchange', true, false);"
1283 | @"window.dispatchEvent(event);"
1284 | @"})();",
1285 | degrees];
1286 | [self.webView stringByEvaluatingJavaScriptFromString:javascript];
1287 | }
1288 |
1289 | }
1290 | ```
1291 |
1292 | Ad designers cannot rely on window.orientation to determine whether a device is in portrait or landscape mode. The value of window.orientation is intended to indicate the screen's position in relation to the “standard” orientation axis, i.e., the axis on which the values of a DeviceOrientationEvent are reported. However, that standard orientation may not be portrait (height greater than width) mode. Indeed, on widescreen Android tablets, such as the Samsung Galaxy Tab 10.1., window.orientation is set to zero when the device is in landscape (width greater than height) mode.
1293 |
1294 | Ad designers should instead use the mraid.getScreenSize() method to retrieve the current width and height of the device screen.
1295 |
1296 | ## _Storing a Picture_
1297 |
1298 | Rich Media Ad designers may want to add a picture to the camera roll or photo album of the device they are running on. This can be handy for a number of features, including storing coupons for later redemption.
1299 |
1300 | **storePicture** method
1301 |
1302 | The storePicture method will place a picture in the device's photo album. The picture may be local or retrieved from the Internet. To ensure that the user is aware a picture is being added to the photo album, MRAID requires the SDK/container use an OS-level handler to display a modal dialog box asking that the user confirm or cancel the addition to the photo album for each image added. If the device does not have a native “add photo” confirmation handler, the SDK should treat the device as though it does not support storePicture.
1303 |
1304 | This method will store the image or other media type specified by the URI.
1305 |
1306 | MRAID-compliant containers will support adding a picture via an HTTP redirect (for tracking purposes); however they will not necessarily support meta redirects.
1307 |
1308 | If the attempt to add the picture fails for any reason or is cancelled by the user, it will trigger an error.
1309 |
1310 | storePicture(URI)
1311 |
1312 | parameter:
1313 | · URI -String: the URI to the image or other media asset
1314 | related event:
1315 | · none
1316 |
1317 |
1318 | ## _Creating Calendar Events_
1319 |
1320 | The createCalendarEvent method opens the device UI to create a new calendar event. The ad is suspended while the UI is open. To ensure the creation of a calendar event is always user initiated and authorized, MRAID-compliant containers must invoke the device’s native “create calendar event” sheet, pre-populated with data supplied by the ad. Where a device does not support such a “create calendar event” sheet, the SDK should treat that device as if it does not support adding calendar events.
1321 |
1322 | Calendar event data should be delivered in the form of a JavaScript object written to the W3C’s calendar specification. See Appendix.
1323 |
1324 | If the attempt to create the calendar event fails or is cancelled by the user, it will trigger an error.
1325 |
1326 | createCalendarEvent(parameters)
1327 |
1328 | parameters:
1329 | · parameters: JavaScript Object {…} – this object contains the parameters for the calendar entry, written according to the W3C specification for calendar entries. See Appendix.
1330 | return value:
1331 | · none
1332 | related event:
1333 | · none
1334 |
1335 |
1336 | For example, the following would add a calendar event for the Mayan Apocalypse/End of the World on December 21, 2012, taking place “everywhere” and starting at midnight Eastern time and ending at midnight Eastern time on December 22, 2012.
1337 |
1338 | ```
1339 | createCalendarEvent({
1340 | description: “Mayan Apocalypse/End of World”,
1341 | location: ‘everywhere’,
1342 | start: ‘2012-12-21T00:00-05:00,
1343 | end: ‘2012-12-22T00:00-05:00’
1344 | })
1345 | ```
1346 |
1347 | ## _Working with Video_
1348 |
1349 | Video on mobile devices can be played either inline (within the current web view, app, or mobile web page) or by opening a native player on the device. For many advertising applications, inline playback will be preferred: it is less disruptive to the viewer’s experience, and playback within a web view enables HTML5 reporting on metrics related to how much of the creative was viewed. These metrics are generally harder to access, or unavailable, when video is viewed in the native player.
1350 |
1351 | Ad designers must keep in mind that device/OS limitations may prevent inline video playback (this is notably the case with devices running Android version 2.x and earlier).
1352 |
1353 | However, MRAID-compliant containers should support inline playback where possible, and permit ad designers to specify if video creative should play inline or in a separate player. Ad designers can use the “supports(inlineVideo)” method to determine whether the device running the creative will display video inline.
1354 |
1355 | In order to enable inline video playback and autoplay of video, MRAID-compliant SDKs should consistently insert the any necessary enabling tags into the web view depending on operating system of the device.
1356 |
1357 | For iOS devices, the following tags must be used:
1358 |
1359 | * webView.mediaPlaybackRequiresUserAction = NO;
1360 | * webView.allowsInlineMediaPlayback = YES;
1361 |
1362 | For Android (Honeycomb, Ice Cream Sandwich and above) devices, the SDK must invoke hardware acceleration, which is dependent on the view in question and how it is added to the WindowManager:
1363 |
1364 | * getWindow().setFlags(WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED, WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED);
1365 |
1366 | For Android 2.x and earlier devices, it is not possible to play video inline; the native player is always invoked by the playVideo method.
1367 |
1368 | **playVideo** method
1369 |
1370 | Use this method to play a video on the device via the device’s native, external player. Note that this is purely a convenience method for the OS’s existing external player, and does not imply a separate, SDK-based video player. To play video inline (on devices where that feature is supported), use HTML5 video tags.
1371 |
1372 | playVideo(URI)
1373 |
1374 | parameters:
1375 | · URI - String, the URI of the video or video stream
1376 | return values:
1377 | · none
1378 |
--------------------------------------------------------------------------------