Engineering Portal / Digital / US DCR & DTVR / DCR Video iOS SDK / DCR Video iOS SDK xcframework

The Nielsen SDK xcframework bundle

Setting up your Development Environment

Obsolete "Fat" Frameworks

Prior to SDK Version 8.1.0.0 the iOS framework has been distributed as a static and dynamic "fat" framework. It was a framework that contained all the required architectures for devices and simulators. A single binary file had slices like the following: arm7 or arm64 for iPhone, x86-64 for Macs. Since the architectures for iPhones did not overlap with the architecture for Macs, the linker would never get tripped up over which binary to use for a given target. In November 2020, Apple started releasing Macs with a new class of hardware called the M1, which has a CPU that uses the arm64 architecture. So now the corresponding binary file would have slices like the following: arm64 for iPhone and arm64 for Mac. They have the same architecture name, but the code for each target is very different. The iOS simulator has different rules than the iPhone, it is not possible to run a binary built for one on the other. The previous way to link binary frameworks, lipo, is unable to deal with a merged binary containing multiple binaries that share the same architecture.

xCode 12 building errors

Developers who uses "fat" framework in their apps started reporting the following error that they get building the app in xCode 12.3+:

Building for iOS Simulator, but the linked and embedded framework 'MyFramework.framework' was built for iOS + iOS Simulator.

The binary framework contains different code for the same architecture in multiple places, and Xcode doesn’t know how to handle it. There is workaround that people recommend to use in such cases:

IPA processing failure

Assertion failed: Expected 4 archs in otool output:

The error above is due to the "fat" (simulator+device) framework which will not appear if you have not enabled Bitcode. To build your app with full Bitcode support, it is recommended that you use a XCFramework.

New way of packaging - XCFramework

As a solution for the problems described above Apple recommends to use XCFrameworks. In XCFramework, we no longer build a single framework with multiple architectures. Instead, we build one small framework for each combination of architecture and target and store it in its own folder. The top-level XCFramework folder have folders like ios-arm64, ios-arm64-simulator, etc. Each of these folders is its own framework, complete with headers, modules, and binary.

Benefits of XCFramework

As mentioned above XCFramework allows to combine small frameworks created for different architectures in one package even if the same architecture is used for different platforms like iPhone and Mac. This division into individual frameworks means you no longer have to use build script in the application for stripping slices before uploading to AppStore.

But there are other benefits. Previously we distributed iOS and tvOS versions of the Nielsen SDK as separate frameworks, but now it is possible to combine frameworks created for those platforms in one XCFramework and distribute them as a single package. Moreover, starting from the release 8.1.0.0 the Nielsen SDK will support Mac Catalyst builds and the framework slices needed for that support will be a part of the same XCFramework also.

Usage of "Fat" Frameworks

Note: For clients who still have reasons to keep using the old framework packages in the application and do not migrate to XCFramework we distribute "fat" frameworks both static and dynamic for the release 8.1.0.0. Nielsen will stop distributing "fat" frameworks for future releases and distribute the Nielsen iOS SDK as an XCFramework only.
If you build an app with "fat" framework on a Mac with Apple M1 chip and if you see this error: “Building for iOS Simulator, but linking in dylib built for iOS, file for architecture arm64.”, please use the following workaround. In the Build Setting for your application target please find a setting named Exclude Architectures. Both Debug and Release, change to Any iOS Simulator SDK – arm64.

Initially Nielsen AppSDK has been distributed as a static library packaged into framework bundle format. Starting from the release 6.2.0.0 it has been transformed into dynamic framework (static framework is still available).

If migrating from the static library to a dynamic framework, once implemented, unless your specific application requires, you can remove the following Frameworks that were once required: [AdSupport, JavascriptCore, SystemConfiguration, Security, AVFoundation, libc++]

The dynamic framework was created as a fat framework. It means that it contains slices required for devices (armv7, arm64) as well as slices required for simulators (i386, x86_64). Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. The example of the shell script that should be added as a Run Script phase in the application can be found below.

Migration to XCFramework

We highly recommend to migrate to XCFramework for all our clients. Apple forces developers to use XCFramework also. Starting in Xcode 12.3 it is not possible to build the app with "fat" frameworks without workarounds. Soon, Apple will require all developers to use Xcode 12 for code signing, at which point clients which have not migrated to XCFrameworks will not be able to release new app versions.

If migrating from the static library, once implemented, unless your specific application requires, you can remove the following Frameworks that were once required: [AdSupport, JavascriptCore, SystemConfiguration, Security, AVFoundation, libc++]

If migrating from the dynamic library, please remove the run script used for removing the simulator slices before publishing to AppStore. For XCFrameworks it is not needed.

Obtaining the NielsenAppApi.xcframework

The Nielsen AppSDK can either be downloaded and integrated directly or can be integrated through the use of the SDK Dependency Managers for iOS. We recommend using the integration through the SDK Dependency Managers whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.

Configuring Xcode Development Environment

The Nielsen App SDK is compatible with Apple iOS versions 9.0 and above. In addition, when using XCFramework or dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

Note: All communications between the SDK and the Census (Collection Facility) use HTTPS.

Download Framework

The first step is to download and copy the NielsenAppApi.xcframework bundle to the app project directory. (Not required if using Dependency Managers)

Add Framework

In the General tab for app configuration add NielsenAppApi.xcframework in the list of Embedded Binaries. (Not required if using Dependency Managers) If you migrate from a "fat" framework to an XCFramework just remove the existing NielsenAppApi.framework from that list first.

Add Path

Add path to the NielsenAppApi.xcframework in the Framework Search Paths build setting. (Not required if using Dependency Managers)

Import Framework

Add NielsenAppApi.xcframework module in the source file of your app:

Using Swift

Add the following:

import NielsenAppApi

Using Objective-C

@import NielsenAppApi;

DCR Video iOS SDK xcframework

From Engineering Client Portal