Getting Started with iOS SDK

iOS SDK Prerequisites

  • Applications using iOS 8.0 or above
  • Applications using Xcode 9.0 or above

Integrate the Smaato iOS SDK

To download the latest version of our iOS SDK, log in to your SPX account, go to the user menu (next to your email address) in the top right corner and select Integration Options. Please also find the integration documentation below once you have downloaded the SDK. Lastly, by using our SDK you must agree to the terms and conditions.

Option 1: Using Cocoapods

To simplify dependency management, add the following line in your Podfile before executing pod install: pod 'SmaatoSDK'

Option 2: Zipped Package Source

In the unzipped folder, you will find a file called iSoma.framework:

Drag and drop the iSoma.framework file and SMAMoatMobileAppKit.frameworkinto your Xcode application group/project navigator. As shown in this example below.

You will also need to add -ObjC as Other Linker Flags in Build Settings.

Special Instructions for iOS 10

The iOS SDK supports iOS 10 but comes with updated integration steps. Publishers need to update their applications info.plist file with the following settings:

For MRAID – Removal of “Create Calendar Event Entry” and “Save Photo in Photo Library” Functionality

  • The SDK has now removed the MRAID calendar event creation as well as saving a photo to photo library functionality completely.
  • Publishers do not need to add NSCalendarsUsageDescription or NSPhotoLibraryUsageDescription in the project .plist file anymore.

Update ‘Privacy Settings’ in the Info.plist File

  • NSLocationWhenInUseUsageDescription
  • This key is required only if the publisher wants the SDK to monitor the user’s location:
[iSoma setGPSEnabled:YES];

App Transport Security

MRAID 2.0 Limitations

Smaato does not support the following in  iOS SDK:

    • createCalendarEvent()
    • storePicture()
    • "Two-part" ads

Update ATS Settings in the Info.plist File

Make sure to set the following key file in the Info.plist of your app: NSAllowsArbitraryLoads: Yes

To use the Smaato SDK, please don’t add the following keys to your .plist file:

  • NSAllowsArbitraryLoadsForMedia
  • NSAllowsArbitraryLoadsInWebContent
  • NSAllowsLocalNetworking

In iOS 10 and later, and macOS 10.12 and above, the value of the key NSAllowsArbitraryLoads is ignored. This results in an effective value for this key of its default value of NO if any of the following keys are present in your app’s Info.plist file.

Changes for the GPS location handling

Apple recently enforced the policy related to the guidelines which may result in an app rejection. The following reason is usually provided: “Your app’s code references one or more APIs that access sensitive user data. The app’s Info.plist file should contain a NSLocationWhenInUseUsageDescription key with a user-facing purpose string explaining clearly and completely why your app needs the data.” Starting from this version of the iOS SDK, we changed the way how the GPS location is handled in the SDK. If your app is not collecting the location data, you don’t need to do anything as long as you are using the latest SDK.

In case if your app is gathering location data and feeding it to the SDK. In order to send more targeted ads using the location data from the user, you need to request authorization to use location services inside your app, following Apple’s configurations guidelines, depending on the authorization level that you choose:

For When-In-UseAuthorization Please refer to this link.
For Always-Authorization: PleasePlease refer to this link

Also to enable monitoring GPS data on Smaato SDK side by calling:

[iSoma setGPSEnabled:YES];

Configure User Properties

You can configure the user profile to individual ads or to global by updatingadView.adSettings.userProfile or [iSoma userProfile]with the respective properties.

The properties and possible values are shown here:

Property name Possible values Description
age Integer value Age of the user
gender

SOMAUserGenderFemale

SOMAUserGenderMale

Gender of the user
region String Region of the user
zip String Zip code of the user
  • yearlyIncome
  • ethnicity,
  • education,
  • interestedIn,
  • maritalStatus,
  • country,
  • countrycode,
  • city

General Data Protection Regulation (GDPR)

As a publisher, you should integrate a Consent Management Platform (CMP) and request for vendor and purpose consents as outlined in IAB Europe’s Mobile In-App CMP API v1.0: Transparency & Consent Framework. You can find a reference implementation of a web-based CMP and the corresponding native wrappers here in the IAB’s GDPR Transparency and Consent Framework.

