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.framework
into 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.
iSoma.h
(located in iSoma.framework
> Headers) and uncomment the @import lines.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
orNSPhotoLibraryUsageDescription
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"
Please make sure to use the exact naming format for the
"IABUSPrivacy_String"
and to review the IAB’s guidelines for entering and formatting the U.S. Privacy String (CCPA Opt-Out Storage Format).Our sample provided above (“1YNN”) for the US Privacy String demonstrates when the user has not made a choice to opt-out.
Further Examples of the U.S. Privacy String
1YNN: User has not made a choice to opt-out
1NYY: User has made a choice to opt-out
1—: A Digital Property has determined to use a U.S. Privacy string version 1 and that CCPA does not apply to the transaction.
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:
- A publisher notifies the Smaato sales department (or emails Smaato legal department) that they have an application directed towards children OR
- 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
Last Modified: February 20, 2020 at 1:35 pm
© 2005-2020 Smaato, Inc. All Rights Reserved. Smaato® is a registered trademark of Smaato, Inc.