SDK Integration

This SDK is developed in Swift and supports integration with Swift Package Manager (SPM). For new projects, we recommend integrating the Netmera Swift SDK to optimize functionality and streamline development.

Onboarding Checklist: Swift

Below is the Onboarding Checklist for Swift and Flutter. Follow each item in the list to ensure all essential steps in your Netmera onboarding process are completed successfully.

Netmera Mobile Technical Onboarding Checklist (Swift & Flutter).xlsx

44KB

Open

How to Integrate Netmera Swift SDK: A Complete Video Guide

Step 1: Create an Apple Push Notification Certificate

To enable push notifications, Netmera uses APNS (Apple Push Notification Service). Follow these steps to create and upload the required certificate:

1. Log in to developer.apple.com with your Apple Developer account.

2. Generate an Apple Push Notification Certificate for your app.

3. Export the certificate using Keychain Access on your Mac.

4. Upload the exported certificate to the Netmera panel by navigating to Developer > Push Backends > iOS in the left menu.

Bundle IDs should match on your project, certificate and panel:

Ensure that the certificate you upload to the panel matches the bundle ID of your project. Additionally, set your project's bundle ID in the panel to ensure consistency. The bundle ID of your project, the certificate, and the one specified in the panel must all align.

Push Notification Certificate Types

1. p8 Certificate

For P8 certificates, select both Sandbox & Production environments since a single P8 certificate works for both. If only one environment (e.g., Production) is selected, a BadEnvironmentKeyInToken error occurs when testing in the sandbox.

1. p12 Certificate

Create separate certificates for each environment.

1. Apps Built from Xcode

When building apps from Xcode, set the certificate type to dev.

If you encounter issues with push notifications, check the certificate type in the Developer > Push Backends > iOS section.

Environment	Certificate Type	Certificate Format	Notes
Production & Test	Sandbox & Production	p8	This single certificate type works for both environments when using the p8 format.
Production	Production	p12	Separate certificates should be created for different environments when using the p12 format.
Test	Sandbox	p12	Separate certificates should be created for different environments when using the p12 format.
App Built Directly from Xcode	Development (dev)	p8/p12	Must be set to dev.

Creating an APNS .p8 Certificate (Recommended)

Using the APNS .p8 certificate is highly recommended for the following reasons:

1. The .p8 certificate is mandatory for enabling features such as Live Activities.

2. Unlike .p12 certificates, a single .p8 certificate can manage push notifications for multiple applications.

3. The .p8 certificate does not require yearly renewal.

4. The .p8 certificate is easier to generate via the Apple Developer Portal and only needs to be downloaded once.

Creating an APNS .p12 Certificate

Step 2: Integrate SDK into Your Project

Requirements

• Xcode 13 or later

• iOS 11.0 or later

You can integrate the Netmera SDK into your project using either Swift Package Manager (SPM) or Cocoapods. Follow the instructions for your chosen method.

Swift SDK Modules – Select the modules you need

Netmera Swift SDK is modular. Include only the modules your app needs in the appropriate targets.

Module	Purpose	Target
NetmeraNotification	Manages push permission flow, token registration, delegate methods, and deep link handling.	App
NetmeraAnalytic	Allows sending analytics events to Netmera.	App
NetmeraAnalyticsAutotracking	Tracks screen transitions and user actions automatically.	App
NetmeraNotificationInbox	Enables the push inbox feature.	App
NetmeraLocation	Provides location–based functionalities.	App
NetmeraGeofence	Enables geofence monitoring.	App
NetmeraAdvertisingId	Provides access to IDFA/IDFV (AdTracking).	App
NetmeraLiveActivity	Enables ActivityKit-based Live Activities (iOS 16.1+).	App
NetmeraNotificationServiceExtension	Required for Media / Rich Push rendering.	Notification Service Extension
NetmeraNotificationContentExtension	Enables custom push UIs such as Carousel & Slider Push.	Notification Content Extension

Option 1: Integrating with Swift Package Manager (SPM)

1. Open Project Settings and navigate to Package Dependencies. Click the "+" button to add a new dependency.

1. Enter the following repository URL in the search bar. The package details will load automatically.

https://github.com/Netmera/swift-sdk

1. Click "Add Package" to complete the integration.

Option 2: Integrating with Cocoapods

1. Make sure your Podfile includes the necessary Netmera SDK modules, along with any other dependencies you need. Here’s an example:

target 'YourAppTargetName' do
  ...
  # Pods for Netmera Modules
  pod "NetmeraAnalytic" // to use Netmera analytic features
  pod "NetmeraAnalyticAutotracking" // to use auto tracking features
  pod "NetmeraNotification" // to use Netmera push notification features
  pod "NetmeraAdvertisingId" // to use Netmera advertising identifier features
  pod "NetmeraLocation" // to use Netmera location features
  pod "NetmeraGeofence" // to use Netmera geofence features
  pod "NetmeraNotificationInbox" // to use Netmera push inbox features
  pod "NetmeraLiveActivity" // to use Netmera live activity features
  ...
end

