A Passible Advertising WebIDL

Abstract

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

1. Introduction

This section is non-normative.

The Advertising 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.

2. Conformance

As well as sections marked as non-normative , all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

he key words must , must not , required , should , should not , recommended , may , and optional in this specification are to be interpreted as described in RFC2119.

3. Terminology

The following concepts, terms and interfaces are defined in HTML5:

• EventHandler
• event handler and event types

Promise objects are defined in ECMASCRIPT.

4.Interface

interface xwalk {
  attribute Experimental experimental;
}

interface experimental {
  attribute Advertising ad;
}

4.1 Attributes

ad of type Advertising, readonly

• The object that exposes the Advertising functionality.

5. Advertising interface

The Advertising interface exposes the Advertising functionality.

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

5.1 Methods

create

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

5.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.

6. Advertise interface

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

6.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.

6.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

6.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.

7. 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;
}

7.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.

8. Enumerations

enum AdType {
  "banner",
  "interstitial"
}

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

9. Example

This section is non-normative.

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");
        ad.destroy();
      })  
    },  
    function(err) {
      console.log("Failed to create ad")
    }   
);

First step, you should create an advertise object. If you don't have a publisherId from an advertising service, please access the home page of corresponding service provider to register an account and get one. In this example, adverting service is admob. The request type is banner.

In the success callback function of the Promise, which ad.create() returns, you can add event listener to object. There are two types of event you can get, open and close. open is fired when user touches or clicks the advertisement. If you are in a game, the game should be paused in the callback function of the event. In this example, just leave a log, "Ad is opened". close means user touches or clicks the close button of the advertisement.