If you are embedding your own custom CMP, the collected end-user consent information needs to be stored in NSUserDefaults using the following keys:

Key Type Description
IABConsent_CMPPresent boolean Set to YES if a CMP that follows the IAB specification is present in the application.
IABConsent_SubjectToGDPR String “1” = Subject to GDPR
“0” = Not subject to GDPR
“-1” = Unknown (default before initialization)
IABConsent_ConsentString String Base64-encoded consent string as defined in by the IAB: Consent string and vendor list format v1.1
IABConsent_ParsedPurposeConsents String String of “0”s and “1”s, where the character at position N indicates the consent status to purposeID N as defined in the Global Vendor List
IABConsent_ParsedVendorConsents String String of “0”s and “1”s, where the character at position N indicates the consent status to vendorID N as defined in the Global Vendor List

Example Code

[[NSUserDefaults standardUserDefaults] setObject:@"0" forKey:@"IABConsent_SubjectToGDPR"]; // User is not subject to GDPR

Important Details About CCPA

The California Consumer Privacy Act (CCPA) was created to provide California consumers with greater transparency and control over their personal information. In many ways, the CCPA is a first of its kind regulation in the United States that seeks to create broad privacy and data protection rules that apply to all industries doing business in the jurisdiction of California, rather than focusing on a single sector or specific data collection and use practices.

For more information about the CCPA regulation, please check out the Smaato FAQ. You can also review the IAB’s U.S. Privacy String documentation.

For Publishers with California-Based Users

As a publisher, you need to make sure to request consent from California-based users (to give or refuse consent / to opt-out or opt-in) about private data transfer. This answer should be saved in NSUserDefaults with key “IABUSPrivacy_String” in the US Privacy String format (CCPA Opt-Out Storage Format).

Sample of US Privacy String Saving in NSUserDefaults

As per the guidelines defined by IAB for CCPA, publishers are required to set CCPA value for key IABUSPrivacy_String inside NSUserDefaults.

[NSUserDefaults.standardUserDefaults setObject:usString forKey:@"IABUSPrivacy_String]; // for example "1YNN"

Children’s Online Privacy Protection Act (COPPA)

“COPPA” stands for The Children’s Online Privacy Protection Rule. It imposes certain requirements on Publishers (operators of websites or online services) with apps/sites directed to children under 13 years of age, and on operators of other websites or online services (i.e., Smaato) that have actual knowledge (defined below) that they are collecting personal information online from a child under 13 years of age.

Enabling COPPA

COPPA can be enabled or disabled like this:

adSettings.coppaEnabled = YES;

// default is set to NO

When should the COPPA Flag be set to COPPA=1?

If the publisher doesn’t have an age, or even if the publisher has an age gate, Smaato may need to flag the publisher’s application as COPPA=1:

  1. A publisher notifies the Smaato sales department (or emails Smaato legal department) that they have an application directed towards children OR
  2. If Smaato notices that a publisher’s application is very obviously directed to children under 13 (e.g., the application has “for Kids” in the name, features animation, or has other indicators that the app is for children).

If the publisher has an age gate, such that the age of the end-user is known, then:

  • Age gate says end-user is <13, then the publisher must send the COPPA=1 flag;
  • Age gate says end-user is ≥13, then the publisher should send the COPPA=0 flag.

Integrating Swift

From version 8.0 onward, the Smaato iOS SDK comes with a built-in Swift module structure.

Simply drag and drop the framework to the Swift project and you are ready to start. Bridging headers will not be required.

Using the Smaato Demo App

Within the SDK ZIP file, there’s a demo app that shows an example of how to integrate our SDK, how to use it and how to implement desired options.

The demo app allows you to:

    • Use your Publisher and Adspace ID.
    • Request multiple adspaces (text, image, rich media, medium rectangle, video)
    • Configure refresh time
    • See how a banner, can be used across multiple screens
    • Use a classic BannerView
    • Use a full-screen banner
    • Use an interstitial banner
    • Use a toaster banner
    • See how to implement banners directly from your XML layout

Modified: February 20, 2020 at 1:35 pm