Difference between revisions of "Digital Measurement iOS Swift Package Manager Guide"

From Engineering Client Portal

(Repository Credentials)
Line 20: Line 20:
 
<br>
 
<br>
  
== SDK integration using the SPM ==
+
== SDK integration ==
# Nielsen AppSDK can be integrated to an application in the Xcode from the menu: File -> Swift Packages -> Add Package Dependency...
+
Two approaches of the SDK integration are applicable for SPM:
 +
# SDK integration using local SPM package
 +
# SDK integration using the Xcode project settings
 +
 
 +
=== SDK integration using local package ===
 +
Nielsen AppSDK can be integrated to an application by setup local SPM package with dependencies the remote Nielsen SDK package.
 +
# In the Xcode from the menu go to: File -> New -> Package... - to create the new local package by specifying it's name and location.
 +
# Close the Xcode instance with the just created package.
 +
# In the Xcode with the application project from the menu go to: File -> Add Packages... -> Add local... - to add local package into the application project by specifying the package folder.
 +
# In order to integrate the local package into your application open your application targets’ General settings tab. In the "Frameworks, Libraries, and Embedded Content" section tap: + -> Workspace -> <Package Name> -> <Package Name> -> Add.
 +
# In the Xcode in the Project Navigator go to: <Project Name> -> Packages -> <Package Name> -> Package.swift - to open SPM package manifest file in Xcode editor.
 +
# Update the package manifest with a minimal template below to use the remote Nielsen SDK package as a dependency: <syntaxhighlight lang=Swift>
 +
// swift-tools-version:5.3
 +
// The swift-tools-version declares the minimum version of Swift required to build this package.
 +
 
 +
import PackageDescription
 +
 
 +
let package = Package(
 +
    name: "<Package Name>",
 +
    products: [
 +
        // Products define the executables and libraries a package produces, and make them visible to other packages.
 +
        .library(
 +
            name: "<Package Name>",
 +
            targets: ["<Package Name>"]),
 +
    ],
 +
    dependencies: [
 +
        // Dependencies declare other packages that this package depends on.
 +
        // .package(url: /* package url */, from: "1.0.0"),
 +
        .package(name: "NielsenAppApi",
 +
                url: "https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm",
 +
                      .branch("master"))
 +
    ],
 +
    targets: [
 +
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
 +
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
 +
        .target(
 +
            name: "<Package Name>",
 +
            dependencies: [.product(name: "NielsenAppApi", package: "NielsenAppApi")]
 +
        ),
 +
    ]
 +
)
 +
</syntaxhighlight>
 +
# In the package definition statement decide whether your project dependency accepts updates up to the next major version or up to the next minor version. To be more restrictive, select a specific version range or an exact version. <syntaxhighlight lang=Swift>
 +
        .package(name: "NielsenAppApi",
 +
                url: "https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm",
 +
                      .branch("master"))
 +
</syntaxhighlight> For detailes please see: https://developer.apple.com/documentation/swift_packages/package/dependency
 +
# In the dependencies product statement please choose package product you need for the application in the '''name:''' parameter.
 +
<syntaxhighlight lang=Swift>
 +
            dependencies: [.product(name: "NielsenAppApi", package: "NielsenAppApi")]
 +
</syntaxhighlight>
 +
 
 +
For an additional technical details please refer to: https://developer.apple.com/documentation/xcode/creating_a_standalone_swift_package_with_xcode
 +
 
 +
=== SDK integration using the Xcode project settings ===
 +
Nielsen AppSDK can be integrated to an application by setup the remote SDK package in the Xcode project settings explicitly.
 +
# In the Xcode from the menu go to: File -> Swift Packages -> Add Package Dependency... - to setup the remote Nielsen SDK package.
 
# In the appeared popup please enter the repository address: https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm
 
# In the appeared popup please enter the repository address: https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm
 
# On the next screen please define an SDK version for integration. There are options available for the selection. Decide whether your project accepts updates to a package dependency up to the next major version or up to the next minor version. To be more restrictive, select a specific version range or an exact version.
 
# On the next screen please define an SDK version for integration. There are options available for the selection. Decide whether your project accepts updates to a package dependency up to the next major version or up to the next minor version. To be more restrictive, select a specific version range or an exact version.
Line 27: Line 83:
 
<br>
 
<br>
  
=== Nielsen AppSDK Versions ===
+
== Nielsen AppSDK Versions ==
 
iOS/tvOS AppSDK has 4 digits in the version numbers, but the SPM packages should conform to semantic versioning and contain only 3 digits in the version number. Please use only 3 first digits while specifying the exact version of the SDK:
 
