VRTCAL iOS SDK Integration Guide -- SDK VERSION 1.0.2

Introduction

Thank you for your interest in the VRTCAL iOS SDK! We’re proud to offer a mobile SDK with many publisher-focused features.

Sign up for an account at https://vrtcal.com to download the SDK.

Technical Support

Need help? Please email us at support@vrtcal.com.

You can also find helpful information at https://vrtcal.com.

Table of Contents

• Minimum Requirements
• Installation
• Downloading SDK
• Modify App Delegate
• Update Info.plist
• Showing Banner Ads
• Showing Interstitial Ads
• Important Notes
  • Ad Lifecycle
• GDPR
• Ad Mediation (VRTCAL to MoPub)
• FAQ

Minimum Requirements

The Vrtcal SDK supports iOS 10.0 or higher. Additionally, iOS 9.0 is supported, but ads will not be displayed.

The Vrtcal SDK uses the arm64 Device Capability which excludes:

• iPhone 5
• 1st Generation iPad Mini(2012)
• Other Apple Devices released prior to Autumn 2012

Installation

Installation with CocoaPods

CocoaPods is a dependency manager iOS projects which automates and simplifies installation of 3rd-party libraries. You can install CocoaPods with the following command:

$ gem install cocoapods

To integrate Vrtcal SDK using MoPub as you primary SDK using CocoaPods, add Vrtcal-MoPub-Adapters to your Podfile. Example PodFile:

platform :ios, '9.0'
project 'MyProject.xcodeproj'
target 'MyTarget'
  
pod 'Vrtcal-MoPub-Adapters'

Then run the following command:

$ pod install

Manual Installation

Download the SDK

Download our SDK from https://ui.vrtcal.com/sdk_downloads/VRTCALSDK_iOS_1_0_2.zip and unzip the file. The resulting vrtcal-sdk directory will have the following files:

Add VrtcalSDK.framework to your App

