iMessage extension setup

Use this guide when your product includes an iMessage app extension (Messages extension) and you want Adtrace to track sessions and events inside that extension.

Complete Getting started with the iOS SDK for your main iOS app first. This page covers the additional steps for the iMessage target.

Example reference: AdtraceExample-iMessage.

Before you start

Topic	What to do
Main app	Finish SDK install, frameworks, and appDidLaunch in the host app.
App token	Create a separate app in the Adtrace panel and use its app token in the iMessage extension.
Why a separate token?	The host app and iMessage extension run in different memory spaces with different bundle IDs. The same token in both places creates two independent SDK instances and can mix dashboard data.

1. Add the SDK to your iMessage target

Choose the integration path that matches how you added the SDK to your main app.

From source

If you add the Adtrace SDK from source to the iMessage target, set the preprocessor macro ADTUST_IM=1 in the iMessage extension target settings.

1. In Xcode, select your iMessage extension target.
2. Open Build Settings.
3. Search for Preprocessor Macros (or GCC_PREPROCESSOR_DEFINITIONS).
4. Add ADTUST_IM=1 for Debug and Release.

Preprocessor macro

ADTUST_IM=1

As a framework

If you use the iMessage-specific framework:

1. Add AdtraceSdkIm.framework to your iMessage extension target.
2. In Build Phases, add a Copy Files phase (or use an existing one).
3. Set the destination to Frameworks.
4. Add AdtraceSdkIm.framework so it is copied into the extension bundle at build time.

2. Initialize the SDK in the extension

Initialize Adtrace in your iMessage extension the same way as in a standard app: create an ADTConfig with your iMessage app token and call appDidLaunch when the extension starts.

Use the iMessage-specific app token from the panel, not the host app token.

Objective-C

MessagesViewController.m

#import "Adtrace.h"

- (void)viewDidLoad {
    [super viewDidLoad];

    NSString *yourAppToken = @"{YourIMessageAppToken}";
    NSString *environment = ADTEnvironmentSandbox;
    ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken
                                                 environment:environment
                                         allowSuppressLogLevel:YES];

    [Adtrace appDidLaunch:adtraceConfig];
}

Swift

MessagesViewController.swift

import Adtrace

override func viewDidLoad() {
    super.viewDidLoad()

    let yourAppToken = "{YourIMessageAppToken}"
    let environment = ADTEnvironmentSandbox
    let adtraceConfig = ADTConfig(
        appToken: yourAppToken,
        environment: environment,
        allowSuppressLogLevel: true
    )

    Adtrace.appDidLaunch(adtraceConfig)
}

For production, switch environment to ADTEnvironmentProduction and set an appropriate log level.

3. Enable session tracking in the extension

In a standard iOS app, the Adtrace SDK listens to system foreground/background notifications to measure sessions. iMessage extensions do not receive those notifications, so you must tell the SDK when the extension becomes active or inactive.

Call trackSubsessionStart when the extension enters the foreground and trackSubsessionEnd when it leaves.

Method signatures

+ (void)trackSubsessionStart;
+ (void)trackSubsessionEnd;

Method	When to call
trackSubsessionStart	Extension is about to present UI (user opened your iMessage app).
trackSubsessionEnd	Extension is dismissed, user switches conversation, or Messages quits.

Hook into Messages lifecycle

Implement the calls in your MSMessagesAppViewController subclass:

UIKit / Messages callback	Adtrace call
didBecomeActiveWithConversation:	trackSubsessionStart
willResignActiveWithConversation:	trackSubsessionEnd

Objective-C

MessagesViewController.m

- (void)didBecomeActiveWithConversation:(MSConversation *)conversation {
    [super didBecomeActiveWithConversation:conversation];
    [Adtrace trackSubsessionStart];
}

- (void)willResignActiveWithConversation:(MSConversation *)conversation {
    [super willResignActiveWithConversation:conversation];
    [Adtrace trackSubsessionEnd];
}

Swift

MessagesViewController.swift

override func didBecomeActive(with conversation: MSConversation) {
    super.didBecomeActive(with: conversation)
    Adtrace.trackSubsessionStart()
}

override func willResignActive(with conversation: MSConversation) {
    super.willResignActive(with: conversation)
    Adtrace.trackSubsessionEnd()
}

With these calls in place, the SDK can measure session length inside your iMessage extension.

4. Track events (optional)

After initialization, track events in the extension the same way as in the main app. See Track events.

Objective-C

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[Adtrace trackEvent:event];

Swift

let event = ADTEvent(eventToken: "abc123")
Adtrace.trackEvent(event)

5. Test the integration

1. Set environment to ADTEnvironmentSandbox and log level to verbose.
2. Run the iMessage extension on a device (simulator support for Messages extensions is limited).
3. Open your iMessage app inside Messages and confirm session and event traffic in Xcode console logs.
4. Verify data in the Adtrace panel under the iMessage app you created (not the host app).

See Test the integration for general install verification steps.

Checklist

• Host iOS app integrated with Adtrace
• Separate app and app token created in the panel for the iMessage extension
• AdtraceSdkIm.framework or source integration with ADTUST_IM=1
• appDidLaunch called in the extension with the iMessage app token
• trackSubsessionStart in didBecomeActiveWithConversation: / didBecomeActive(with:)
• trackSubsessionEnd in willResignActiveWithConversation: / willResignActive(with:)
• Sandbox logs and panel data verified before production release