A Passible Advertising WebIDL

Abstract

This specification defines a set of interface to access advertising service.

1. Introduction

This section is no-normative.

This API is designed to access advertising service from web app, such as admob, iAd, etc. Developer can request various types of advertisements from such services, as well as control the shown, hidden and destroy of the object. Meanwhile, the API can set the listener to open and close events of the object to maintain the states of the web app, for example, pause/resume the game.

1.Interface

interface xwalk {
  attribute Experimental experimental;
}

interface experimental {
  attribute Advertising ad;
}

1.1 Attributes

ad of type Advertising, readonly

• The object that exposes the Advertising functionality.

2. Advertising interface

The Advertising interface exposes the Advertising functionality.

interface Advertising {
  Promise create (RequestOptions requestOptions);
};

2.1 Methods

create

• This method creates an ad.
• Parameter: options
• Type: RequestOptions
• Nullable: N
• Optinal: N
• Return type: Promise

2.2 Steps

1. The create method when invoded Must run the following steps:

1. Create a View with input options. Banner or Interstitial.
2. Return a new Promise object.
3. If an error occurs call promise's error method.
4. When the method has been successfully completed, call success method of the promise.

3. Advertise interface

interface Advertise {
  Promise destroy ();
  Promise show (boolean show);
  attribute EventHandler onopen;
  attribute EventHandler onclose;
};

3.1 Attributes

onopen

• Handles the touch event, fired when an ad is opened by user.

onclose

• Handles the close event, fired when an ad is closed by user.

3.2 Methods

destroy

• This method destroys a view.
• No parameters.
• Return type: Promise

show

• This method controls the ad be shown and hidden.
• Parameter: bShow
• Type: boolean
• Nullable: N
• Optinal: N
• Return type: Promise

3.3 Steps

1. The destroy method when invoded Must run the following steps:

1. Destroy the ad.
2. Return a new Promise object.
3. If an error occurs call promise's error method.
4. When the method has been successfully completed, call success method of the promise.

2. The request method when invoded Must run the following steps:

1. request an ad from server.
2. Return a new Promise object.
3. If an error occurs call promise's error method.
4. When the method has been successfully completed, call success method of the promise.

3. The show method when invoded Must run the following steps:

1. Show ad when show is true. Hide ad when show is false.
2. Return a new Promise object.
3. If an error occurs call promise's error method.
4. When the method has been successfully completed, call success method of the promise.

4. RequestOptions interface

The Advertising interface exposes the Advertising functionality.

interface RequestOptions {
  attribute DOMString service;
  attribute DOMString publisherId;
  attribute AdType type;
  optional attribute AdSize size;
  optional attribute boolean bannerAtTop;
  optional attribute boolean overlap;
}

4.1 Attributes

service of type DOMString

• Represents a unique identifier of the provider. Like, "admob", etc.

publisherId of type DOMString

• Represents a unique identifier of the publisher.

type of type DOMString

• Represents the type of ad. Currently, "banner" and "interstitial" are available.

size of type DOMString

• Represents the size of ad.

bannerAtTop of type boolean

• Represents Whether or not the ad should be positioned at top or bottom of screen.

overlap of type boolean

• Represents Whether or not the banner will overlap the webview instead of push it up or down.

5. Enumerations

enum AdType {
  "banner",
  "interstitial"
}

enum AdSize {
  "BANNER",
  "IAB_MRECT",
  "IAB_BANNER",
  "IAB_LEADERBOARD",
  "SMART_BANNER"
}

6. Example

xwalk.experimental.ad.create({
    "service" : "admob",
    "publisherId" : "ca-app-pub-xxx/4806197152",
    "type" : "banner",
    "size" : "SMART_BANNER",
    "bannerAtTop" : false,
    "overlap" : false
}).then(
    function(ad) {
      ad.addEventListene("open", function(evt) {
        console.log("Ad is opened");
        ad.show(true);
      })  
      ad.addEventListene("close", function(evt) {
        console.log("Ad is closed");
      })  
    },  
    function(err) {
      console.log("Failed to create ad")
    }   
);