# Background
Prebid Mobile SDKs for iOS and Android were released to GitHub in August 2017 with the intention of providing an end-to-end open-source header bidding solution for mobile app publishers. Over a year of alpha testing, we have worked closely with early adopters to understand major friction points, gaps in understanding, design flaws, and areas for improvement.
## Observations from the Past Year
- It is taking publishers far too long to integrate Prebid Mobile
- Prebid Mobile has suffered from stability issues
- The ad unit creation/ registration/ bid keyword association workflow is too complicated, and is difficult to implement correctly
- Interstitial ad units in Prebid Mobile do not work the way that publishers expect
- When experiencing issues during implementation, publishers are unable to troubleshoot them effectively
# Goals
- Simplify Prebid Mobile implementation workflow for publishers
- Eliminate inconsistencies between the iOS and Android SDK APIs
- Eliminate inconsistencies between DFP and MoPub ad server behavior
- Eliminate "secret" backend processes which cause publisher confusion and unexpected behavior
- Eliminate Prebid Mobile stability issues and reduce Prebid Mobile bug index
# Proposed Design
## Global Settings
Global settings will be associated with a `PrebidMobile` object.
- `setPrebidServerHost`
Define the Prebid Server host with which Prebid Mobile will communicate. Choose from system-defined Prebid Server hosts or define your own custom Prebid Server host.
- `setPrebidServerAccountId`
Define the Prebid Server account ID provided by your Prebid Server host.
- `setShareGeoLocation`
Boolean flag. If this flag is True AND the app collects the user's geographical location data, Prebid Mobile will send the user's geographical location data to Prebid Server. If this flag is False OR the app does not collect the user's geographical location data, Prebid Mobile will not populate any user geographical location information in the call to Prebid Server.
- `setApplicationContext`
For Android only. Prebid Mobile will use the application context to retrieve metadata needed for targeting such as user agent, location, device information, connectivity information, etc.
### Android Example
```
PrebidMobile.setPrebidServerHost(Prebid.Host.APPNEXUS);
PrebidMobile.setPrebidServerAccountId("PREBID_SERVER_ACCOUNT_ID");
PrebidMobile.setShareGeoLocation(true);
PrebidMobile.setApplicationContext(getApplicationContext());
```
### iOS Example
```
let prebidMobile = PrebidMobile()
prebidMobile.prebidServerAccountId = "PREBID_SERVER_ACCOUNT_ID"
prebidMobile.prebidServerHost = Host.appnexus
prebidMobile.shareGeoLocation = true
```
## Banner Ad Unit
- `BannerAdUnit`
Create a new Banner Ad Unit associated with a Prebid Server configuration ID and a banner size (width and height).
- `addAdditionalSize`
Add an additional banner size to the Prebid Mobile ad unit. Banner ad units must be associated with one or more sizes.
- `fetchDemand`
Trigger a call to Prebid Server to retrieve demand for this Prebid Mobile ad unit.
- `addUserKeyword`
Add a key-value pair to a given Prebid Mobile ad unit. One key may correspond to one or more values.
- `removeUserKeyword`
Remove a key and all its associated values from a given Prebid Mobile ad unit.
- `clearUserKeywords`
Remove all keys and all values from a given Prebid Mobile ad unit.
- `setAutoRefreshMillis`
If set on a given Prebid Mobile ad unit, the fetchDemand function will be called every periodMillis until stopAutoRefresh is called. Each call to fetchDemand will invoke the onComplete function.
- `stopAutoRefresh`
Halts the auto-refresh behavior for a given Prebid Mobile ad unit. If no auto-refresh behavior has been set, stopAutoRefresh will be ignored.
### Android Example
```
PublisherAdView dfpAdView = new PublisherAdView(context);
dfpAdView.setAdUnitId("/12345/foo");
dfpAdView.setAdSizes(new AdSize(300, 250));
final PublisherAdRequest.Builder builder = new PublisherAdRequest.Builder();
final PublisherAdRequest request = builder.build();
BannerAdUnit bannerAdUnit = new BannerAdUnit("PREBID_SERVER_CONFIGURATION_ID", 300, 250);
bannerAdUnit.addUserKeyword("my_key", "my_value");
bannerAdUnit.fetchDemand(request, new onCompleteListener() {
@Override
public void onComplete(ResultCode resultCode) {
dfpAdView.loadAd(request);
}
});
```
### iOS Example
```
var dfpBannerView = DFPBannerView(adSize: GADAdSizeFromCGSize(CGSize(width: 300, height: 250)))
dfpBannerView.adUnitID = "/12345/foo"
dfpBannerView.rootViewController = self;
dfpBannerView.delegate = self
let bannerAdUnit = BannerAdUnit(configId: "PREBID_SERVER_CONFIGURATION_ID", size: CGSize(width: 300, height: 250))
bannerAdUnit.addUserKeyword(key: "my_key", value: "my_value")
bannerAdUnit.fetchDemand(adObject: dfpBannerView) { (resultCode) in
//Load the dfp request
dfpBannerView.load(GADRequest())
}
```
## Interstitial Ad Unit
- `InterstitialAdUnit`
Create a new Interstitial Ad Unit associated with a Prebid Server configuration ID.
- `fetchDemand`
Trigger a call to Prebid Server to retrieve demand for this Prebid Mobile ad unit.
- `addUserKeyword`
Add a key-value pair to a given Prebid Mobile ad unit. One key may correspond to one or more values.
- `removeUserKeyword`
Remove a key and all its associated values from a given Prebid Mobile ad unit.
- `clearUserKeywords`
Remove all keys and all values from a given Prebid Mobile ad unit.
- `setAutoRefreshMillis`
If set on a given Prebid Mobile ad unit, the fetchDemand function will be called every periodMillis until stopAutoRefresh is called. Each call to fetchDemand will invoke the onComplete function.
- `stopAutoRefresh`
Halts the auto-refresh behavior for a given Prebid Mobile ad unit. If no auto-refresh behavior has been set, stopAutoRefresh will be ignored.
### Android Example
```
InterstitialAdUnit interstitialAdUnit = new InterstitialAdUnit("PREBID_SERVER_CONFIGURATION_ID");
interstitialAdUnit.addUserKeyword("my_key", "my_value");
interstitialAdUnit.fetchDemand(publisherAdRequest, new onCompleteListener() {
@Override
public void onComplete(ResultCode resultCode) {
dfpInterstitial.loadAd(publisherAdRequest);
}
});
```
### iOS Example
```
let dfpInterstitialView = DFPInterstitial(adUnitID: "/12345/foo")
dfpInterstitialView.delegate = self
let interstitialAdUnit = InterstitialAdUnit(configId: "PREBID_SERVER_CONFIGURATION_ID")
interstitialAdUnit.addUserKeyword(key: "my_key", value: "my_value")
interstitialAdUnit.fetchDemand(adObject: dfpInterstitialView) { (resultCode) in
//Load the dfp request
interstitialAdUnit.load(GADRequest())
}
```
## Result Codes
- Success
Prebid Mobile received at least one valid bid from Prebid Server and successfully associated Prebid key-values with the appropriate ad server request.
- Prebid Server Error
General result code for an unknown error returned from Prebid Server. The actual Prebid Server error message will be exposed to the developer.
- Invalid account ID
Prebid Server did not recognize the account ID.
- Invalid configuration ID
Prebid Server did not recognize the configuration ID.
- Invalid size
Attempted to add an invalid size to a banner ad unit.
- Network error
Request to Prebid Server resulted in a network error.
- Timeout
Request to Prebid Server resulted in a timeout.
- No bids
Prebid Server responded without returning any valid bids.
- Empty host URL
Attempted to define a custom Prebid Server host without providing a host URL.
- Invalid ad object
Ad object passed to `fetchDemand` is not supported.
## Global Targeting Parameters
Prebid Mobile will support the following global targeting parameters. These targeting parameters are set only once and apply to all Prebid Mobile ad units. They do not change for a given user session.
### Global User Targeting
- Year of birth
- Gender
### Global Application Targeting
- Bundle ID
- Domain
- Store URL
### Global GDPR Targeting
- Flag to indicate if the user is subject to GDPR
- GDPR consent string
@anwzhang , and @ppuviarasu . Thanks for the new PR and versions.
I have noticed many points to be fixed with Prebid SDK 1.0 for iOS and Android. I am reviewing the code and will update you soon.
Some points are minors but some are essential as it could broke the current integration (for instance running the completion function the main queue, NSTimer not bound to an NSRunLoop, itunesId not passed...)
@AntoineJac thanks for taking time to review the same.
With the new API 1.0 the current integration will not work anymore. Yes it is a breaking change for the publishers but this is more simplified and maintainable.
@anwzhang , and @ppuviarasu . Thanks for the new PR and versions.
I have noticed many points to be fixed with Prebid SDK 1.0 for iOS and Android. I am reviewing the code and will update you soon.
Some points are minors but some are essential as it could broke the current integration (for instance running the completion function the main queue, NSTimer not bound to an NSRunLoop, itunesId not passed...)
@AntoineJac thanks for taking time to review the same. With the new API 1.0 the current integration will not work anymore. Yes it is a breaking change for the publishers but this is more simplified and maintainable.
Closing for Prebid Mobile 1.0 is released.