Skip to main content
Version: 4.x.x

Getting Started

Overview​

BlueStack-SDK provides functionalities for monetizing your mobile application: from premium sales with rich media, video and innovative formats, it facilitates inserting native mobile ads as well all standard display formats.

You can see : Our Sample, Change Log and Upgrade Guide.

Prerequisites​

check Change Log for Xcode version

Version​

See Change Log and Upgrade Guide.

Guidelines​

See Design Guidelines and Best practices

Demo​

Once you cloned/downloaded the repository, make sure to run pod install before trying to run our Demo.

Help and Troubleshooting​

Help Center Answers to frequently asked questions

Using CocoaPods​

The BlueStack SDK is available through Cocoapods. see Using CocoaPods section.

Using Swift Package Manager​

The BlueStack SDK is available through Swift Package Manager. You can follow these steps :

  • Select the project (1).

  • Select Package Dependencies and click on + (2) and (3) .

SPM

  • Enter this Url (4):
  https://github.com/azerion/BlueStackSDK
  • Add the package (5).

SPM

  • This will show a list of bluestack mediation adapters

BlueStackSDK mediation adapter listBlueStackSDK mediation adapter list

  • Select the mediation adapters that need to be included and add it to the target

BlueStackSDK mediation adapter listBlueStackSDK mediation adapter list

  • Add -ObjC linker flag to the Other Linker Flags build settings of your project target.

SPM

Manual Install​

  • download BlueStack-SDK, you must use the according versions of Ads servers's librairies.

  • drag and drop it in your project

  • check that libBlueStack.a exist in "Link Binary With Libraries"

  • For manual installation without pod, do not forget to include the "-ObjC" linker flag in "Other Linker Flags" under "Build Settings" in the project file." see our Faq

BlueStack SDK needs, these libraries are in demo project :

Note : Make your application comply with the new General Data Protection Regulation (GDPR) law applies in Europe by using any official iab licensed Consent Management Provider (CMP).

adNetworkAdapter​

You must add to your project lib[adNetworkAdapter].a and the adNetwork SDK. You must add all adapters in order to increase fillrate/revenues

Recommended :

  • Google Ads SDK
  • FBAudienceNetwork
  • Smart-Display-SDK (Note : It available as in-App Bidding Bidder)
pod "BlueStack-SDK",:subspecs => ["FBAudienceNetwork","Google-Mobile-Ads-SDK","Smart-Display-SDK"]

Recommended in-App Bidding :

  • AmazonPublisherServicesSDK
  • CriteoPublisherSdk
pod "BlueStack-SDK",:subspecs => ["In-App-Bidding","CriteoPublisherSdk","AmazonPublisherServicesSDK"]

Optional :

  • AdColony
pod "BlueStack-SDK",:subspecs => ["AppLovinSDK","AdColony"]

You can see [Installation guide for Swift]

Bluestack-SDK-Core​

you can use Bluestack-SDK-Core only without the adNetworks SDKs

pod "Bluestack-SDK-Core"

App Transport Security Settings​

App Transport Security improves privacy and data integrity by ensuring your app’s network connections employ only industry-standard protocols and ciphers without known weaknesses. This helps instill user trust that your app does not accidentally leak transmitted data to malicious parties.

MNGAds SDK (with Mediation) are now ATS-compliant, but a small percentage of creatives (near to zero) not directly hosted on our platform are not.

If you must make an exception for a reason, we recommend that you minimize it by only setting the NSAllowsArbitraryLoadsInWebContent and NSAllowsArbitraryLoadsForMedia keys,

<key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoadsForMedia</key>
            <true/>
        <key>NSAllowsArbitraryLoadsInWebContent</key>
            <true/>
    </dict>

On December 21st, Apple announced that they have extended the ATS deadline. Previously, the deadline was January 1, 2017. The new deadline has not yet been announced. Set up the following keys in your app’s info.plist:

<key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>

Building Against iOS9​

