Mraid Extension Protocol

Mobile Rich Media Interactive advertising standard

tags (space delimited): MRAID Rich media advertising Interactive advertising background description

Over the past few years, rich media advertising on mobile applications has become more popular, and the IAB organization defines the Mraid advertising protocol has been widely used, but the Mraid protocol is the application of inline ads and interstitial ads, not widely used in the video field, This agreement on the basis of compatible with the Mraid 2.0 protocol, the player's interactive advertising has been expanded, in addition to Mraid protocol in support of mobile terminal sensors directly rely on the HTML5 standard, the latest HTML5 standards, although the sensor behavior is defined, But not all browser cores are supported, so this standard expands on mobile terminal sensor events, allowing more mobile devices to use rich sensor interactions. AD Format video pre-patch, mid-insert, post-patch video pause advertising interface standard interface Overview MRAID 2.0 defines the interface between the creative material and the app that the WebView component presents. The video player control defines the interactive interface between the creative footage and the video player displayed by the WebView component. The device sensor defines the interface between the app and sensor-related functions and the creative footage presented by the WebView component, in which the creative JS layer invokes the app method, which is an event triggered by the app, player, or system for the JS layer to process. IAB MRAID v2.0 compatible Overview

Method List

AddEventListener
GetVersion
Createcalendarevent
Isviewable
Close
Open
Expand
PlayVideo
GetCurrentPosition
RemoveEventListener
Getdefaultposition
Resize
Getexpandproperties
Setexpandproperties
Getmaxsize
Setresizeproperties
Getplacementtype
Storepicture
Getresizeproperties
Supports
Getscreensize
Usecustomclose
GetState
Getorientationproperties
Setorientationproperties

Event List

Error
StateChange
Ready
Viewablechange
Sizechange initializing The Ready event
The Ready event fires when the container is fully loaded, initialized, and prepared for any calls from the ad creative.
Ads should wait for the ready event before performing any rich media operations. Ad designers can use the ready event with the GetState () method because of some time issues, such as triggering a ready event before the ad registers for monitoring. GetVersion method
The GetVersion method allows the ad to confirm the underlying feature set before it is displayed. The version number must conform to the MRAID specification (for example, 1.0 or 2.0), not the vendor's SDK version number.
GetVersion (), String
Parameters:
None
return value
string–mraid compatible SDK version number or IAB-specific SDK version number. For example, for the version number of this article, GetVersion () will return the "2.0" event handling Web layer and the native layer of communication inherently asynchronous. With event handling, ad designers are able to listen to the specified events and respond to them as needed.

AddEventListener method
Use this method to subscribe to a specified processing method for the specified event. In this way, multiple listeners can subscribe to a specified event, and a listener can handle multiple events.

AddEventListener (event, listener)
Parameters:
event–string The name of the event to listen on
listener– performing a listener function
return value:
None

RemoveEventListener method
Use this method to unsubscribe from the specified event processing method. When event listeners are no longer useful, they should be removed to avoid errors. If no listener method is specified, all methods that are listening for the event are removed.

RemoveEventListener (event, listener)
Parameters:
Event–strign Event Name
listener– the function to be removed
return value:
None
Trigger event:
None error handling

Error event, the error event is triggered whenever a container error occurs. The event contains a description of when the error occurred, and, where appropriate, the name of the action that caused the error.

"Error" function (message, action)
Parameters:
message:string Error description
action:string trigger Error Action control ad display GetState method
Returns the current state of the ad container, returns whether the ad container is in its default state, whether it is a fixed position, whether it is in an expanded or scaled state, whether it is a larger position, or whether it is hidden.

Status	explain
Hidden	The interstitial ad turns into a closed state. In case of being supported, the banner ad turns into a closed state
Resized	AD container has changed size by MRAID2.0 resize () method
Expanded	Ad container expanded to cover top of application content
Default	Application and SDK set the initial location and size of the ad container

GetState (), String
Parameters:
None
return value:
string: "Loading" or "default" or "expanded" or "resized" or "hidden"
Related events:
StateChange

