Bidding with In-House Mediation

iOS Setup

In-house mediation is not publicly available

In-house bidding with Audience Network is currently in Closed Beta and is not publicly available. We'll provide further updates if this changes.

As an alternative, you can access Audience Network Bidding through one of the mediation platforms we partner with.

Integration

Step 1: Configuration

  1. Drag and drop FBBiddingKit.framework into your project, select Copy items if needed and choose a target in Add to targets (if needed).
  2. Import FBBiddingKit by adding the following umbrella header:
    3. #import <FBBiddingKit/FBBiddingKit.h>}
  3. Set up bidder SDKs:
    4. #import <AppLovinSDK/AppLovinSDK.h>
#import <Tapjoy/Tapjoy.h>
#import <FBAudienceNetwork/FBAudienceNetwork.h>

// Initializing AppLovin SDK
[[ALSdk shared] initializeSdk];

// Initializing Tapjoy SDK
[Tapjoy connect:@"TAPJOY_SDK_KEY"];

// Initializing Chartboost SDK
[Chartboost startWithAppId:@"CHARTBOOST_APP_ID" appSignature:@"CHARTBOOST_APP_ID" completion:**nil];**

// Initializing Facebook Audience Network SDK
[FBAudienceNetworkAds initializeWithSettings:nil completionHandler:nil];
  4. Initialize Bidding Kit: 
    // Initializing BiddingKit
FBBKConfiguration *configuration = [[FBBKConfiguration alloc] init];
configuration.auctionTimeout = 10;
configuration.verboseLoggingEnabled = YES;
[FBBKBiddingKit initializeWithConfiguration:configuration];

Step 2: Waterfall and WaterfallEntry

  1. Implement the following protocols for waterfall logic using waterfall entry as abstract entity abstraction: 
    2. @protocol FBBKWaterfall <NSObject>
- (id<FBBKWaterfall>)createWaterfallCopy;
/*!
 * @discussion Creates waterfall entry from bid, inserts and sort to keep order
 * @param bid Bid object with information that is needed to create an WaterfallEntry
 */
- (void)insertEntryUsingBid:(FBBKBid *)bid;
/*!
 * @discussion Inserts the given WaterfallEntry into the Waterfall. Should be sorted afterwards
 * @param entry Waterfall Entry to insert
 */
- (void)insertEntry:(id<FBBKWaterfallEntry>)entry;
/*!
 * @discussion Provides a an array of waterfall entries inside current waterfall
 * @return Array of presented waterfall entries
 */
- (NSArray<id<FBBKWaterfallEntry>> *)entries;
@end
    @protocol FBBKWaterfallEntry <NSObject>
/*!
 * @discussion Provides a bid for current Waterfall Entry, if it exists
 * @return Stored bid value if presented or nil otherwise
 */
@property (nonatomic, readonly, nullable) FBBKBid *bid;
/*!
 * @discussion Cost Per Thousand for current Waterfall Entry
 * @return CPM in cents
 */
@property (nonatomic, readonly) double CPMCents;
/*!
 * @discussion Entry Name for current Waterfall Entry
 * @return Name of Entry that provided bid
 */
@property (nonatomic, readonly) NSString *entryName;
@end
  2. Create waterfall and provide historical CPM:
    3. id<FBBKWaterfall> waterfall = [[Waterfall alloc] init];
[waterfall insertEntry:[[WaterfallEntry alloc] initWithName:@"NetworkA" cpm:0.3]];
[waterfall insertEntry:[[WaterfallEntry alloc] initWithName:@"NetworkB" cpm:0.2]];

Step 3: ABTest and ABTestSegment

  1. Implement A/B testing supporting protocols: 
    @protocol FBBKABTest <NSObject>
/*!
 * @discussion Equally splits the users into different segments
 * @return Segment for a current user
 */
@property (nonatomic, readonly) id<FBBKABSegment> currentSegment;
@end
    @protocol FBBKABSegment <NSObject>
/*!
 * @discussion Segment identifier for current segment
 */
@property (nonatomic, readonly) NSString *segment;
@end
  2. Create A/B Segments and Tests:
    3. id<FBBKABTest> abtest = [[ABTest alloc] init];
id<FBBKABSegment> testA = [[ABSegment alloc] initWithSegment:@"A"];
id<FBBKABSegment> control = [[ABSegment alloc] initWithSegment:@"B"];
[abtest addSegment:testA];
[abtest addSegment:control];

Step 4: Bidder

  1. Implement bidders, or use predefined bidders that conform to protocols: 
    @protocol FBBKBidder <NSObject>
/*!
 * An Identifier for a bidder
 */
@property (nonatomic, readonly) NSInteger identifier; 
/*!
 * This method will return a name for bidder
 */
@property (nonatomic, readonly, copy) NSString *bidderName;
/*!
 * Provides bid asynchronously
 */