iOS/tvOS AppSDK has 4 digits in the version numbers, but the SPM packages should conform to semantic versioning and contain only 3 digits in the version number. Please use only 3 first digits while specifying the exact version of the SDK:
 
<syntaxhighlight lang=Javascript>
 
<syntaxhighlight lang=Javascript>
Line 34: Line 90:
 
Nielsen AppSDK is available for distribution through the Swift Package Manager starting from 8.0.0.0 version only.
 
Nielsen AppSDK is available for distribution through the Swift Package Manager starting from 8.0.0.0 version only.
  
=== Nielsen AppSDK products ===
+
== Nielsen AppSDK products ==
 
Each specific version of the Nielsen AppSD package created for the Swift Package Manager distribution has its own set of XCFramework builds - products:<br>
 
Each specific version of the Nielsen AppSD package created for the Swift Package Manager distribution has its own set of XCFramework builds - products:<br>
  
==== Global products ====
+
=== Global products ===
(For 'kids' apps, please use the NoId framework - NielsenNoIdAppSDK)
+
(For 'kids' apps, please use the NoId framework - NielsenNoIdAppApi)
 
{| class="wikitable" style="width: 30%;"
 
{| class="wikitable" style="width: 30%;"
 
|- style="background-color:#efefef;"
 
|- style="background-color:#efefef;"
 
! App Flavor Name
 
! App Flavor Name
 
|-
 
|-
| NielsenAppSDK<br>
+
| NielsenAppApi<br>
 
|-
 
|-
| NielsenNoAdAppSDK<br>
+
| NielsenNoAdAppApi<br>
 
|-
 
|-
| NielsenNoIdAppSDK<br>
+
| NielsenNoIdAppApi<br>
 
|}
 
|}
  
==== Regional products ====
+
=== Regional products ===
(For 'kids' apps, please use the NoId framework - NielsenAGFNoIdAppSDK)  
+
(For 'kids' apps, please use the NoId framework - NielsenAGFNoIdAppApi)  
 
{| class="wikitable" style="width: 30%;"
 
{| class="wikitable" style="width: 30%;"
 
|- style="background-color:#efefef;"
 
|- style="background-color:#efefef;"
 
! App Flavor Name
 
! App Flavor Name
 
|-
 
|-
| NielsenAGFAppSDK<br>
+
| NielsenAGFAppApi<br>
 
|-
 
|-
| NielsenAGFNoAdAppSDK<br>
+
| NielsenAGFNoAdAppApi<br>
 
|-
 
|-
| NielsenAGFNoIdAppSDK<br>
+
| NielsenAGFNoIdAppApi<br>
 
|}
 
|}
  

Revision as of 16:03, 28 October 2021

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png Digital Downloads breadcrumbArrow.png Digital Measurement iOS Artifactory Guide breadcrumbArrow.png Digital Measurement iOS Swift Package Manager Guide

The Nielsen AppSDK can either be downloaded directly or can be integrated within an application through the use of a CocoaPods, Carthage or Swift Package Manager.

How to integrate Nielsen SDK in iOS/tvOS application using Swift Package Manager

Initially the Swift Package Manager (SPM) was created as a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies. However, starting from the Swift 5.3 it allows to add binary dependencies and to import proprietary, closed-source libraries into applications also.

Swift Package Manager Installation

