راه‌اندازی افزونه iMessage

این راهنما را زمانی استفاده کنید که محصول شما شامل یک iMessage app extension (Messages extension) است و می‌خواهید ادتریس Session ها و رویدادها را درون آن افزونه ردیابی کند.

ابتدا شروع کار با iOS SDK را برای اپ اصلی iOS خود تکمیل کنید. این صفحه مراحل اضافی برای target افزونه iMessage را پوشش می‌دهد.

مرجع نمونه: AdtraceExample-iMessage.

پیش از شروع

موضوع	اقدام لازم
اپ اصلی	نصب SDK، framework ها و appDidLaunch را در host app کامل کنید.
توکن اپ	یک اپ جداگانه در پنل ادتریس ایجاد کرده و توکن آن را در افزونه iMessage استفاده کنید.
چرا توکن جداگانه؟	host app و افزونه iMessage در فضاهای حافظه متفاوت با bundle ID های مختلف اجرا می‌شوند. استفاده از یک توکن در هر دو مکان، دو instance مستقل SDK ایجاد کرده و ممکن است داده‌های dashboard را با هم مخلوط کند.

۱. افزودن SDK به target افزونه iMessage

مسیر یکپارچه‌سازی را بر اساس نحوه افزودن SDK به اپ اصلی خود انتخاب کنید.

از سورس

اگر Adtrace SDK را از سورس به target افزونه iMessage اضافه می‌کنید، preprocessor macro ADTUST_IM=1 را در تنظیمات target افزونه iMessage تنظیم کنید.

1. در Xcode، target افزونه iMessage را انتخاب کنید.
2. Build Settings را باز کنید.
3. به دنبال Preprocessor Macros (یا GCC_PREPROCESSOR_DEFINITIONS) بگردید.
4. ADTUST_IM=1 را برای Debug و Release اضافه کنید.

Preprocessor macro

ADTUST_IM=1

به عنوان framework

اگر از framework مخصوص iMessage استفاده می‌کنید:

1. AdtraceSdkIm.framework را به target افزونه iMessage خود اضافه کنید.
2. در Build Phases، یک فاز Copy Files اضافه کنید (یا از فاز موجود استفاده کنید).
3. مقصد را روی Frameworks تنظیم کنید.
4. AdtraceSdkIm.framework را اضافه کنید تا در زمان build به bundle افزونه کپی شود.

۲. مقداردهی اولیه SDK در افزونه

Adtrace را در افزونه iMessage خود به همان روش اپ standard مقداردهی اولیه کنید: یک ADTConfig با توکن اپ iMessage خود ایجاد کرده و appDidLaunch را هنگام شروع افزونه فراخوانی کنید.

از توکن اپ مخصوص iMessage از پنل استفاده کنید، نه توکن اپ host.

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)
}

برای production، environment را به ADTEnvironmentProduction تغییر دهید و یک سطح لاگ مناسب تنظیم کنید.

۳. فعال‌سازی ردیابی Session در افزونه

در یک اپ iOS standard، Adtrace SDK به notification های foreground/background سیستم گوش می‌دهد تا Session ها را اندازه‌گیری کند. افزونه‌های iMessage آن notification ها را دریافت نمی‌کنند، بنابراین باید به SDK بگویید افزونه چه زمانی فعال یا غیرفعال می‌شود.

وقتی افزونه وارد foreground می‌شود trackSubsessionStart و وقتی از آن خارج می‌شود trackSubsessionEnd را فراخوانی کنید.

امضاهای متد

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

متد	زمان فراخوانی
trackSubsessionStart	افزونه در شرف نمایش UI است (کاربر iMessage app شما را باز کرده).
trackSubsessionEnd	افزونه بسته شده، کاربر گفتگو را تغییر داده یا Messages بسته شده.

Hook کردن به lifecycle پیام‌ها

فراخوانی‌ها را در subclass MSMessagesAppViewController خود پیاده‌سازی کنید:

callback UIKit / Messages	فراخوانی Adtrace
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()
}

با این فراخوانی‌ها، SDK می‌تواند طول Session را داخل افزونه iMessage اندازه‌گیری کند.

۴. ردیابی رویدادها (اختیاری)

بعد از مقداردهی اولیه، رویدادها را در افزونه به همان روش اپ اصلی ردیابی کنید. به ردیابی رویدادها مراجعه کنید.

Objective-C

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

Swift

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

۵. تست یکپارچه‌سازی

1. environment را روی ADTEnvironmentSandbox و سطح لاگ را روی verbose تنظیمت کنید.
2. افزونه iMessage را روی یک دستگاه اجرا کنید (پشتیبانی شبیه‌ساز از افزونه‌های Messages محدود است).
3. iMessage app خود را داخل Messages باز کنید و ترافیک Session و رویداد را در لاگ‌های Xcode console تأیید کنید.
4. داده‌ها را در پنل ادتریس زیر اپ iMessage که ایجاد کردید (نه host app) بررسی کنید.

برای مراحل کلی تأیید install، به تست یکپارچه‌سازی مراجعه کنید.

Checklist

• اپ iOS host با ادتریس یکپارچه شده
• اپ جداگانه و توکن اپ برای افزونه iMessage در پنل ایجاد شده
• AdtraceSdkIm.framework یا یکپارچه‌سازی سورس با ADTUST_IM=1
• appDidLaunch در افزونه با توکن اپ iMessage فراخوانی شده
• trackSubsessionStart در didBecomeActiveWithConversation: / didBecomeActive(with:)
• trackSubsessionEnd در willResignActiveWithConversation: / willResignActive(with:)
• لاگ‌های Sandbox و داده‌های پنل قبل از انتشار production تأیید شده