Digital Measurement iOS Swift Package Manager Guide: Difference between revisions

From Engineering Client Portal

No edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 14: Line 14:


== Repository Credentials ==
== Repository Credentials ==
SDK framework packages are stored on a private Github repository.
SDK framework packages are stored on a public Github repository.
To access that you need the credentials received from Nielsen.
To access that you do not need any credentials.
<blockquote>
[[Image:AlertIcon.png|left|60px|link=|class=smallIcon]] Please do not upload any file to github or bitbucket containing the credentials above.
This will automatically lock your access.
</blockquote>
=== Credentials ===
Obtain credentials '''[[Digital Downloads| → here ←]]'''


== 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:
# In the appeared popup please enter the repository address: https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm
# SDK integration using local SPM package
# This a private repo, so the Xcode will immediately show a popup asking for the credentials. Please enter the credentials obtained on the previous step.
# 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(url: "https://github.com/NielsenDigitalSDK/<REPO_NAME>",
                from: "8.2.0")
    ],
    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: "<REPO_NAME>")
            ]
        )
    ]
)
</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(url: "https://github.com/NielsenDigitalSDK/<REPO_NAME>",
                from: "8.2.0")
</syntaxhighlight> For detailes please see: https://developer.apple.com/documentation/swift_packages/package/dependency
# Please specify the <REPO_NAME> parameter according to the product you need for the application, refer the Nielsen AppSDK Products section: e.g. nielsenappsdk-ios-dynamic-spm-global.
<syntaxhighlight lang=Swift>
            dependencies: [
                .product(name: "NielsenAppApi",
                        package: "nielsenappsdk-ios-dynamic-spm-global")
            ]
</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 according to the product you need for the application: https://github.com/NielsenDigitalSDK/<REPO_NAME>. Example: https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-global
# 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.
# 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).
# On the next dialog please select NielsenAppApi product and add it(s) to the particular application build target(s).
<br>
<br>


=== Nielsen AppSDK Versions ===
Notes:<br>
1. We are aware about the Xcode 13.3 issue with SPM integration of the framework where its name does not match the target name: https://stackoverflow.com/questions/71539013/spm-artifact-not-found-for-target-aaa-xcode-13-3-only. <br>
In the release 8.2.0 we have addressed this issue. Please update to the release 8.2.0 if this is happening.<br>
2. In some scenarios after upgrading to the latest SDK release Xcode shows a number of compilation warning/error messages saying that duplicate symbols exist in the code. Please goto menu <File> -> <Packages> and press <Reset Package Caches> if this is happening.<br>
 
== 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 38: Line 97:
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 AppSDK package created for the Swift Package Manager distribution has its own set of XCFramework builds. Each XCFramework is stored on its own repository:<br>


==== Global products ====
=== Global flavors ===
(For 'kids' apps, please use the NoId framework - NielsenNoIdAppSDK)
{| class="wikitable"
{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
|- style="background-color:#efefef;"
! App Flavor Name
! App Flavor !! Repository Name (REPO_NAME)!! Repository URL
|-
|-
| NielsenAppSDK<br>
| Global || '''nielsenappsdk-ios-dynamic-spm-global''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-global
|-
|-
| NielsenNoAdAppSDK<br>
| Global No Ad || '''nielsenappsdk-ios-dynamic-spm-globalnoad''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-globalnoad
|-
|-
| NielsenNoIdAppSDK<br>
| Global No Id (for 'kids' apps) || '''nielsenappsdk-ios-dynamic-spm-globalnoid''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-globalnoid
|}
|}


==== Regional products ====
=== Regional flavors ===
(For 'kids' apps, please use the NoId framework - NielsenAGFNoIdAppSDK)
{| class="wikitable"
{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
|- style="background-color:#efefef;"
! App Flavor Name
! App Flavor !! Repository Name (REPO_NAME)!! Repository URL
|-
|-
| NielsenAGFAppSDK<br>
| AGF || '''nielsenappsdk-ios-dynamic-spm-agf''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agf
|-
|-
| NielsenAGFNoAdAppSDK<br>
| AGF No Ad || '''nielsenappsdk-ios-dynamic-spm-agfnoad''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agfnoad
|-
|-
| NielsenAGFNoIdAppSDK<br>
| AGF No Id (for 'kids' apps) || '''nielsenappsdk-ios-dynamic-spm-agfnoid''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agfnoid
|}
|}


Latest revision as of 18:34, 17 August 2022

Engineering Portal / Digital / Digital Downloads / Digital Measurement iOS Artifactory Guide / 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

SDK framework packages are stored on a public Github repository. To access that you do not need any credentials.

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(url: "https://github.com/NielsenDigitalSDK/<REPO_NAME>",
                 from: "8.2.0")
    ],
    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: "<REPO_NAME>")
            ]
        )
    ]
)
  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(url: "https://github.com/NielsenDigitalSDK/<REPO_NAME>",
                 from: "8.2.0")
    For detailes please see: https://developer.apple.com/documentation/swift_packages/package/dependency
  8. Please specify the <REPO_NAME> parameter according to the product you need for the application, refer the Nielsen AppSDK Products section: e.g. nielsenappsdk-ios-dynamic-spm-global.
            dependencies: [
                .product(name: "NielsenAppApi",
                         package: "nielsenappsdk-ios-dynamic-spm-global")
            ]

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 according to the product you need for the application: https://github.com/NielsenDigitalSDK/<REPO_NAME>. Example: https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-global
  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 select NielsenAppApi product and add it(s) to the particular application build target(s).


Notes:
1. We are aware about the Xcode 13.3 issue with SPM integration of the framework where its name does not match the target name: https://stackoverflow.com/questions/71539013/spm-artifact-not-found-for-target-aaa-xcode-13-3-only.
In the release 8.2.0 we have addressed this issue. Please update to the release 8.2.0 if this is happening.
2. In some scenarios after upgrading to the latest SDK release Xcode shows a number of compilation warning/error messages saying that duplicate symbols exist in the code. Please goto menu <File> -> <Packages> and press <Reset Package Caches> if this is happening.

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 AppSDK package created for the Swift Package Manager distribution has its own set of XCFramework builds. Each XCFramework is stored on its own repository:

Global flavors

App Flavor Repository Name (REPO_NAME) Repository URL
Global nielsenappsdk-ios-dynamic-spm-global https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-global
Global No Ad nielsenappsdk-ios-dynamic-spm-globalnoad https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-globalnoad
Global No Id (for 'kids' apps) nielsenappsdk-ios-dynamic-spm-globalnoid https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-globalnoid

Regional flavors

App Flavor Repository Name (REPO_NAME) Repository URL
AGF nielsenappsdk-ios-dynamic-spm-agf https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agf
AGF No Ad nielsenappsdk-ios-dynamic-spm-agfnoad https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agfnoad
AGF No Id (for 'kids' apps) nielsenappsdk-ios-dynamic-spm-agfnoid https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agfnoid

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.

Retrieved from "https://engineeringportal.nielsen.com/w/index.php?title=Digital_Measurement_iOS_Swift_Package_Manager_Guide&oldid=5932"