1. After listing all your pod dependencies, add the following post_install block to the end of your Podfile.

post_install do |installer|
  installer.pods_project.targets.each do |target|
    if target.name.include?('Swinject')
      target.build_configurations.each do |config|
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end
end

1. Run pod install command in your terminal.

pod install

Step 3: Setup Netmera

Import the Netmera Framework

In your AppDelegate.swift file, import the necessary Netmera modules based on the features you plan to use:

import NetmeraAnalytic
import NetmeraNotification
import NetmeraLocation
import NetmeraNotificationInbox
import NetmeraAdvertisingId

Notes for SwiftUI projects:

For SwiftUI projects, the AppDelegate.swift file is not included by default. Instead, SwiftUI uses an App struct marked with @main to manage the application lifecycle.

You can adapt your implementation by creating an AppDelegate class and integrating it into the App struct if needed.

Initialize Netmera

1. Configure with Netmera Plist

1. Add the Netmera-Config.plist file to your project.

2. Ensure the file is included in the correct Target Membership (main target + extensions if applicable).

1. Replace the placeholders ({API_KEY}, {AppGroupName}, etc.) in the following code snippet with your actual values:

To obtain your SDK API Key, follow these steps:

1. Go to the Netmera Panel.

2. Navigate to Developer > API > SDK API Key.

3. Copy your SDK API Key from this section.

Use this key to replace the {API_KEY} placeholder in either the Netmera-Config.plist or your programmatic setup.

<?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>sdk_params</key>
        <dict>
            <key>api_key</key>
            <string>your_api_key</string>
        </dict>
    </dict>
</plist>

Further Plist Configurations

Source Code View

<?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>sdk_params</key>
    <dict>
      <key>app_group_name</key>
      <string>{AppGroupName}</string>
      <key>api_key</key>
      <string>{API_KEY}</string>
      <key>custom_events</key>
      <array>
        <string>{YourCustomEvent}</string>
      </array>
    </dict>

    <key>location_max_active_region</key>
    <string></string>

    <key>in_app_message_settings</key>
    <dict>
      <key>TextColor</key>
      <string>{hexcolor. For ex-> 16777215}</string>
      <key>TitleColor</key>
      <string>{hexcolor. For ex-> 16777215}</string>
      <key>BackgroundColor</key>
      <string>{hexcolor. For ex-> 16777215}</string>
      <key>CancelButtonBackgroundColor</key>
      <string>{hexcolor. For ex-> 16777215}</string>
      <key>TitleFont</key>
      <string>{font family name. ex -> ariel}</string>
      <key>TextFont</key>
      <string>{font family name. ex -> ariel}</string>
      <key>CancelButtonRadius</key>
      <string>{10 sd px}</string>
      <key>ShadowOpacity</key>
      <string>{0-1}</string>
      <key>BottomPaddingRatio</key>
      <string>{between 0.01 - 1}</string>
      <key>CancelButtonImage</key>
      <string>{imagename}</string>
    </dict>

    <key>blacklist_screen_names</key>
    <array/>
  </dict>
</plist>

SDK Config Parameters

sdk_params

• app_group_name: iOS App Group name for data sharing with extensions.

• api_key: Project-specific Netmera API key.

• custom_events: List of custom events to track (e.g., PurchaseCompleted).

location_max_active_region

Max number of active regions for location tracking (optional).

in_app_message_settings

Customize in-app message appearance:

• TextColor, TitleColor, BackgroundColor, CancelButtonBackgroundColor

• TitleFont, TextFont

• CancelButtonRadius, ShadowOpacity, BottomPaddingRatio

• CancelButtonImage

blacklist_screen_names

Screens excluded from auto-tracking.

Property List View

Additional Configuration for On-Premises Customers

If you are using Netmera in an on-premises environment, include the following in your Netmera-Config.plist:

<key>base_url</key>
<string>{BaseURL}</string

For Multiple Targets

If your project contains multiple targets you can manage this by copying the correct configuration file during build time.

Add the following script as a Run Script Phase in your app target:

if [ "${CONFIGURATION}" == "Debug" ]; then
    CONFIG_FILE="${PROJECT_DIR}/NetmeraSwiftDemo/Netmera-Config-Debug.plist"
else
    CONFIG_FILE="${PROJECT_DIR}/NetmeraSwiftDemo/Netmera-Config-Release.plist"
fi
        
BUNDLE_PATH="${PROJECT_DIR}/NetmeraSwiftDemo/Netmera-Config.plist"

cp "${CONFIG_FILE}" "${BUNDLE_PATH}"

This ensures that the correct Netmera-Config.plist file is bundled based on the active build configuration.

⚠️ Make sure the script runs before the app is built, and that Netmera-Config.plist is included in the target bundle.

2. Initialize Netmera

Call the Netmera initialization method in your application(_:didFinishLaunchingWithOptions:) method:

Netmera.initialize()  
Netmera.setLogLevel(.debug) // Options: .debug, .info, .error, .fault  
// Use .debug mode to view detailed Netmera logs

Optional: Initialization Callback

Important Note: To use the initialization callback method, make sure you are using Swift SDK v4.19.0 or later.

