شروع کار با iOS SDK

این راهنما شما را در مراحل اولیه راه‌اندازی iOS SDK ادتریس همراهی می‌کند. یاد می‌گیرید چطور SDK را نصب، پروژه را پیکربندی، SDK را مقداردهی اولیه کنید و صحت یکپارچه‌سازی را تأیید نمایید. در پایان این راهنما، اپ شما آماده ردیابی install، Session و رویدادها خواهد بود.

اپلیکیشن‌های نمونه: Objective-C، Swift، WebView (تجربی).

۱. افزودن Adtrace SDK

SDK ادتریس را با یکی از این روش‌ها به پروژه iOS خود اضافه کنید:

• CocoaPods (پیشنهادی): pod را به Podfile خود اضافه کرده و pod install را اجرا کنید.
• Carthage: SDK را به Cartfile خود اضافه کنید.
• Swift Package Manager: مخزن GitHub را در Xcode اضافه کنید.

برای آخرین نسخه پایدار، صفحه releases را بررسی کنید.

مهم

iOS SDK ادتریس از iOS 9 به بالا پشتیبانی می‌کند.

CocoaPods

SDK را به Podfile خود اضافه کنید:

Podfile

# از مخزن CocoaPods \{#from-the-cocoapods-repository}
pod 'Adtrace', '~> 2.2.1'

# یا مستقیماً از GitHub \{#or-directly-from-github}
pod 'Adtrace', :git => 'https://github.com/adtrace/adtrace_sdk_iOS.git', :tag => '2.2.1'

Carthage

خط زیر را به Cartfile خود اضافه کنید:

Cartfile

github "adtrace/ios_sdk"

Swift Package Manager

1. در Xcode روی File → Add Package Dependencies کلیک کنید.
2. آدرس مخزن SDK را وارد کنید:

https://github.com/adtrace/adtrace_sdk_iOS

3. نسخه Adtrace SDK را از منوی کشویی Version انتخاب کنید.

۲. یکپارچه‌سازی SDK

SDK ادتریس را در app delegate خود (یا bridging header برای Swift) import کنید.

CocoaPods

Objective-C

به AppDelegate.h اضافه کنید:

AppDelegate.h

#import "Adtrace.h"
// یا
#import <Adtrace/Adtrace.h>

برای WebBridge (تجربی)، این مورد را هم اضافه کنید:

AppDelegate.h

#import "AdtraceBridge.h"

Swift

به bridging header خود اضافه کنید:

Bridging-Header.h

#import <Adtrace/Adtrace.h>

برای WebBridge (تجربی)، این مورد را هم اضافه کنید:

Bridging-Header.h

#import "AdtraceBridge.h"

Carthage یا import از framework

Objective-C

AppDelegate.h

#import <AdtraceSdk/Adtrace.h>

برای WebBridge (تجربی):

AppDelegate.h

#import <AdtraceSdkWebBridge/AdtraceBridge.h>

Swift

Bridging-Header.h

#import <Adtrace/Adtrace.h>

برای WebBridge (تجربی):

Bridging-Header.h

#import <AdtraceSdkWebBridge/AdtraceBridge.h>

۳. افزودن framework های iOS

SDK ادتریس می‌تواند از framework های اختیاری Apple برای ویژگی‌های بیشتر استفاده کند. آن‌ها را در Xcode اضافه کرده و هر کدام را به عنوان Optional علامت بزنید تا SDK حتی زمانی که framework در دسترس نیست هم اجرا شود.

Framework	هدف	نکات
AdSupport.framework	خواندن IDFA و (قبل از iOS 14) LAT	برای اپ‌های دسته‌بندی Kids اضافه نکنید
AdServices.framework	attribution از Apple Search Ads
StoreKit.framework	ارتباط با SKAdNetwork (iOS 14+)
AppTrackingTransparency.framework	دیالوگ رضایت ATT (iOS 14+)	برای اپ‌های دسته‌بندی Kids اضافه نکنید
WebKit.framework	پشتیبانی از WebView	فقط برای اپ‌های WebBridge / WebView