1. Download VrtcalSDK.framework and add it to your projects Frameworks Folder (If the folder doesn't exist, create it).

2. Verify that VrtcalSDK.framework is in Frameworks, Libraries, and Embedded Content and that Embed & Sign is selected.



3. Verify that under Project->Targets(your app)>Build Settings->Search Paths a path in the Framework Search Paths section points to the Frameworks directory:

Modify AppDelegate

In your AppDelegate, import VrtcalSDK and Initialize the SDK with your application ID:

Swift:

VrtcalSDK.initializeSdk(withAppId:1, sdkDelegate:self)

Objective-C:

[VrtcalSDK initializeSdkWithAppId:appId sdkDelegate:self];

Update info.plist

Though the Vrtcal SDK communicates entirely with https some ad content still uses http. In order for these ads to load correctly and to increase revenue, please add an exception to App Transport Security settings:

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

The VRTCAL SDK supports MRAID 3.0 ads which, if the user has interacted with the ad, may ask via a popup to perform an action such as write to the photo album, add a contact to the user’s contact list, or create a calendar event:

<key>NSCalendarsUsageDescription</key>
<string>Some ad content may access calendar</string>
<key>NSContactsUsageDescription</key>
<string>Some ad content may access contacts list</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Some ad content may access photo library</string>

The VRTCAL SDK will not ask the user for access to Location Services but if it is available to the application, it will use location data to enrich ad requests:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Please allow access to Location Services</string>

Showing Banner Ads

1. On the ViewController from which you will be serving ads, import the VrtcalSDK and implement VRTBannerDelegate:

2. Do one of the following:

1. Manually instantiate a VRTBanner:

   let vrtBanner = VRTBanner(frame: CGRect(x:0, y:0, width:320, height:50))

2. 1. Create one in a Storyboard by adding a UIView Object and setting the custom class of the object to VRTBanner:

   

   2. Create an IBOutlet for the banner:

   @IBOutlet var vrtBanner: VRTBanner!

3. Set the banner’s adDelegate and implement all delegate methods. Call loadAd() with the zoneId of your ad. Note: If you need help setting up an ad unit check out the relevant docs here.

  // Ads
    vrtBanner.adDelegate = self
    vrtBanner.loadAd(1)
  

4. If the banner successfully loads it will call vrtBannerAdLoaded and automatically display. If it fails, it will call vrtBannerAdFailedToLoad. Banner refresh rates are controlled server-side and may be adjusted by editing your Vrtcal line item.

Showing Interstitial Ads

1. On the ViewController from which you will be serving ads import the VrtcalSDK and implement VRTInterstitialDelegate:



2. Instantiate a VRTInterstitial and set the adDelegate. Then call loadAd() with the zoneId of your ad unit as an argument:

    
  let vrtInterstitial = VRTInterstitial()
  override func viewDidLoad() {
    super.viewDidLoad()
    // Do any additional setup after loading the view.
    self.vrtInterstitial.adDelegate = self
    self.vrtIntertitial.loadAd(10024)
  }
    
  

3. If the Interstitial successfully loads, vrtInterstitialAdLoaded will be called, at which point showAd may be called on the interstitial object to display the ad. If the interstitial fails to load, vrtInterstitialAdFailed will be called.

    func vrtInterstitialAdLoaded(_ vrtInterstitial: VRTInterstitial) {
      vrtInterstitial.showAd()
    }

    func vrtInterstitialAdFailed(toLoad vrtInterstitial: VRTInterstitial, error: Error) {
      print("error: \(error)")
    }
 

Important Notes

Ad Lifecycle

You can only call loadAd() on VRTBanner or VRTInterstitial once for each instance. If you want to load another ad you must create a new instance. In the case of banners you should remove the old VRTBanner from the view hierarchy and replace it with the new one. This, however, does not apply if you use our SDK's banner refresh mechanism.

GDPR

We support IAB's GDPR framework. Follow IAB's instructions on how to save the user's GDPR settings in IOS NSUserDefaults and/or to integrate their SDK in your project. You should set GDPR settings before you invoke any VRTCAL SDK API functionality.

Ad Mediation

The Vrtcal iOS SDK supports mediation as both a primary SDK (the one doing the mediating) and a secondary SDK (one being mediated, typically MoPub or AdMob). Several mediation adapters are included in the “MediationAdapters” directory of your download:

Mediating Vrtcal SDK through MoPub

1. If you have not done so already, ask your VRTCAL account manager to create your Vrtcal ad unit. Ask for integration parameters and note the App ID and the newly created Zone Id.

2. Create an ad unit & line item on http://mopub.com. Set the following values on the line item:

Banner Example:

3. Please note that it can take about 5 minutes for changes to ad units & line items to take effect.

4. Copy the following 4 files from your Vrtcal_Mobile_SDK download into your app’s Xcode Project:

5. Your MoPub ad unit should now be capable of displaying VRTCAL ads.

FAQ

Q: Where can I reach out for help?

A: Reach out to us at support@vrtcal.com

Q: How do I increase the likelihood that my ad gets filled?

A: There are many factors that affect advertiser interest and spend. Aside from the content type/category of your application, there things that you can do to build and maintain advertiser interest, such as (1) if you are able to include location data; (2) set a refresh rate of 30 seconds or greater; (3) include as much device data that is available; and (4) make sure the ad unit location is a good placement with content.

Q: Why are some ads showing up as blank?

A: This could be for many reasons, it may be an ad that was configured incorrectly by the advertiser, it could be that the ad is using the non-secure HTTP protocol which requires extra configuration to allow ads that use HTTP, or it could we something that need to look into email us at support@vrtcal.com

Q: Does VRTCAL have adapters for other SDKs besides MoPub?

A: The current SDK only includes a MoPub at the moment, but we have others on the way.

Q: Where do I create an Ad Unit?

A: Once you are a registered user on vrtcal.com navigate to the SDK Management section click on the "Add New Ad Unit" button.