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.

Version 2.0 introduces significant enhancements including product detection, price comparison features, and a completely overhauled user interface. Version 1.0 focused primarily on coupon functionality.

On iOS, the SDK uses a Safari Web Extension to interact with web content in Safari browser. This requires users to enable the extension through Safari settings, which is handled by the SDK's onboarding flow.

Key Links

• 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 AppnomixCommerce.
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 AppnomixCSDK.initialize 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.
5. Call theAppnomixCSDK.trackOfferDisplay function whenever the CTA is displayed, as described in the API Reference.

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 !AppnomixCSDK.isOnboardingAvailable() || onboardingEvent == .onboardingDropout || onboardingEvent == .onboardingCompleted {
                ContentView()
            } else {
                AppnomixOnboardingView(onboardingEvent: $onboardingEvent)
            }
        }
    }
}

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

Updating 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.

Event Tracking

Tracking Offer Display

Call the AppnomixCSDK.trackOfferDisplay function whenever the CTA is displayed to your users. The function accepts a string parameter representing the context in which the offer was shown, such as "home screen", "special offers", "level complete", or "daily rewards" based on what's relevant to your app.

AppnomixCSDK.trackOfferDisplay(context: "home_screen")

Installation Verification

To detect successful installation and track it, use AppnomixCSDK.isExtensionInstalled() which returns true if extension usage was detected in the last 14 days.

if AppnomixCSDK.isExtensionInstalled() {
    // Extension is active
}

Event Listeners

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:

• OnboardingEvent.onboardingStarted - Triggered when the onboarding screen is shown
• OnboardingEvent.onboardingDropout - Triggered if onboarding is exited early
• OnboardingEvent.onboardingCompleted - Triggered when onboarding completes and extension is installed

Customization

UI Customization

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

Language Selection

The SDK's initialize function accepts a language parameter using ISO 639-1 language codes. Choose the language for the UI use en for English, de for German, or leave empty to default to the system language.

AppnomixCSDK.initialize(
    clientId: "YOUR_CLIENT_ID",
    authToken: "YOUR_AUTH_TOKEN",
    appGroupName: "YOUR_APP_GROUP_NAME",
    options: .init(
        appURLScheme: "",
        language: "en" // available options: "en", "de", or empty for system language
    )
)

API Reference

Functions

Events

Testing & Support

Attribution Testing

To ensure that the SDK integration is working correctly and that attribution is being tracked properly, please contact us at [email protected]. We can verify that:

• Events are being tracked correctly
• User attribution is working as expected
• The integration is configured properly

What's Next

If the integration is successful and the user has enabled the Safari Extension, when visiting supported websites, users will see:

• Automatic coupon detection and application
• Product price comparison (v2.0+)
• Product availability tracking (v2.0+)
• Deal notifications

Troubleshooting

Common Issues

If you encounter issues during integration, check the following:

1. Extension not appearing in Safari

   • Verify that the App Group is configured for both your app and extension targets
   • Ensure the extension target is included in your build scheme
   • Check that the user has completed the onboarding flow

2. Onboarding not showing

   • Verify AppnomixCSDK.isOnboardingAvailable() returns true
   • Check that your clientId and authToken are correct
   • Ensure AppnomixCSDK.initialize() is called before attempting to show onboarding

3. Events not tracking

   • Verify that trackOfferDisplay is being called with a valid context string
   • Check that the SDK has been initialized before calling tracking functions
   • Contact [email protected] to verify server-side tracking

Error Codes

The SDK logs error codes to help diagnose integration issues. All errors are logged to the console, and critical errors are reported to Appnomix servers to help diagnose integration issues.

Note: For any errors not listed here or if you need additional assistance, please contact [email protected] with the error code and relevant details from your logs.

Privacy & Permissions

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!