The Swift Package Manager is available as a part of the Xcode application for MacOS. We recommend to use the Xcode version 12.x with Swift 5.3 that is the minimum required version of Swift with binary dependencies support. Apple Xcode can be downloaded and installed using Mac App Store application or from the Apple web site (https://developer.apple.com/account) in the Downloads section.

XCFramework package

Swift Package Manager only supports XCFramework type of package for binary distribution. This a new type of package supported by Apple. It has a number of benefits against the fat library packaged into a framework. First of all it allows to combine device and simulator slices into one package and it is not needed to write custom run scripts to exclude simulator slices from the embedded frameworks before deploying apps. Also XCFramework allows to combine binaries for different platforms, like iOS, tvOS, MacOS. Nielsen SDK added support for XCFramework packages and they are now available for SPM distribution.

Repository Credentials

The first step is to add the credentials received from Nielsen into your .netrc file.

AlertIcon.png

Starting on Sept 21, 2021 the Nielsen SDK has moved to a public repository. Credentials are no longer required.


SDK integration

Two approaches of the SDK integration are applicable for SPM:

  1. SDK integration using local SPM package
  2. SDK integration using the Xcode project settings

SDK integration using local package

Nielsen AppSDK can be integrated to an application by setup local SPM package with dependencies the remote Nielsen SDK package.

  1. In the Xcode from the menu go to: File -> New -> Package... - to create the new local package by specifying it's name and location.
  2. Close the Xcode instance with the just created package.
  3. In the Xcode with the application project from the menu go to: File -> Add Packages... -> Add local... - to add local package into the application project by specifying the package folder.
  4. In order to integrate the local package into your application open your application targets’ General settings tab. In the "Frameworks, Libraries, and Embedded Content" section tap: + -> Workspace -> <Package Name> -> <Package Name> -> Add.
  5. In the Xcode in the Project Navigator go to: <Project Name> -> Packages -> <Package Name> -> Package.swift - to open SPM package manifest file in Xcode editor.
  6. Update the package manifest with a minimal template below to use the remote Nielsen SDK package as a dependency:
    // swift-tools-version:5.3
    // The swift-tools-version declares the minimum version of Swift required to build this package.
    
    import PackageDescription
    
    let package = Package(
        name: "<Package Name>",
        products: [
            // Products define the executables and libraries a package produces, and make them visible to other packages.
            .library(
                name: "<Package Name>",
                targets: ["<Package Name>"]),
        ],
        dependencies: [
            // Dependencies declare other packages that this package depends on.
            // .package(url: /* package url */, from: "1.0.0"),
            .package(name: "NielsenAppApi",
                     url: "https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm",
                           .branch("master"))
        ],
        targets: [
            // Targets are the basic building blocks of a package. A target can define a module or a test suite.
            // Targets can depend on other targets in this package, and on products in packages this package depends on.
            .target(
                name: "<Package Name>",
                dependencies: [.product(name: "NielsenAppApi", package: "NielsenAppApi")]
             ),
        ]
    )
    
  7. In the package definition statement decide whether your project dependency accepts updates up to the next major version or up to the next minor version. To be more restrictive, select a specific version range or an exact version.
            .package(name: "NielsenAppApi",
                     url: "https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm",
                           .branch("master"))
    
    For detailes please see: https://developer.apple.com/documentation/swift_packages/package/dependency
  8. In the dependencies product statement please choose package product you need for the application in the name: parameter.
            dependencies: [.product(name: "NielsenAppApi", package: "NielsenAppApi")]

For an additional technical details please refer to: https://developer.apple.com/documentation/xcode/creating_a_standalone_swift_package_with_xcode

SDK integration using the Xcode project settings

Nielsen AppSDK can be integrated to an application by setup the remote SDK package in the Xcode project settings explicitly.

  1. In the Xcode from the menu go to: File -> Swift Packages -> Add Package Dependency... - to setup the remote Nielsen SDK package.
  2. In the appeared popup please enter the repository address: https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm
  3. On the next screen please define an SDK version for integration. There are options available for the selection. Decide whether your project accepts updates to a package dependency up to the next major version or up to the next minor version. To be more restrictive, select a specific version range or an exact version.
  4. On the next dialog please choose package product(s) you need for the application and add it(s) to the particular application build target(s).


Nielsen AppSDK Versions

iOS/tvOS AppSDK has 4 digits in the version numbers, but the SPM packages should conform to semantic versioning and contain only 3 digits in the version number. Please use only 3 first digits while specifying the exact version of the SDK:

8.0.0.0 -> 8.0.0

Nielsen AppSDK is available for distribution through the Swift Package Manager starting from 8.0.0.0 version only.

Nielsen AppSDK products

Each specific version of the Nielsen AppSD package created for the Swift Package Manager distribution has its own set of XCFramework builds - products:

Global products

(For 'kids' apps, please use the NoId framework - NielsenNoIdAppApi)

App Flavor Name
NielsenAppApi
NielsenNoAdAppApi
NielsenNoIdAppApi

Regional products

(For 'kids' apps, please use the NoId framework - NielsenAGFNoIdAppApi)

App Flavor Name
NielsenAGFAppApi
NielsenAGFNoAdAppApi
NielsenAGFNoIdAppApi

Frameworks for tvOS platform do not have their specific repositories as they are distributed as part of the same XCFramework. The following SDK versions are now available for distribution through SPM:
8.0.0

More details about SPM integration can be found in the official Apple documentation: https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app
Please note: Nielsen AppSDK is distributed through SPM as dynamic framework only.

Additional Resources for Swift Package Manager

For more information on Swift Package Manager or How to integrate the package into an application here.