Overview

The Appnomix Commerce SDK is a library designed to help brands deepen their relationship with customers by placing the brand prominently on the users' mobile phones.

You can also explore how the SDK is integrated in our Appnomix SwiftUI Sample.

For any questions regarding the integration, please contact [email protected].

Getting Started

Minimum requirements

• iOS 15
• Xcode 15.4

Installing the SDK

• For Automated Xcode Setup refer to the simplified instructions available here.
• For Manual instructions follow the steps described below, organized into two main categories: Safari Extension target Add Safari Extension target and SDK configuration .

Safari Extension target

1. Copy Safari Extension template

Copy Appnomix Safari Extension template to your library.

1. Download the Appnomix.Safari.Extension.xctemplate.zip file from the assets of the latest release.

2. Copy Appnomix.Safari.Extension.xctemplate into the Templates folder:

   1. Open a new Finder window and navigate to the Go menu at the top of the screen.
   2. Select Go to Folder...
   3. In the dialog box that appears, type ~/Library/Developer/Xcode and press Enter.
      
   4. Create a new folder named Templates, or select it if it already exists.
   5. Extract the downloaded file and copy the Appnomix.Safari.Extension.xctemplate to the Templates folder.
   

2) Add New Target

Add New Target to your project, using Appnomix Safari Extension template (see screenshots below).

1. The new target name should be [Your Product] Extension
   
2. Update the extension's name and description by editing the messages.json files located at Resources/_locales/{lang}/messages.json.
3. Set your App Group Name to SafariWebExtensionHandler.swift file:
   
4. Replace the required logos in the Resources/images folder, ensuring the file names remain unchanged.

SDK Configuration

1. Add the SDK to your project

Add the SDK via Swift Package Manager by including the GitHub package in your project.

• Use this source: https://github.com/NomixGroup/ios_commerce_sdk_binary/
• Make sure you select Dependency Rule: Up to Next Major Version

2. Link AppnomixCommerce Framework to Targets

Link AppnomixCommerce library to your main app target and the new created Extension target.

• Make sure you add the library for both targets: Your App and Safari Extension

Starting the SDK

To integrate AppnomixCommerceSDK, you’ll need to update your code in four key areas:

1. Import the AppnomixCommerceSDK.
2. Ensure the AppDelegate and the onboardingEvent variable are properly defined.
3. Integrate the AppnomixOnboardingView screen to boost the adoption rate of the extension.
4. Add the AppnomixCommerceSDK.start function to your AppDelegate as an initializer and adjust your data setup accordingly:
   1. Obtain YOUR_CLIENT_ID and YOUR_AUTH_TOKEN by contacting [email protected].
   2. appGroupName (required) Set the App Group name to enable shared data between the app and the extension.
      • Important note: To ensure that your Safari extension operates effectively, you must activate the App Groups capability for both your app and the extension's targets. You can do this by following the steps outlined here: Configuring App Groups.
   3. appURLScheme (optional) Set the custom URL scheme of your app.
      • Learn how to define a custom URL scheme for your app by visiting: Defining a Custom URL Scheme for Your App.
   4. requestLocation (optional) Set this to true if you want the SDK to request access to the user's location information.
      • Add NSLocationWhenInUseUsageDescription to your Info.plist. For more information, visit: NSLocationWhenInUseUsageDescription.
   5. requestTracking (optional) Set this to true if you want the SDK to request the permission to use data for tracking the user's device. The following instruction is required if this parameter is set to true.
      • Add NSUserTrackingUsageDescription to your Info.plist. For more information, visit: NSUserTrackingUsageDescription.

Sample code

• You can use the code below, to copy and adapt to your application code.

import SwiftUI

import AppnomixCommerce

@main
struct Demo_SwiftUIApp: App {

    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    @State private var onboardingEvent: OnboardingEvent? = .unknown