برای راه‌اندازی ATT، به App Tracking Transparency مراجعه کنید.

۴. مقداردهی اولیه Adtrace SDK

AdtraceConfig را با توکن اپلیکیشن و محیط خود مقداردهی اولیه کنید، سپس appDidLaunch را از application:didFinishLaunchingWithOptions: در app delegate خود فراخوانی کنید.

به موارد زیر نیاز دارید:

• appToken: توکن اپلیکیشن ادتریس از پنل ادتریس
• environment: برای تست از ADTEnvironmentSandbox و قبل از انتشار از ADTEnvironmentProduction استفاده کنید. ادتریس از این مقدار برای جداسازی ترافیک تست از ترافیک واقعی استفاده می‌کند.

مهم

هنگام تست از ADTEnvironmentSandbox استفاده کنید. قبل از ارسال به App Store یا انتشار اپ، به ADTEnvironmentProduction تغییر دهید.

Objective-C

AppDelegate.m

#import "Adtrace.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSString *yourAppToken = @"{YourAppToken}";
    NSString *environment = ADTEnvironmentSandbox;
    ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken
                                                   environment:environment];

    [Adtrace appDidLaunch:adtraceConfig];
    return YES;
}

Swift

AppDelegate.swift

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    let yourAppToken = "{YourAppToken}"
    let environment = ADTEnvironmentSandbox
    let adtraceConfig = ADTConfig(appToken: yourAppToken, environment: environment)

    Adtrace.appDidLaunch(adtraceConfig)
    return true
}

{YourAppToken} را با توکن اپلیکیشن خود از پنل ادتریس جایگزین کنید.

environment را بر اساس مرحله خود تنظیم کنید:

Objective-C

// تست
NSString *environment = ADTEnvironmentSandbox;

// Production (قبل از انتشار)
NSString *environment = ADTEnvironmentProduction;

Swift

// تست
let environment = ADTEnvironmentSandbox

// Production (قبل از انتشار)
let environment = ADTEnvironmentProduction

۵. راه‌اندازی لاگ‌گیری

logLevel را روی ADTConfig پیش از فراخوانی appDidLaunch تنظیم کنید. برای همه گزینه‌ها و حالت suppress در production، به تنظیم سطح لاگ مراجعه کنید.

نکته

برای غیرفعال کردن تمام لاگ‌ها، allowSuppressLogLevel را در AdtraceConfig روی YES / true تنظیم کرده و از ADTLogLevelSuppress استفاده کنید.

Objective-C

AppDelegate.m

[adtraceConfig setLogLevel:ADTLogLevelVerbose]; // فعال کردن همه لاگ‌ها
[adtraceConfig setLogLevel:ADTLogLevelDebug];
[adtraceConfig setLogLevel:ADTLogLevelInfo];    // پیش‌فرض
[adtraceConfig setLogLevel:ADTLogLevelWarn];
[adtraceConfig setLogLevel:ADTLogLevelError];
[adtraceConfig setLogLevel:ADTLogLevelAssert];
[adtraceConfig setLogLevel:ADTLogLevelSuppress]; // غیرفعال کردن همه لاگ‌ها

Swift

AppDelegate.swift

adtraceConfig?.logLevel = ADTLogLevelVerbose // فعال کردن همه لاگ‌ها
adtraceConfig?.logLevel = ADTLogLevelDebug
adtraceConfig?.logLevel = ADTLogLevelInfo    // پیش‌فرض
adtraceConfig?.logLevel = ADTLogLevelWarn
adtraceConfig?.logLevel = ADTLogLevelError
adtraceConfig?.logLevel = ADTLogLevelAssert
adtraceConfig?.logLevel = ADTLogLevelSuppress // غیرفعال کردن همه لاگ‌ها