StateChange Events
The StateChange event is triggered when the state is changed by the ad or the environment in a procedural way. When the ad view changes between the default, expanded, resized, hidden states (these states are triggered by calling expand (), resize (), close (), the StateChange event is fired.

function (state), "StateChange"
Parameters:
state-string, "Loading" or "default" or "expanded" or "resized" or "hidden"
Via Trigger:
expand () method, resize () method, Close () method, or app

Getplacementtype () method
The container returns the value of the placement type to make it easier for the creative to raise different behaviors when needed.
Value Description:

form	Description
Inline	The default placement type is embedded in the content display (that is, banner)
Interstitial	This type of ad placement is overlaid on the content

Getplacementtype (), String
Parameters:
None
return value:
string: "inline", "interstitial"
Related events:
None

Isviewable method
The Isviewable method returns whether the ad container is currently on the screen.

Isviewable (), Boolean
Parameters:
None
return value:
Boolean-
True: The container is on the screen and visible to the user;
False: The container is not on the screen and is not visible
Related events:
Viewablechange

Viewablechange Events

    Wait for the SDK to become Ready
    if (mraid.getstate () = = = ' loading ') {
        mraid.addeventlistener (' Ready ', Onsdkrea DY);
    } else {
        onsdkready ();
    }

    function Onsdkready () {
        //Wait for the ad-become viewable for the first time
        if (mraid.isviewable ()) {
            sho Wmyad ();
        } else {
            mraid.addeventlistener (' Viewablechange ', function (viewable) {
                if (viewable) {
                    Mraid.removeeventlistener (' Viewablechange ', Arguments.callee);
                    Showmyad ();}}
            ); 
        }
    }

    function Showmyad () {
    ... 
    }

The Viewablechange event is triggered when an ad appears or departs from the screen

Function "Viewablechange" (isviewable)
Parameters:
Isviewable-boolean
True: The container is on the screen and visible to the user;
False: The container is not on the screen and is not visible
Via Trigger:
• Changes to the application view Controller

Ads can be loaded outside the screen under any circumstances, and the best practice is to check the visibility of the ad itself or register for Viewablechange monitoring events before taking any action. Change AD Size

MRAID2.0 contains three different ways to change the size of your ad.
-Resize ()
Can accomplish complex ad size changes

Resize ()
Parameters:
None
return value:
None
Trigger event:
Sizechange, StateChange
Side effects:
• Change State Control Resize properties
Resizeproperties Object
Resizeproperties Object = {
"width": integer,
"Height": integer,
"OffsetX": Integer,
"OffsetY": Integer,
"Customcloseposition": String,
"Allowoffscreen": Boolean
}

width:integer--(must) creative pixel width
height:integer--(must) creative pixel high
offsetx:--(MUST) TODO
offsety:--(MUST) TODO
customcloseposition:string--(optional) "Top-right", "center", "Bottom-left", "Bottom-right", "Top-center" or "Bottom-center ”。 Represents the Origin location of the closing event area provided by the container relative to the scale of the creative. If none of these options are specified or not, the default is "Top-right".
allowoffscreen:--(optional) tells the container whether to allow the zoom creative to draw the full/partial out of the screen.
True (default): The container should not attempt to position the zoom creative.
False: The container should try to readjust the zoom creative to accommodate the value of the Getmaxsize ().

Getresizeproperties method
Use this method to get the attributes after the ad is scaled.

Getresizeproperties (), JavaScript Object
Parameters:
None
return value:
{.}-JS object containing the resize attribute
Trigger event:
None

Setresizeproperties method
Use this method to set the scale properties of your ad, especially the width and height properties.

Setresizeproperties (), JavaScript Object
Parameters:
Properties:javascript Object {...}--contains the width and height of the ad to be scaled, the close position, the offset direction (in dips), whether the ad can be scaled to the left screen. See the Resizeproperties object for more information.
return value:
None
Trigger event:
None
-Expand ()
Simple, modal, increase the size of the ad
expand ([URL])
Parameters:
URL (optional): The URLs in this article are displayed in a new matte view. If you pass in null or do not use this parameter, the body of the current ad is used in the same Web view
return value:
None
Trigger event:
StateChange

Control Expand Properties
The Expand property is designed to provide additional functionality to AD designers.
Expandproperties Object = {
"width": integer,
"Height": integer,
"Usecustomclose": Boolean,
"Ismodal": Boolean (Read only)
}

Getexpandproperties method
Returns the complete JavaScript object containing the expand attribute.

Getexpandproperties (), JavaScript Object
Parameters:
None
return value:
{...}-this object contains the expand properties
Trigger event:
None

Setexpandproperties method
Sets the entire JavaScript object that contains the expand property.

Setexpandproperties (properties)
Parameters:
Properties:javascript Object {...}--contains the advertisement's wide-height value, and more properties refer to the Property object.
return value:
None
Trigger event:
None

Open ()
Open an external mobile site in a browser window

Open (URL)
Parameters:
url-string, Web URL
return value:
None
Turn off expanded and interstitial ads

Close ()
The Close method returns the ad container to its original state. For ads in the expanded or resized state, calling the Close method will change the ad status to default. For interstitial ads in the default state, calling the Close method changes the ad state to hidden. In this specification, for banner ads that are in the default state, the effect of calling close is undefined, so the ad designer is not generally recommended to call the Mraid.close () method in a banner ad

Close ()
Parameters:
None
return value:
None
Trigger event:
StateChange

Usecustomclose method
Although mraid requires all implementation containers to provide a clickable area with a default close icon, it is entirely possible for ad creators to use their own closed guidelines.
For expanded ads, the designer does not need to call this method, typically setting the Usecustomclose property in the Setexpandproperties () method.
For standalone interstitial ads that cannot invoke the expand method, but still require a mraid force-off option, the ad designer should call the method immediately after the ready event completes.
This method is used as a shortcut to a property of the same name in the Expand property. Set the Usecustomclose property or call this method, both of which have the same effect and can be used interchangeably. If an ad is set with Usecustomclose through the Expand property and this method, any later calls will overwrite the older settings. They notify the container to stop using the default shutdown guidelines.

Usecustomclose (Iscustomize)
Parameters:
Iscustomize-boolean
true--Advertising ideas to provide their own design closure guidelines
false--will display the default picture provided by the container for the close guide
return value:
None
Trigger event:
None

Precautions:
Hypertext Links
When a user clicks an HTML hyperlink (defined by <\a href= "" > tag) in a mraid ad, there are two possibilities: the target page can be loaded into an existing Web view, or the content of the target page can open a separate browser window and load the link there. Mraid-compatible SDKs can choose any of two ways, so advertisers should avoid using inline hyperlinks and window.location. For a standard mraid ad, Mraid.open () is the appropriate way to specify a link to open a page in a separate browser. When you load a new page in AD view and leave the ad without being written to the Mraid specification, the app may be unavailable at this time. Control Direction Properties

Mraid.setorientationproperties ({"Alloworientationchange": true});
Mraid.expand ()/
* user changes to Landscape, starts game *
/mraid.setorientationproperties ({" Alloworientationchange ": false});
/* User is do with game *
/mraid.setorientationproperties ({"Alloworientationchange": true});

Orientationproperties object = { 
"Alloworientationchange": Boolean,
"Forceorientation": "Portrait|landscape |none "
}

alloworientationchange:boolean--if set to True, the ad container will allow changes based on device orientation, or if set to False, this change is ignored (for example: if the device changes direction, the Web view will not change). The default value is true. Regardless of how alloworientationchange is set, creative advertising can always change their orientation by setting forceorientation values.
forceorientation:string--can set one of the values for portrait, landscape, none. If you set the value of Forceorientation, the view must open in a specific direction, regardless of the orientation of the device. That is, if the user is viewing the ad in landscape mode and clicking expand it, if the ad designer sets the Forceorientation property to portrait, then the ad will open in portrait mode. The default value is None. Getorientationproperties method
The Getorientationproperties method returns the complete JavaScript object that contains the Orientation property.

Getorientationproperties (), JavaScript Object
Parameters:
None
return value:
{.}--This object contains the Orientation property.
Trigger event:
None Setorientationproperties method
Sets the JavaScript Direction Property object.
Setorientationproperties (properties)
Parameters:
Properties:javascript Object {...}--contains values for Alloworientationchange and forceorientation.
return value:
None
Trigger event:
None detecting the location and size of screens and ads

GetCurrentPosition method
The GetCurrentPosition method returns the current position and size of the ad view, in dips.

GetCurrentPosition (), JavaScript Object
Parameters:
None
return value:
JavaScript Object-{x, y, width, height}:
x= offset from the left side of the rectangle defined by the Getmaxsize method (dip units)
Y= offset from the top of the rectangle defined by the Getmaxsize method (dip units)
Width= the width of the current container.
height= the height of the current container. (All in dip units)
Associated events:
None

Getmaxsize method
The Getmaxsize method returns the maximum size (width and height, in dips) that the ad can expand to or zoom to.

Getmaxsize (), JavaScript Object
Parameters:
None
return value:
JavaScript Object, {width, height}--view can grow to the maximum width and height
Associated events:
None

Sizechange method
The Sizechange event is triggered when the ad's size changes within the app interface. It may be the result of a device direction change or call to resize or a call to the expand method. are in dip units.
This event is triggered when the display state of the ad's Web view has changed.

function (width, height), "Sizechange"
Parameters:
Width-number: The width of the view.
Height-number: The height of the view.
Via Trigger:
• Triggered when the ad view size changes after scaling, expanding, closing, changing direction, or when the app registers size-related event listeners.

Getdefaultposition method
The Getdefaultposition method returns the location and size (in dips) of the default ad view, regardless of the state of the view in which it is called.

Getdefaultposition (), JavaScript Object
Parameters:
None
return value:
JavaScript Object-{x, y, width, height}:
X= the offset from the left side of the Getmaxsize (Dip unit);
Y= the offset from the top of the Getmaxsize (Dip unit);
Width= the width of the current container;
height= the height of the current container;

Getscreensize method
The Getscreensize method returns the actual pixel width and height of the running ad device based on the current direction, in dips. One thing to note: If the device changes from a horizontal screen to a vertical screen, the screensize will change (and vice versa). Another point to note is that Getscreensize returns the total size of the device screen, including the reserved areas of the operating system to the status bar/system bar, or other areas that can be covered by the app or AD.

Getscreensize (), JavaScript Object
Parameters:
None
return value:
{width, height}
Associated events: accessing local functionality supports method
The Supports method allows the ad to inquire about the specified features supported by the device.

Properties	Value Description
Sms	The device supports the use of the short message feature: Send a short message according to the protocol
Tel	Device support using the phone function to make a call: by agreement
Calendar	Device can create a calendar item
Storepicture	Device Support Mraid Storepicture method
Inlinevideo	The device can use the label to play the HTML5 video file and play it according to the dimensions (width and height) specified in the video tag. There is no need to play the video in full-screen mode.

> Supports (feature), Boolean parameter: string The name of the attribute to detect (SMS, tel, calendar, storepicture, Inlinevideo) return values: Boolean true--supports this feature, and getter and events are available. false--the current device does not support this feature. # # # # # # # # # # # # # # # # # # The physical characteristics of the equipment in theory HTML5 's latest standards have been supported, but since not all devices can support the latest HTML5 standards, this part of the work, this agreement is supplemented by the third part, advertising designers, monitoring the third part of the event, will be able to obtain more support # Save Picture Call the Storepicture method will leave a picture in the device album. The picture may have been downloaded locally or from the Web. To ensure that users notice that the pictures will be added to their device albums, Mraid requires the sdk/container to use the OS-level Processor Display Model dialog box to ask the user to confirm or cancel the add picture during the addition of each picture. > storepicture (URI) parameter: uri-string: URI Association event for picture or other media resource: None # # # # # # # # Create calendar events-Createcalendarevent createcalendarevent ({description: "Mayan apocalypse/end of the World", location: ' Everywhere ', start: ' 2012-12-21t00:00-05:00, End: ' 2012-12-22 T00:00-05:00 '}) > createcalendarevent (Parameters) Parameters: The parameters:javascript object {...}--objects contain the entries required for calendar events, as specified by the Calendar entries are written. return value: none associated event: None # # # # # # # # # # # # # # # # # # # # # # # # # # Where possible, Mraid-compatible containers are best supported for inline playback, while allowing the ad designer to specify whether video ideas are played in-line or individually. Ad designers can use the supports (Inlinevideo) method to determine whether the device that is running the creative is displayedIn-line video. -Inline playback in order for the inline video to play and play automatically, the Mraid compatible SDK should insert the necessary open tags into the Web view, depending on the type of operating system of the device. For iOS devices, you must use the following tags:

Webview.mediaplaybackrequiresuseraction = NO;
Webview.allowsinlinemediaplayback = YES;

For Android devices (Honeycomb,ice Cream Sandwich, and later versions of them), the SDK must request hardware acceleration, which depends on the view in the problem and how it was added to the WindowManager:

GetWindow (). SetFlags (WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED, WindowManager.LayoutParams.FLAG_ hardware_accelerated);

Device/OS limitations may prevent inline video playback, and ad designers can use the supports (Inlinevideo) method to determine whether the device running the idea displays inline video.
-PlayVideo method
Use this method to play the video on the device through the device's native external player.

PlayVideo (URI)
Parameters:
uri-string, video address or video stream
return value:
None video player controls (optional) Overview

In order to increase the video pre-paste, plug-in, post-paste ads interactive ability, you need to add a layer of video advertising player WebView to show HTML5 ads, WebView layer can not interact with the video player, but in order to give WebView layer with more permissions, The methods and events defined below can be implemented by the WebView layer, with the ability to implement the original native code, resulting in greater flexibility. However, these interfaces are optional, enabling the implementation to interact only by adding webview.

Method List

Mainvideo.addeventlistener
Mainvideo.removeeventlistener
Mainvideo.pause
Mainvideo.resume
Mainvideo.getprogress
Mainvideo.expand
Mainvideo.shrink
Mainad.addeventlistener
Mainad.removeeventlistener
Mainad.setobjectviewable Event List

Durationchange Player Control Mainvideo

Mainvideo.pause method
Pause main AD Playback

Mainvideo.pause ()
Parameters:
None
return value:
None

Mainvideo.resume method
Resume Primary AD Playback

Mainvideo.resume ()
Parameters:
None
return value:
None

Mainvideo.getprogress method
Gets the current ad playback progress to 0~1 before the decimal representation

Mainvideo.getprogress ()
Parameters:
None
return value:
Number 0~1 Decimal

Durationchange Events
Get current AD duration
How to listen:
Mraid.mainVideo.addEventListener (Mraid.mainVideo.EVENTS.DURATION_CHANGE, func);
This event needs to be used with the Mraid.stageready () method, when the page is loaded successfully, the Mraid.stageready () method needs to be called, the above event will be triggered, the incoming ad duration

Function "Durationchange" (duration)
Parameters:
Duration-number
Duration of ad remaining
Via Trigger:
• Triggered when the ad player ad time changes

Mainvideo.expand method
Call the interface to enlarge the video to full screen

Mainvideo.expand ()
Parameters:
None
return value:
None

Mainvideo.shrink method
Call the interface to exit the video full screen

Mainvideo.shrink ()
Parameters:
None
return value:
None HTML5 rich media floating layer Mainad mainad.setobjectviewable method
Hide/Show related UI based on different parameters
Mainad.setobjectviewable (Number,boolean)
Parameters
Number-number: Sets the UI that needs to be hidden/displayed based on different values
1: Countdown number
2: Details click button
Boolean-The incoming parameter sets the display/hide effect of the UI; true: Display, false: hidden;
Cases:
Hide Countdown mraid.mainAd.setObjectViewable (1, false)
Display Countdown mraid.mainAd.setObjectViewable (1, true)
Hide Click Details mraid.mainAd.setObjectViewable (2, false)
Show Click Details mraid.mainAd.setObjectViewable (2, true) device sensor (optional) Overview The Mobile sensor event has been defined in the latest standard for HTML5, However, since the mobile phone built-in browser kernel does not all support the latest HTML5 standard, based on this, this Protocol defines a series of events, for the mobile side of the more extensive support device sensor events and methods are directly based on the Mraid protocol to increase, do not produce a new namespace, Monitored by mraid.addeventlistener (event, processing method). Event List

Shake

"Shake", Function ()
Parameters:
None
Via Trigger:
• Mobile phone Shake trigger

Tiltchange

function (x, y, z), "Tiltchange"
Parameters:
x,y,z-float rotation vectors for corresponding axes, respectively
Via Trigger:
• Triggered when the phone's tilt angle changes

Headingchange

Function "Headingchange" (heading)
Parameters:
heading value is 0-360 integer angle, 0 is north direction, clockwise accumulation
Via Trigger:
• Mobile phone facing change trigger

Locationchange

Function "Locationchange" (LAT,LNG,ACC)
Parameters:
Are floating-point numbers
lat to longitude
LNG for Latitude
ACC for accuracy
Via Trigger:
• Mobile phone location change trigger

NetworkChange

function (Network), "NetworkChange"
Parameters:
network-string value is Unknown,offline,cell,wifi
Via Trigger:
• Mobile network status change Trigger

Orientationchange
Function "Orientationchange" (angle)
Parameters:
angle for angle, 90 for vertical screen, 180 for horizontal screen
Via Trigger:
• Mobile phone screen Change trigger method

Supports method
The Supports method allows the ad to inquire about the specified features supported by the device. The method is to expand the Mraid.supports (), the value is shake, title, heading, keyboard, location, network, orientation.

Supports (feature), Boolean
Parameters:
string to detect the name of the attribute (shake, title, heading, keyboard, location, network, orientation)
Return values:
Boolean
true--supports this feature, and getter and events are available.
false--the current device does not support this feature. get the version of this Agreement

Caamraid.getversion method

GetVersion (), String
Parameters:
None
return value
string– The version number of this Agreement, GetVersion () will return "1.0" out of range

Search ads from AD servers, ad networks, local resources
Ad Size
Download resources to the local file system for caching or offline
IDE Integration
Security and privacy
Internationalization
Error Reporting extensibility and compatibility

Minimum support Support MRAID2.0