    var body: some Scene {
        WindowGroup {
            if AppnomixCommerceSDK.isExtensionInstalled() || onboardingEvent == .onboardingDropout || onboardingEvent == .onboardingCompleted {
                ContentView()
            } else {
                AppnomixOnboardingView(onboardingEvent: $onboardingEvent)
            }
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        AppnomixCommerceSDK.start(
            clientID: "YOUR_CLIENT_ID", // ask Appnomix
            authToken: "YOUR_AUTH_TOKEN", // ask Appnomix
            appGroupName: "YOUR_APP_GROUP_NAME", // e.g., group.com.mycompany.myapp
            appURLScheme: "", // e.g., my-app-url://
            requestLocation: true,
            requestTracking: true
        )
        AppnomixCommerce.AnalyticsFacade().trackOfferDisplay(context: "app_start")
        
        return true
    }
}

How to Update the Safari Extension

• For Automated Xcode Setup refer to the simplified instructions available here.
• For Manual instructions follow the steps described below:

1. Download and extract the latest zip file provided in the Safari Extension.
2. Open Finder to access the folder of your Safari Extension within your Xcode project (e.g.[Your Product] Extension)
3. Make sure you backup your customized files:
   1. Resources/_locales.
   2. Resources/images
   3. SafariWebExtensionHandler.swift
4. Replace the contents of the Appnomix Extension with the folder downloaded in step 1.
5. Copy the backed-up files from step 3 back to their respective locations.

Tracking the CTA and installation

Event tracking

• Call theAppnomixCommerce.AnalyticsFacade().trackOfferDisplay function whenever the CTA is displayed, as described in the API Reference.
• To detect successful install and track it, use AppnomixCommerceSDK.isExtensionInstalled() as described API Reference.
• The OnboardingEvent (refer to the code snippet above) allows you to execute custom actions at each stage of the onboarding process and track a user's progress through the onboarding flow as described here.

Customize Onboarding screen

You can customize the colors on the onboarding screen by configuring and adding the AppnomixCustomizationPoints.json file to your project.

Changing the Language

The SDK’s start function accepts a language parameter using ISO 639-1 language codes.

• language (optional) Choose the language for the UI — use en for English, de for German or leave empty to default to the system language.

AppnomixCommerceSDK.start(
    clientID: "YOUR_CLIENT_ID",
    authToken: "YOUR_AUTH_TOKEN",
    appGroupName: "YOUR_APP_GROUP_NAME",
    appURLScheme: "",
    requestLocation: true,
    requestTracking: true,
    language: "en" // available options: "en", "de", or empty for system language
)

API Reference

1. Functions

2. Events

API Usage Declaration

Starting May 1, 2024, Apple mandates that apps utilizing APIs requiring justification must declare them in their app's privacy manifest. Here are the steps to include or update your privacy manifest with the APIs utilized by the Appnomix Extension.

1. Add the PrivacyInfo.xcprivacy file to your Xcode project by following the illustrated steps below:

2. Include the entries detailed below as API types and their corresponding reasons:

3. Here is an example of how the PrivacyInfo.xcprivacy file should look:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">
<dict>
	<key>NSPrivacyAccessedAPITypes</key>
	<array>
		<dict>
			<key>NSPrivacyAccessedAPIType</key>
			<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
			<key>NSPrivacyAccessedAPITypeReasons</key>
			<array>
				<string>1C8F.1</string>
				<string>CA92.1</string>
			</array>
		</dict>
	</array>
</dict>
</plist>

Automated Xcode Setup

The SetupXcode.sh script helps you integrate the Safari extension into your Xcode project and automatically configures all necessary settings for SDK. Just follow these simple steps:

1. Download and unzip SetupXcode.sh.zip file into the same folder as your Xcode project.
2. Place your logo image as logo.png in the same folder as SetupXcode.sh.
3. Open SetupXcode.sh in a text editor and update the APP_GROUPS_NAME variable with your app group identifier.
4. Open Terminal, navigate to the folder, and run the script:

./SetupXcode.sh

Wishing you a smooth integration!