- (void)retrieveBidComplete:(void (^)(FBBKBid *_Nullable bid))complete;
/*!
 * Provides bid asynchronously
 */
- (void)retrieveBidComplete:(nullable void (^)(FBBKBid *bid))complete
                     failed:(nullable void (^)(NSError *_Nullable error))failed;
@end
  2. Set up the bidders that you going to use.
    NOTE: In order to get bidderToken you need to integrate FBAudienceNetwork.framework: 
    #import <FBAudienceNetwork/FBAdSettings.h>

// Provide required values for Facebook Bidder
NSString *appId = @"YOUR_APP_ID";
NSString *placementId = @"YOUR_PLACEMENT_ID";
NSString *bidToken = [FBAdSettings bidderToken];
FBBKFacebookAdBidFormat adBidFormat = FBBKFacebookAdBidFormatInterstitial;

// Create parameters for Facebook Bidder
FBBKFacebookBidderParameters *parameters =
  [[FBBKFacebookBidderParameters alloc] initWithAppId:appId
                                          placementId:placementId
                                          adBidFormat:adBidFormat
                                             bidToken:bidToken];
// Setup additional fields if needed
parameters.testMode = YES;

// Create Facebook Bidder
FBBKFacebookBidder *facebookBidder = [[FBBKFacebookBidder alloc] initWithParameters:parameters];

Step 5: Auction

  1. Follow the protocol for Auction: 
    @protocol FBBKAuction <NSObject>
/**
 * An integer indentifier for a particular FBBKAuction
 */
@property (nonatomic, readonly) NSInteger auctionId;
/**
 * Delegate for FBBKAuction instance. Set up for listenening to updates and notifications
 */
@property (nonatomic, nullable, weak) id<FBBKAuctionDelegate> delegate;
/**
 * Starts running the Auction with the given bidders FBBKBidder.
 * This method will run the auction asynchronously and will return immediately.
 * This method can be called only once.
 *
 * Bidders are added to an auction through (see -[FBBKAuctionImpl initWithBidders:];)
 * When the auction is finished, we will return a waterfall copy
 * (see -[FBBKWaterfall createWaterfallCopy];) which will include the results of the bids
 * of the auction results.
 * All bidders in the auction run in parallel and all start at the same time.
 * They are all given the same timeout defined by the configuration set in
 * (see +[FBBiddingKit initializeWithConfig:] method. Bidders that do not obtain a bid in the provided
 * time slot will not be considered for the auction, even if they return a bid later.
 *
 * @param waterfall The waterfall we want to use for this FBBKAuction
 */
- (void)startUsingWaterfall:(id<FBBKWaterfall>)waterfall;
/**
 * Must be called just before an ad is displayed. Notifies bidders of the demand source
 * (real-time or not) that has eventually displayed the ad. This is later used to estimate
 * ARPDAU by bidding kit and is necessary for optimisations
 *
 * @param winnerEntry the winning FBBKWaterfallEntry which is being shown on screen
 */
- (void)notifyDisplayWinner:(id<FBBKWaterfallEntry>)winnerEntry;
@end

/**
 * This is an FBBKAuctionDelegate
 * We use it to notify about the auction completion
 */
@protocol FBBKAuctionDelegate <NSObject>
@optional
/**
 * This method will be called when the Auction is completed
 *
 * @param auction Auction which notified about completion
 * @param waterfall The waterfall with the updated bidders.
 */
- (void)fbbkAuction:(id<FBBKAuction>)auction didCompleteWithWaterfall:(id<FBBKWaterfall>)waterfall;
@end
  2. Create the auction and pass the bidders
    3. // Create Auction
id<FBBKAuction> abAuction = [[FBBKAuctionImpl alloc] initWithBidders:@[facebookBidder]];
  3. Set up the delegate:
    4. auction.delegate = self; // become a delegate to handle callbacks
    - (void)fbbkAuction:(id<FBBKAuction>)auction didCompleteWithWaterfall:(id<FBBKWaterfall>)waterfall
{
    // TODO: use waterfall to show ads
}
  4. Start the auction, pass the test and waterfall:
    5. [auction `startUsingWaterfall`:waterfall];
}

Step 6: A/B Auction

  1. For an A/B tested Auction, use this protocol:
    2. @protocol FBBKABAuction <NSObject>
/*!
 * @discussion An integer indentifier for a particular A/B Auction
 * @return Identifier of an auction
 */
@property (nonatomic, readonly) NSInteger abAuctionId;
/*!
 * @discussion Delegate for A/B Auction instance. Set up for listenening to updates and notifications
 */
@property (nonatomic, weak, nullable) id<FBBKABAuctionDelegate> delegate;
/*!
 * @discussion Chooses an A/B auction for segment and starts it with values provided by waterfall
 * @param test A/B test for this auction
 * @param waterfall Interface for providing waterfall entries
 */
