Before you get started...

Our newest iOS SDK (since 4.0.8) was released in support of the newest Xcode 8.0. Please ensure you are using Xcode 8.0 or higher to ensure smooth integration.

If you haven't already done so, head over to our dashboard and add your app to your account. You need to do this so that you can get your Application ID that you’ll be adding to your app with our SDK. For example in the image, it’s circled in red and will be found on your app’s page. It can match the Reporting API ID for new applications. Existing applications created using 'search' can have a different Application ID and Reporting API ID, which is ok. (for mediation the Reporting API 'key' is found on the User account details page)

Now let's get started.

The Vungle iOS SDK isn't included in the sample code we have linked. Download it from the Vungle dashboard, extract the archive and follow these steps.

1. Add the Vungle framework to your Xcode project

There are two ways to add Vungle to your Xcode project: using Cocoapods, or manual integration.

Cocoapods

If you're familiar with Cocoapods, you can quickly add Vungle to your project by adding :

pod "VungleSDK-iOS", "4.1.0"

to your Podfile. Please make sure you put down the correct version number for the SDK version you want ("4.1.0" in line above). If you omit the version number, then the latest version will be installed. In the above After that a quick pod install run should update your project with the latest version of our iOS SDK! At this point you can skip down to Step 2 in our guide.

Manual Integration

1a. Add the VungleSDK.embeddedFramework to your project

Find the extracted files, then drag & drop the VungleSDK.embeddedFramework directory into Xcode under Frameworks.

IMPORTANT: The VungleSDK.embeddedframework folder should be added as a group (yellow folder) and not as a reference (blue folder).

1b. Add Other Required Frameworks

The Vungle SDK require a few other native frameworks to be linked to your project, so click on your project and head to:

General > Linked Frameworks and Libraries

Many of these frameworks will already be included, as they are default for most Xcode projects, but be sure to add any of the following that are not already included:

AdSupport.framework

AudioToolbox.framework

AVFoundation.framework

CFNetwork.framework

CoreGraphics.framework

CoreMedia.framework

Foundation.framework

libz.dylib or libz.tbd

libsqlite3.dylib or libsqlite3.tbd

MediaPlayer.framework

QuartzCore.framework

StoreKit.framework

SystemConfiguration.framework

UIKit.framework

WebKit.framework

It's also a good idea to check that the VungleSDK framework appears under Linked Frameworks and Libraries. If the previous drag & drop step didn't link it automatically, we can manually add it by clicking the '+' and then 'Add Other'.

1c. Add the-ObjC linker flag

This can be added by navigating to Build Settings and adding -ObjC to Other Linker Flags in the Linking section

2. Remove the iOS status bar

This isn’t a required step, but it is recommended, as keeping the status bar at bay ensures that Vungle's ad interaction and presentation perform smoothly. To remove the status bar, open up your Info.pList and add the key "View controller-based status bar appearance" and set it to "No".

3. Application Transport Security (ATS)

Starting in iOS 9 (with builds made from Xcode 7), Application Transport Security requires all network traffic made from an app to be secured via HTTPS. You can read more about it in our Vungle iOS 10 Transition Guide. Vungle iOS SDK is fully ready for the ATS change, and all traffic from the Vungle SDK will use HTTPS by January 1, 2017. Before then, we suggest setting your NSAllowsArbitraryLoads value to YES.

4. Add the code!

4a. Initialize the SDK

It's important to initialize the SDK as soon as possible to ensure that an ad has been pre-cached in time for the user. For our sample project (and our recommendation for all iOS projects), we'll add our initialization call to the didFinishLaunchingWithOptions method on our main AppDelegate.

NOTE: If you try to import the VungleSDK.h and it is not found, remove the reference and add it again with the option "Copy items if needed" selected.

4b. Play ads in your ViewControllers

With the SDK initialized previously in the AppDelegate's didFinishLaunchingWithOptions, we can present an ad to the user by simply adding the following code snippet to your top presenting ViewController

NOTE: startWithAppId method should only be called once. Calling it more than once may lead to undefined behavior.

4c. Show ads in the top-most ViewController class

The NSError parameter will be updated to include any error information in the event that a problem occurred during ad presentation.

NOTE: ViewController for playAd method should be the top-most ViewController in view hierarchy, otherwise it will lead to undefined behavior.

4d. Resume playing audio

Check out our Advanced Settings Guide to subscribe to play events. These can be used to unpause audio, resume gameplay, etc.

NOTES:

Test mode: While your app is in Test mode, you will not be able to download any of the apps advertised. Additionally, the Dashboard will not report the number of impressions. This is because test ads are used only to verify that you have integrated the SDK correctly. This functionality becomes available once your app has gone live in active mode.

Replay button: Vungle has removed the endcard Replay button for iOS in SDK versions higher than 4.0.x. If the button remains on an ad unit, its replay functionality will no longer work.

Advanced settings

If you're interested in some of the more advanced details of the Vungle iOS SDK (customization, event listeners, etc) feel free to check out our Advanced Settings Guide.