firebase::gma::AdView

#include <ad_view.h>

Loads and displays Google Mobile Ads AdView ads.

Summary

Each AdView object corresponds to a single GMA ad placement of a specified size. There are methods to load an ad, move it, show it and hide it, and retrieve the bounds of the ad onscreen.

AdView objects provide information about their current state through Futures. Methods like Initialize, LoadAd, and Hide each have a corresponding Future from which the result of the last call can be determined. The two variants of SetPosition share a single result Future, since they're essentially the same action.

For example, you could initialize, load, and show an AdView while checking the result of the previous action at each step as follows:

namespace gma = ::firebase::gma;
gma::AdView* ad_view = new gma::AdView();
ad_view->Initialize(ad_parent, "YOUR_AD_UNIT_ID", desired_ad_size)

Then, later:

if (ad_view->InitializeLastResult().status() ==
    ::firebase::kFutureStatusComplete &&
    ad_view->InitializeLastResult().error() ==
    firebase::gma::kAdErrorCodeNone) {
  ad_view->LoadAd(your_ad_request);
}

Constructors and Destructors

AdView()
Creates an uninitialized AdView object.
~AdView()

Public types

Position{
  kPositionUndefined = -1,
  kPositionTop = 0,
  kPositionBottom,
  kPositionTopLeft,
  kPositionTopRight,
  kPositionBottomLeft,
  kPositionBottomRight
}
enum
The possible screen positions for a AdView, configured via SetPosition.

Protected attributes

ad_listener_
Pointer to a listener for AdListener events.
ad_view_bounding_box_listener_
Pointer to a listener for BoundingBox events.
paid_event_listener_
Pointer to a listener for paid events.

Public functions

Destroy()
Future< void >
Cleans up and deallocates any resources used by the AdView.
DestroyLastResult() const
Future< void >
Returns a Future containing the status of the last call to Destroy.
Hide()
Future< void >
Hides the AdView.
HideLastResult() const
Future< void >
Returns a Future containing the status of the last call to Hide.
Initialize(AdParent parent, const char *ad_unit_id, const AdSize & size)
Future< void >
Initializes the AdView object.
InitializeLastResult() const
Future< void >
Returns a Future that has the status of the last call to Initialize.
LoadAd(const AdRequest & request)
Begins an asynchronous request for an ad.
LoadAdLastResult() const
Returns a Future containing the status of the last call to LoadAd.
Pause()
Future< void >
Pauses the AdView.
PauseLastResult() const
Future< void >
Returns a Future containing the status of the last call to Pause.
Resume()
Future< void >
Resumes the AdView after pausing.
ResumeLastResult() const
Future< void >
Returns a Future containing the status of the last call to Resume.
SetAdListener(AdListener *listener)
void
Sets an AdListener for this ad view.
SetBoundingBoxListener(AdViewBoundingBoxListener *listener)
void
Sets a listener to be invoked when the Ad's bounding box changes size or location.
SetPaidEventListener(PaidEventListener *listener)
void
Sets a listener to be invoked when this ad is estimated to have earned money.
SetPosition(int x, int y)
Future< void >
Moves the AdView so that its top-left corner is located at (x, y).
SetPosition(Position position)
Future< void >
Moves the AdView so that it's located at the given predefined position.
SetPositionLastResult() const
Future< void >
Returns a Future containing the status of the last call to either version of SetPosition.
Show()
Future< void >
Shows the AdView.
ShowLastResult() const
Future< void >
Returns a Future containing the status of the last call to Show.
ad_size() const
Returns the AdSize of the AdView.
bounding_box() const
Retrieves the AdView's current onscreen size and location.

Public types

Position

 Position

The possible screen positions for a AdView, configured via SetPosition.

Properties
kPositionBottom

Bottom of the screen, horizontally centered.

kPositionBottomLeft

Bottom-left corner of the screen.

kPositionBottomRight

Bottom-right corner of the screen.

kPositionTop

Top of the screen, horizontally centered.

kPositionTopLeft

Top-left corner of the screen.

kPositionTopRight

Top-right corner of the screen.

kPositionUndefined

The position isn't one of the predefined screen locations.

Protected attributes

ad_listener_

AdListener * ad_listener_

Pointer to a listener for AdListener events.

ad_view_bounding_box_listener_