Use the initialization callback to listen for init session results, including available user segments and initialization errors.

Add the following code to handle init session success and failure:

let initSessionCallBack: (Result<NetmeraInitSessionInfo, Error>) -> Void = { [weak self] result in
        switch result {
        case let .success(info):
          // handle info, i.e logic depending on info.segments
          break
        case let .failure(error):
          // handle error
          break
        }
      }
      // should be set before or right after the "Netmera.initialize" call in "didFinishLaunchingWithOptions"
      Netmera.setInitSessionCallback(initSessionCallBack)

Network Request Callback

Important Note: To use the network request callback, make sure you are using Swift SDK v4.27.0 or later.

You can watch the network requests the SDK sends and see whether each one succeeded or failed. Register one callback with Netmera.setNetworkRequestCallback(_:). Pass nil to remove the callback.

Netmera.setNetworkRequestCallback { result in
  switch result.outcome {
  case .success:
    print("\(result.requestType.name) succeeded")
  case .failure(let failure):
    print("\(result.requestType.name) failed: \(failure.errorCode ?? "") \(failure.message)")
  }
}

To remove the callback:

Netmera.setNetworkRequestCallback(nil)

Failure Details

• failure.statusCode: the HTTP status code, or nil when there was no HTTP response (for example, offline or timeout).

• failure.errorCode: Netmera's own error code when the server returns one, otherwise the HTTP status code, or the SDK's own error code when there was no HTTP response.

• failure.message: the server's error message.

Retries

• A failed attempt that the SDK will retry is reported with failure.willRetry == true. Use result.isFinal to handle only final outcomes.

Threading

The callback runs on a background queue, one result at a time. Switch to the main queue before updating UI.

Configuring Multiple Environments

If you want to configure multiple environments for your app (e.g., testing and production), follow the steps below:

Step 1: Copy Netmera-Config.plist Files

1. Copy the Netmera-Config.plist file for the development environment into the Dev directory.

2. Copy the Netmera-Config.plist file for the production environment into the Prod directory.

3. When adding these files to your Xcode project, uncheck Copy items if needed and ensure that no targets are selected under Add to targets.

Step 2: Add Run Script Phase

1. In Xcode, select your app target.

2. Go to the Build Phases tab and add a New Run Script Phase.

3. Name the new phase something like "Setup Netmera Environment Netmera-Config.plist".

4. Position this phase before the Copy Bundle Resources step.

Step 3: Implement Shell Script for Config File Selection

In the new Run Script Phase, implement the following shell script to copy the correct Netmera-Config.plist based on the build configuration (Debug or Release):

The following script checks if the development and production versions of Netmera-Config.plist exist in their respective directories, and based on the build configuration (Debug or Release), it will copy the correct configuration file into the app bundle.

# Name of the resource we're selectively copying
NETMERA_CONFIG_PLIST=Netmera-Config.plist

# Get references to dev and prod versions of the Netmera-Config.plist
# NOTE: These should only live on the file system and should NOT be part of the target (since we'll be adding them to the target manually)
NETMERA_CONFIG_DEV=${PROJECT_DIR}/${TARGET_NAME}/NetmeraConfig/Dev/${NETMERA_CONFIG_PLIST}
NETMERA_CONFIG_PROD=${PROJECT_DIR}/${TARGET_NAME}/NetmeraConfig/Prod/${NETMERA_CONFIG_PLIST}

# Make sure the dev version of Netmera-Config.plist exists
echo "Looking for ${NETMERA_CONFIG_PLIST} in ${NETMERA_CONFIG_DEV}"
if [ ! -f $NETMERA_CONFIG_DEV ]
then
    echo "No Development Netmera-Config.plist found. Please ensure it's in the proper directory."
    exit 1
fi

# Make sure the prod version of Netmera-Config.plist exists
echo "Looking for ${NETMERA_CONFIG_PLIST} in ${NETMERA_CONFIG_PROD}"
if [ ! -f $NETMERA_CONFIG_PROD ]
then
    echo "No Production Netmera-Config.plist found. Please ensure it's in the proper directory."
    exit 1
fi

# Get a reference to the destination location for the Netmera-Config.plist
PLIST_DESTINATION=${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app
echo "Will copy ${NETMERA_CONFIG_PLIST} to final destination: ${PLIST_DESTINATION}"

# Copy over the prod Netmera-Config.plist for Release builds
if [ "${CONFIGURATION}" == "Release" ]
then
    echo "Using ${NETMERA_CONFIG_PROD}"
    cp "${NETMERA_CONFIG_PROD}" "${PLIST_DESTINATION}"
else
    echo "Using ${NETMERA_CONFIG_DEV}"
    cp "${NETMERA_CONFIG_DEV}" "${PLIST_DESTINATION}"
fi

Swift SDK Integration Complete

The Swift SDK integration is complete, and your devices are now ready to receive the following types of push notifications from the Netmera Dashboard:

1. Standard Push Notifications

2. Interactive Push Notifications

3. Widgets

4. Push Notifications with Deeplinks