- (void)startWithABTest:(id<FBBKABTest>)test waterfall:(id<FBBKWaterfall>)waterfall;
/*!
 * @discussion Should be invoked after displaying winner
 * @param winnerEntry FBBKWaterfallEntry which wins in current auction
 */
- (void)notifyDisplayWinner:(id<FBBKWaterfallEntry>)winnerEntry;
@end

@protocol FBBKABAuctionDelegate <NSObject>
@optional
- (void)fbbkabAuction:(id<FBBKABAuction>)abAuction didCompleteWithWaterfall:(id<FBBKWaterfall>)waterfall;
@end
  2. Create the auction, and pass the bidders: 
    // Create Auction
id<FBBKABAuction> abAuction = [[FBBKABAuctionImpl alloc] initWithBidders:@{
    testA : @[facebookBidder],
    control : @[],
}];
  3. Setup the delegate: 
    auction.delegate = self; // become a delegate to handle callbacks
    - (void)fbbkabAuction:(id<FBBKABAuction>)abAuction didCompleteWithWaterfall:(id<FBBKWaterfall>)waterfall
{
    // TODO: use waterfall to show ads
}
  4. Start the auction, pass the test and waterfall 
    [auction startWithABTest:abtest waterfall:waterfall];

Sample Code

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Initializing BiddingKit
    FBBKConfiguration *configuration = [[FBBKConfiguration alloc] init];
    configuration.auctionTimeout = 10;
    configuration.verboseLoggingEnabled = YES;
    [FBBKBiddingKit initializeWithConfiguration:configuration];
}

- (void)createAuction
{    
    // create and setup waterfall
    id<FBBKWaterfall> waterfall = [[Waterfall alloc] init];
    [waterfall insertEntry:[[WaterfallEntry alloc] initWithName:@"NetworkA" cpm:0.3]];
    [waterfall insertEntry:[[WaterfallEntry alloc] initWithName:@"NetworkB" cpm:0.2]];
    
    // Provide required values for Facebook Bidder
    NSString *appId = @"YOUR_APP_ID";
    NSString *placementId = @"YOUR_PLACEMENT_ID";
    NSString *bidToken = [FBAdSettings bidderToken];
    FBBKFacebookAdBidFormat adBidFormat = FBBKFacebookAdBidFormatInterstitial;    

    // Create parameters for Facebook Bidder
    FBBKFacebookBidderParameters *parameters =
     [[FBBKFacebookBidderParameters alloc] initWithAppId:appId
                                             placementId:placementId
                                               bidFormat:adBidFormat
                                                bidToken:bidToken];
    // Setup additional fields if needed
    parameters.testMode = YES;

    // Create Facebook Bidder
    FBBKFacebookBidder *facebookBidder = [[FBBKFacebookBidder alloc] initWithParameters:parameters];

    // Create Auction
    _abAuction = [[FBBKABAuctionImpl alloc] initWithBidders:@[facebookBidder]];
    _abAuction.delegate = self;
    
    // Start Auction
    [_abAuction startWithWaterfall:waterfall];
}

#pragma mark - FBBKABAuctionDelegate
- (void)fbbkAuction:(id<FBBKABAuction>)abAuction didCompleteWithWaterfall:(id<FBBKWaterfall>)waterfall;
{
    // waterfall contains your original waterfall entries
    // along with the real time bids

    // Our waterfall implementation is sorted by CPM, so first entry
    // has the highest price
    id<FBBKWaterfallEntry> winnerEntry = waterfall.entries.firstObject;

    // kFBBKFacebookBidderName -> 'FACEBOOK_BIDDER'
    if ([winnerEntry.entryName isEqualToString:kFBBKFacebookBidderName]) {
        FBBKBid *bid = entry.bid;
        // Create the rewarded video unit with a placement ID (generate your own on the Facebook app settings).
        // Use different ID for each ad placement in your app.
        self.rewardedVideoAd = [[FBRewardedVideoAd alloc] initWithPlacementID:bid.placementId withUserID:@"user123" withCurrency:@"gold"];
        // Set a delegate to get notified on changes or when the user interact with the ad.
        self.rewardedVideoAd.delegate = self;
        [self.rewardedVideoAd loadAdWithBidPayload:bid.payLoad];

        // wait till ads is loaded in -interstitialAdDidLoad: callback
    } else {
        // Handle other networks
    }
}

#pragma mark - FBInterstitialAdDelegate
- (void)interstitialAdDidLoad:(FBInterstitialAd *)interstitialAd
{
    id<FBBKWaterfallEntry> winnerEntry = ...
    // Call notifyDisplayWinner before an ad is displayed
    [abAuction notifyDisplayWinner:winnerEntry];
    
    // Display ad
    [self showAdFromBid:entry.bid];
}

See Also