برای suppress کردن لاگ‌ها در build های production، با allowSuppressLogLevel مقداردهی اولیه کنید:

Objective-C

AppDelegate.m

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

[Adtrace appDidLaunch:adtraceConfig];

Swift

AppDelegate.swift

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

Adtrace.appDidLaunch(adtraceConfig)

۶. WebBridge

اختیاری. فقط برای اپ‌هایی که از WKWebView استفاده می‌کنند. اپ‌های native-only می‌توانند به ۷. تست یکپارچه‌سازی بروند.

نمایش راه‌اندازی WebBridge (اپ‌های WebView، تجربی)

ابتدا راه‌اندازی native بالا را کامل کنید (SDK، framework ها، مقداردهی اولیه و لاگ‌گیری). سپس WebBridge را در view controller و محتوای وب خود متصل کنید.

برای مرجع کامل، اپ نمونه WebView را ببینید.

اتصال WebBridge در view controller

Objective-C

ViewController.m

#import "AdtraceBridge.h"

- (void)viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];

    WKWebView *webView = [[WKWebView alloc] initWithFrame:self.view.bounds];
    // به interface خود @property (nonatomic, strong) AdtraceBridge *adtraceBridge; اضافه کنید
    [self.adtraceBridge loadWKWebViewBridge:webView];
}

Swift

ViewController.swift

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)

    let webView = WKWebView(frame: view.bounds)
    // به interface خود var adtraceBridge: AdtraceBridge? اضافه کنید
    adtraceBridge?.loadWKWebViewBridge(webView)
}

همچنین می‌توانید از WebViewJavascriptBridge از طریق property bridgeRegister روی instance AdtraceBridge خود استفاده کنید. به مستندات کتابخانه مراجعه کنید.

مقداردهی اولیه Adtrace در web view

web view init

function setupWebViewJavascriptBridge(callback) {
  if (window.WebViewJavascriptBridge) {
    return callback(WebViewJavascriptBridge);
  }

  if (window.WVJBCallbacks) {
    return window.WVJBCallbacks.push(callback);
  }

  window.WVJBCallbacks = [callback];

  const WVJBIframe = document.createElement('iframe');
  WVJBIframe.style.display = 'none';
  WVJBIframe.src = 'https://__bridge_loaded__';
  document.documentElement.appendChild(WVJBIframe);

  setTimeout(function () {
    document.documentElement.removeChild(WVJBIframe);
  }, 0);
}

setupWebViewJavascriptBridge(function (bridge) {
  const yourAppToken = '{YourAppToken}';
  const environment = AdtraceConfig.EnvironmentSandbox;
  const adtraceConfig = new AdtraceConfig(yourAppToken, environment);
  Adtrace.appDidLaunch(adtraceConfig);
});

اختیاری: افزونه iMessage

اختیاری. فقط اگر اپ شما شامل یک iMessage app extension است. اپ‌هایی که Messages extension ندارند می‌توانند به ۷. تست یکپارچه‌سازی بروند.

افزونه‌های iMessage نیاز به راه‌اندازی اضافی SDK و hook های دستی Session دارند (trackSubsessionStart / trackSubsessionEnd). از یک توکن اپ جداگانه برای افزونه استفاده کنید.

برای مراحل کامل، امضاهای متد و checklist، به راه‌اندازی افزونه iMessage مراجعه کنید.

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

یک install موفق (اولین باز کردن بعد از نصب) باید قبل از نمایش صحیح Session و رویدادها در ادتریس ثبت شود. برای تأیید یکپارچه‌سازی خود مراحل زیر را دنبال کنید.

آماده‌سازی دستگاه تست

برای ثبت یک install واقعی برای تست:

1. از دستگاهی استفاده کنید که هرگز اپ شما را نصب نکرده، یا اپ را از دستگاه حذف کنید.
2. اپ را دوباره در یک وضعیت تمیز نصب و باز کنید.
3. اگر قبلاً روی همان دستگاه تست کرده‌اید، از Forget Device در Testing Console استفاده کنید (در ادامه توضیح داده می‌شود).

تست در پنل ادتریس

اگر از پنل ادتریس استفاده می‌کنید:

1. شناسه دستگاه خود را کپی کنید (IDFA در صورت موجود بودن، در غیر این صورت primary_dedupe_token از لاگ‌های SDK).
2. پنل ادتریس را باز کنید، اپ خود را انتخاب کنید، سپس به Settings → Testing Console بروید.
3. شناسه دستگاه را وارد کنید، نوع شناسه (idfa یا نوع مطابق نمایش داده شده در console) را انتخاب کنید و بررسی کنید که آیا install برای آن دستگاه ثبت شده است.

اگر install نمایش داده نشد، مراحل راه‌اندازی قبلی و اپ‌های نمونه را بررسی کنید، سپس دوباره روی یک دستگاه تست امتحان کنید. برای عیب‌یابی به سوالات متداول مراجعه کنید.

تست با لاگ‌ها (اختیاری)

1. logLevel را روی ADTLogLevelVerbose و environment را روی ADTEnvironmentSandbox تنظیم کنید.
2. دستگاه را متصل کنید و لاگ‌های Xcode console را باز کنید.
3. در صورت نیاز اپ را حذف کنید، دوباره نصب کنید و اپ را باز کنید.
4. در لاگ‌های پاسخ سرور، به دنبال مقدار adid بگردید. دریافت adid به معنی ثبت موفق install است.

پاسخ Console (نمونه)

"adid" : "mhxd6or7d3u57fnbdy2r4urdrdxr7tlr"

۸. ساخت اپ برای production

بعد از اتمام تست، قبل از انتشار اپ AdtraceConfig خود را به‌روز کنید:

1. logLevel را برای production روی ADTLogLevelWarn یا ADTLogLevelSuppress تنظیم کنید.
2. environment را روی ADTEnvironmentProduction تنظیم کنید.

Objective-C

AppDelegate.m

NSString *yourAppToken = @"{YourAppToken}";
NSString *environment = ADTEnvironmentProduction;
ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken
                                             environment:environment
                                     allowSuppressLogLevel:YES];
[adtraceConfig setLogLevel:ADTLogLevelWarn];

[Adtrace appDidLaunch:adtraceConfig];

Swift

AppDelegate.swift

let yourAppToken = "{YourAppToken}"
let environment = ADTEnvironmentProduction
let adtraceConfig = ADTConfig(
    appToken: yourAppToken,
    environment: environment,
    allowSuppressLogLevel: true
)
adtraceConfig?.logLevel = ADTLogLevelWarn

Adtrace.appDidLaunch(adtraceConfig)

ترافیک Sandbox و production در پنل ادتریس از هم جدا هستند، بنابراین می‌توانید داده‌های تست را از کاربران واقعی فیلتر کنید.

شما آماده build و اجرای اپ production خود هستید و می‌توانید attribution کاربران را با Adtrace SDK شروع کنید.

Checklist

قبل از ادامه، مطمئن شوید موارد زیر را انجام داده‌اید:

• افزودن Adtrace SDK (CocoaPods، Carthage یا SPM)
• Import کردن SDK در app delegate یا bridging header
• افزودن framework های اختیاری iOS مورد نیاز برای use case شما
• مقداردهی اولیه Adtrace در application:didFinishLaunchingWithOptions:
• تنظیم محیط sandbox و لاگ‌های verbose برای تست
• تأیید install موفق در Testing Console یا لاگ‌ها
• تغییر به ADTEnvironmentProduction برای انتشار

مراحل بعدی

• ردیابی رویداد
• پیکربندی
• ویژگی‌های تکمیلی
• سوالات متداول