iOS 9 introduces changes that are likely to impact your app and its MngAds integration.

  • [Learn what's new in iOS 9 from Apple]
  • One of the changes in iOS9 is a default setting that requires apps to make network connections only over SSL (App Transport Security). Therefore Whitelist Ads Servers for Network Requests, mngAds works under https but not all adNetworks on mediation (smartAdserver, appNexus, facebook, ...). if you want to release apps that build against iOS9, you will need to disable ATS in order to ensure all mediation works too.
<key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>

You can also edit the plist by adding NSAppTransportSecurity key of dictionary type with a dictionary element of NSAllowsArbitraryLoads of boolean type set to �Yes�.

ats.png

  • The SDK supports bitcode. If you are using earlier versions, you must disable bitcode. But for now GoogleMobileAds.framework do not support bitcode, therefore you must disable bitcode for your app

GoogleMobileAdsSdkiOS-7.4.1/GoogleMobileAds.framework/GoogleMobileAds(GADGestureIdUtil.o)' does not contain bitcode. You must rebuild it with bitcode enabled (Xcode setting ENABLE_BITCODE), obtain an updated library from the vendor, or disable bitcode for this target.

  • FBAudienceNetwork.framework and libSmartAdServer.a do not work with Xcode 6.4. Therefore, MngAds needs Xcode 7.

  • GoogleMobileAds.framework: :

Important :You should note that it is mandatory that you add to your .plist file:

<key>GADIsAdManagerApp</key> 
<true/>

  • Sample Application​

Included is a BlueStack sample app to use as example and for help on BlueStack integration. This basic application allows users to test our differents formats.

Important note:​

just run pod install after cloning the demo

Configuring the SDK​

Init the SDK​

You have to init the SDK in AppDelegate.m in application:didFinishLaunchingWithOptions: This must be executed everytime you run the App

// AppDelegate.m
#Since v4.0.0
#import <BlueStackSDK/MNGAdsSDKFactory.h>
#earlier v4.0.0
#import "MNGAdsSDKFactory.h"
...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [MNGAdsSDKFactory initWithAppId:@"YOUR_APP_ID"];
    ...
}

Initialisation Delegate​

BlueStack SDK is configured by server or from last configuration.

set the MNGAdsSDKFactoryDelegate To know when the SDK has finished Initializing you have to use MNGAdsSDKFactoryDelegate.

To check out if the SDK is initialized or not, you have to use [MNGAdsSDKFactory isInitialized]

** - [MNGAdsSDKFactory initWithAppId:@"YOUR_APP_ID"] is mandatory to call each time the app is opened **

// AppDelegate.h
#Since v4.0.0
#import <BlueStackSDK/MNGAdsSDKFactory.h>
#earlier v4.0.0
#import "MNGAdsSDKFactory.h"

@interface AppDelegate : UIResponder <UIApplicationDelegate,MNGAdsSDKFactoryDelegate>



// AppDelegate.m
...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [MNGAdsSDKFactory initWithAppId:@"YOUR_APP_ID"];
    [MNGAdsSDKFactory setDelegate:self];
   
    ...
}

-(void)MNGAdsSDKFactoryDidFinishInitializing{
       //YOUR_APP_IS_READY_TO_SHOW_AD
       //INIT_FACTORIES_AND_USE_THEM_TO_SHOW_ADS;
}

-(void)MNGAdsSDKFactoryDidFailInitializationWithError:(NSError *)error {
    NSLog(@"BlueStack SDK  failed initialization");
}

Adapters status initialization​

you can get the status of every adapter when the BlueStack SDK is initialzed. so, you can implement this method delegate :

-(void)MNGAdsSDKFactoryDidFinishAdaptersInitializing:(BlueStackInitializationStatus *)blueStackInitializationStatus{
    for (BlueStackAdapterStatus* blueStackAdapterStatus in blueStackInitializationStatus.adaptersStatus) {
        NSString* message = [NSString  stringWithFormat:@"adapter name %@ has this status %u with description %@ ", blueStackAdapterStatus.provider , blueStackAdapterStatus.state, blueStackAdapterStatus.descriptionStatus] ;
        NSLog(@"%@", message);
    }
}

isBusy​

Before making a request you have to check that factory not busy (handling old request).

