iOS Setup

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:

#import <FBBiddingKit/FBBiddingKit.h>}
3. Set up bidder SDKs:

#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:

@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:

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:

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

// Create Auction
id<FBBKAuction> abAuction = [[FBBKAuctionImpl alloc] initWithBidders:@[facebookBidder]];
3. Set up the delegate:

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:

[auction `startUsingWaterfall`:waterfall];
}

Step 6: A/B Auction

1. For an A/B tested Auction, use this protocol:

@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

• Integration
• Android Setup