AdViewBoundingBoxListener * ad_view_bounding_box_listener_

Pointer to a listener for BoundingBox events.

PaidEventListener * paid_event_listener_

Pointer to a listener for paid events.

Public functions

AdView

 AdView()

Creates an uninitialized AdView object.

Initialize must be called before the object is used.

Destroy

Future< void > Destroy()

Cleans up and deallocates any resources used by the AdView.

You must call this asynchronous operation before this object's destructor is invoked or risk leaking device resources.

DestroyLastResult

Future< void > DestroyLastResult() const 

Returns a Future containing the status of the last call to Destroy.

Hide

Future< void > Hide()

Hides the AdView.

HideLastResult

Future< void > HideLastResult() const 

Returns a Future containing the status of the last call to Hide.

Initialize

Future< void > Initialize(
  AdParent parent,
  const char *ad_unit_id,
  const AdSize & size
)

Initializes the AdView object.

Details
Parameters
parent
The platform-specific UI element that will host the ad.
ad_unit_id
The ad unit ID to use when requesting ads.
size
The desired ad size for the ad.

InitializeLastResult

Future< void > InitializeLastResult() const 

Returns a Future that has the status of the last call to Initialize.

LoadAd

Future< AdResult > LoadAd(
  const AdRequest & request
)

Begins an asynchronous request for an ad.

If successful, the ad will automatically be displayed in the AdView.

Details
Parameters
request
An AdRequest struct with information about the request to be made (such as targeting info).

LoadAdLastResult

Future< AdResult > LoadAdLastResult() const 

Returns a Future containing the status of the last call to LoadAd.

Pause

Future< void > Pause()

Pauses the AdView.

Should be called whenever the C++ engine pauses or the application loses focus.

PauseLastResult

Future< void > PauseLastResult() const 

Returns a Future containing the status of the last call to Pause.

Resume

Future< void > Resume()

Resumes the AdView after pausing.

ResumeLastResult

Future< void > ResumeLastResult() const 

Returns a Future containing the status of the last call to Resume.

SetAdListener

void SetAdListener(
  AdListener *listener
)

Sets an AdListener for this ad view.

Details
Parameters
listener
An AdListener object which will be invoked when lifecycle events occur on this AdView.

SetBoundingBoxListener

void SetBoundingBoxListener(
  AdViewBoundingBoxListener *listener
)

Sets a listener to be invoked when the Ad's bounding box changes size or location.

Details
Parameters
listener
A AdViewBoundingBoxListener object which will be invoked when the ad changes size, shape, or position.

SetPaidEventListener

void SetPaidEventListener(
  PaidEventListener *listener
)

Sets a listener to be invoked when this ad is estimated to have earned money.

Details
Parameters
listener
A PaidEventListener object to be invoked when a paid event occurs on the ad.

SetPosition

Future< void > SetPosition(
  int x,
  int y
)

Moves the AdView so that its top-left corner is located at (x, y).

Coordinates are in pixels from the top-left corner of the screen.

When built for Android, the library will not display an ad on top of or beneath an Activity's status bar. If a call to SetPosition would result in an overlap, the AdView is placed just below the status bar, so no overlap occurs.

Details
Parameters
x
The desired horizontal coordinate.
y
The desired vertical coordinate.
Returns
a Future which will be completed when this move operation completes.

SetPosition

Future< void > SetPosition(
  Position position
)

Moves the AdView so that it's located at the given predefined position.

Details
Parameters
position
The predefined position to which to move the AdView.
Returns
a Future which will be completed when this move operation completes.

SetPositionLastResult

Future< void > SetPositionLastResult() const 

Returns a Future containing the status of the last call to either version of SetPosition.

Show

Future< void > Show()

Shows the AdView.

ShowLastResult

Future< void > ShowLastResult() const 

Returns a Future containing the status of the last call to Show.

ad_size

AdSize ad_size() const 

Returns the AdSize of the AdView.

Details
Returns
An AdSize object representing the size of the ad. If this view has not been initialized then the AdSize will be 0,0.

bounding_box

BoundingBox bounding_box() const 

Retrieves the AdView's current onscreen size and location.

Details
Returns
The current size and location. Values are in pixels, and location coordinates originate from the top-left corner of the screen.

~AdView

 ~AdView()