Ads factory is busy means that it has not finished the previous request yet.

isBusy will be setted to true when factory start handling request.

isBusy will be setted to false when factory finish handling request.

example:

if (bannerAdsFactory.isBusy) {
    NSLog(@"Ads Factory is busy");
}else{
    NSLog(@"Ads Factory is not busy");
}
[bannerAdsFactory loadBannerInFrame:CGRectMake(0, 0, 320, 50)]
if (bannerAdsFactory.isBusy) {
    NSLog(@"Ads Factory is busy");
}else{
    NSLog(@"Ads Factory is not busy");
}

Log:

$Ads Factory is not busy
$Ads Factory is busy

Preferences Object​

Preferences object is an optional parameter that allow you select ads by user info. informations that you can set are:

  • age : age of user
  • location : geographical position of the user. Important: your application can be rejected by Apple if you use the device's location only for advertising.
  • language : language of user (ISO code)
  • gender : gender of user
  • keyWord : Use free-form key-values when you want to pass targeting values dynamically into an ad tag based on information you collect from your users. You can also use free-form key-values when there are too many possible values to define in advance. Separator in case of multiple entries is ;.
  • content url : URL for content related to your app (url must be a string which length not exceed 512 caracters).
  • preferredAdChoicesPosition : set the preferred adchoices position , although you need to keep in mind that in some cases it might not position it where mentioned since some of the adnetworks wont take this parameter into consideration , so preferably set the preferred position here as well in the didLoad once the request succeeds.

key=value;key2=value2
#import "MNGPreference.h"
...
MNGPreference * preference = [[MNGPreference alloc]init];
preference.age = 25;
preference.keyword = @"brand=myBrand;category=sport";//Separator in case of multiple entries is ; key=value
preference.gender = MNGGenderFemale;
preference.location = [[CLLocation alloc]initWithLatitude:48.876 longitude:10.453];
[preference setContentUrl:@"your content url"];
[bannerAdsFactory loadBannerInFrame:CGRectMake(0, 0, 320, 50)withPreferences:preference];

Note: this link can help you to get device location.

Error Handling​

@available v2.5 Whenever an Ad fails to load, its correspondent delegate would be invoked providing an NSError object describing what went wrong, what s new in v2.5 and later versions is that we added a new Enum representing the codes of different errors along with a clear description , the different types of error can be found in top of MNGAdsSDKFactory header file :

MAdvertiseError.png

the different errors are pretty much self explanatory , and here s and example use just to remove any ambiguity there might be on how to use it :


-(void)adsAdapter:(MNGAdsAdapter *)adsAdapter nativeObjectDidFailWithError:(NSError *)error{
    NSLog(@"%@",error.localizedDescription); //will log the error's description
    if (error.code == MAdvertiseErrorWrongPlacement) {
        myFactory.placementId = @"Insert the correct placement";
        [myFactory loadNative];
    }
}

Memory managment​

When you have finished your ads plant you must free the memory.

When using ARC it will be done automatically. Otherwise you have to call "releaseMemory".

ARC​
[adsFactory releaseMemory];//optional
adsFactory = nil;

But we recommend to release memory in order to avoid **crashes with a "EXC_BAD_ACCESS" ** for some adNetworks.

No ARC​
[adsFactory releaseMemory];//required
[adsFactory release];
adsFactory = nil;
Avoid crashes​

Some adNetwork does not using Automatic Reference Counting, so you have to mange MNGAdsFactory pointer specially fo interstitial.

  • Do not call releaseMemory on viewDidDisappear

  • you have to call releaseMemory before removing pointer from current instance.

The simplest way is:

  • Calling releaseMemory before setting your property:
    [intersFactory releaseMemory];
    intersFactory = otherFactory;// Or
    intersFactory = [[MNGAdsFactory alloc]init];// Or
    intersFactory = nil;
  • Calling releaseMemory at the dealloc of delegate$
-(void)dealloc{
    [intersFactory releaseMemory];
    intersFactory = nil;
}

Select an ad format​

BlueStack SDK offers a number of different ad formats :