ردیابی رویدادها

از متدهای این راهنما برای ارسال اطلاعات رویداد از اپ خود به ادتریس استفاده کنید.

Adtrace SDK یک شیء ADTEvent ارائه می‌دهد که برای ساختار و ارسال داده‌های رویداد استفاده می‌کنید. یک رویداد در پنل ادتریس ایجاد کنید، instance ADTEvent را پیکربندی کنید، سپس [Adtrace trackEvent:] / Adtrace.trackEvent(...) را فراخوانی کنید.

مهم

قبل از ارسال رویدادها، مطمئن شوید install با موفقیت ردیابی شده برای اپ روی دستگاه. اگر install ثبت نشده باشد، ادتریس ممکن است رویدادهای شما را دریافت و ذخیره کند، اما آن‌ها در آمار پنل نمایش داده نخواهند شد.

جریان معمول:

1. یک ADTEvent با توکن رویداد خود ایجاد کنید.
2. به صورت اختیاری درآمد، پارامترها یا شناسه callback اضافه کنید.
3. trackEvent را فراخوانی کنید تا ارسال شود.

شیء رویداد

با تنظیم property ها و پارامترها روی instance ADTEvent قبل از فراخوانی trackEvent مشخص کنید ادتریس چه چیزی ارسال کند.

ایجاد یک instance از ADTEvent

Method signature

+ (nullable ADTEvent *)eventWithEventToken:(nonnull NSString *)eventToken;

پارامتر	نوع	توضیح
eventToken	NSString	توکن رویداد ادتریس از پنل ادتریس. توکن رویداد را پاس دهید، نه نام رویداد.

برای ارسال اطلاعات رویداد، یک instance جدید ADTEvent ایجاد کرده و توکن رویداد را پاس دهید. این شیء داده‌هایی را نگه می‌دارد که SDK هنگام وقوع رویداد در اپ ارسال می‌کند.

نکته

• رویدادهای یکتا هنگام ایجاد رویداد در پنل پیکربندی می‌شوند (Settings → Event). رویدادهای یکتا فقط اولین بار روی یک دستگاه ذخیره می‌شوند؛ رویدادهای غیریکتا در هر trigger ذخیره می‌شوند. هیچ flag اضافی در SDK لازم نیست.
• هیچ محدودیتی برای تعداد instance های رویداد که می‌توانید ارسال کنید وجود ندارد (برای رویدادهای غیریکتا).
• SDK رویدادها را روی دستگاه صف‌بندی می‌کند و تا زمانی که سرورهای ادتریس آن‌ها را با موفقیت قبول کند retry می‌کند.

abc123 در مثال‌های زیر را با توکن رویداد از پنل ادتریس جایگزین کنید.

ثبت درآمد رویداد

Method signature

- (void)setRevenue:(double)amount currency:(nonnull NSString *)currency;

پارامتر	نوع	توضیح
amount	double	مقدار درآمد ایجاد شده توسط رویداد.
currency	NSString	برچسب ارز برای این درآمد (برای مثال IRR، EUR یا USD). ادتریس بین ارزها تبدیل نمی‌کند. ترجیح دهید همه درآمد را در یک ارز واحد ارسال کنید.

می‌توانید درآمد مرتبط با یک رویداد را با فراخوانی setRevenue:currency: روی instance ADTEvent ثبت کنید. از این برای اقدامات درآمدزا مانند تبلیغات یا خریدهای درون‌برنامه‌ای استفاده کنید.

درآمد می‌تواند با پارامترهای callback ترکیب شود.

مهم

برای خریدهای درون‌برنامه‌ای، trackEvent را فقط بعد از اتمام خرید و دریافت آیتم فراخوانی کنید (برای مثال بعد از finishTransaction وقتی وضعیت SKPaymentTransactionStatePurchased است). این از ردیابی درآمدی که واقعاً ایجاد نشده جلوگیری می‌کند.

درآمد را از طریق پارامترهای مقدار رویداد ارسال نکنید. همیشه از setRevenue استفاده کنید.

مثال

Objective-C

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event setRevenue:52000.0 currency:@"IRR"];
[Adtrace trackEvent:event];

Swift

let event = ADTEvent(eventToken: "abc123")
event?.setRevenue(52000.0, currency: "IRR")
Adtrace.trackEvent(event)

Javascript

let event = new AdtraceEvent('abc123');
event.setRevenue(52000.0, 'IRR');
Adtrace.trackEvent(event);

تأیید در Xcode console

سطح لاگ را روی ADTLogLevelVerbose یا ADTLogLevelDebug تنظیم کنید، سپس در درخواست /event به دنبال revenue و currency بگردید:

Xcode console (نمونه)

Path:      /event
Parameters:
  event_token      abc123
  revenue          52000.0
  currency         IRR

Deduplication رویدادهای درآمدی

Method signature

- (void)setTransactionId:(nonnull NSString *)transactionId;

پارامتر	نوع	توضیح
transactionId	NSString	یک شناسه یکتا برای این transaction درآمدی (برای مثال یک شناسه transaction StoreKit).

رویدادهای درآمدی اغلب با داده‌های خرید واقعی مقایسه می‌شوند. درآمد تکراری زمانی رایج است که کاربر بیش از یک بار روی خرید می‌زند (مثلاً به خاطر شبکه کند).

یک transaction ID اختیاری با setTransactionId: پاس دهید تا ادتریس بتواند تکراری‌ها را رد کند. SDK آخرین ۱۰ transaction ID را به خاطر می‌سپارد و رویدادهای درآمدی که از آن‌ها مجدداً استفاده می‌کنند را رد می‌کند. این به‌خصوص برای خریدهای درون‌برنامه‌ای مفید است.

مثال

Objective-C

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event setRevenue:52000.0 currency:@"IRR"];
[event setTransactionId:@"{TransactionId}"];
[Adtrace trackEvent:event];

Swift

let event = ADTEvent(eventToken: "abc123")
event?.setRevenue(52000.0, currency: "IRR")
event?.setTransactionId("{TransactionId}")
Adtrace.trackEvent(event)

Javascript

let event = new AdtraceEvent('abc123');
event.setRevenue(52000.0, 'IRR');
event.setTransactionId('{TransactionId}');
Adtrace.trackEvent(event);

مثال: خرید درون‌برنامه‌ای با transaction ID

Objective-C

- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions {
    for (SKPaymentTransaction *transaction in transactions) {
        if (transaction.transactionState == SKPaymentTransactionStatePurchased) {
            [[SKPaymentQueue defaultQueue] finishTransaction:transaction];

            ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
            [event setRevenue:52000.0 currency:@"IRR"];
            [event setTransactionId:transaction.transactionIdentifier];
            [Adtrace trackEvent:event];
        }
    }
}

Swift

func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) {
    for transaction in transactions where transaction.transactionState == .purchased {
        SKPaymentQueue.default().finishTransaction(transaction)

        let event = ADTEvent(eventToken: "abc123")
        event?.setRevenue(52000.0, currency: "IRR")
        event?.setTransactionId(transaction.transactionIdentifier)
        Adtrace.trackEvent(event)
    }
}

تأیید در Xcode console

به دنبال transaction_id یا order_id در درخواست رویداد بگردید (نام فیلد ممکن است بر اساس نسخه SDK متفاوت باشد):

Xcode console (نمونه)

Path:      /event
Parameters:
  event_token      abc123
  transaction_id   5e85484b-1ebc-4141-aab7-25b869e54c49

مرور کلی پارامترهای سفارشی

علاوه بر داده‌هایی که Adtrace SDK به طور پیش‌فرض جمع‌آوری می‌کند، می‌توانید داده key-value سفارشی را به رویدادها ضمیمه کنید.

نوع پارامتر	متد	ارسال به	در پنل نمایش داده می‌شود؟
پارامترهای Callback	addCallbackParameter:value:	URL callback ثبت‌شده شما	خیر (فقط داده‌های callback خام)
پارامترهای مقدار رویداد	addEventValueParameter:value:	پنل ادتریس	بله
پارامترهای Partner	addPartnerParameter:value:	partner های خارجی	خیر (فقط در داده‌های raw)

افزودن پارامترهای Callback

Method signature

- (void)addCallbackParameter:(nonnull NSString *)key value:(nonnull NSString *)value;

پارامتر	نوع	توضیح
key	NSString	نام پارامتر callback.
value	NSString	مقدار پارامتر callback.

اگر یک URL callback در پنل ادتریس ثبت کرده‌اید، ادتریس یک درخواست GET به آن URL ارسال می‌کند وقتی رویداد ردیابی می‌شود.

از پارامترهای callback برای ضمیمه کردن داده key-value سفارشی به آن URL استفاده کنید. addCallbackParameter:value: را روی instance ADTEvent خود قبل از trackEvent فراخوانی کنید.

نکته

ادتریس پارامترهای callback سفارشی شما را ذخیره نمی‌کند. آن‌ها فقط به URL callback شما ضمیمه می‌شوند. اگر رویداد URL callback ثبت‌شده‌ای نداشته باشد، این پارامترها خوانده نمی‌شوند.

مثال

Objective-C

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event addCallbackParameter:@"key" value:@"value"];
[event addCallbackParameter:@"foo" value:@"bar"];
[Adtrace trackEvent:event];

Swift

let event = ADTEvent(eventToken: "abc123")
event?.addCallbackParameter("key", value: "value")
event?.addCallbackParameter("foo", value: "bar")
Adtrace.trackEvent(event)

Javascript

let event = new AdtraceEvent('abc123');
event.addCallbackParameter('key', 'value');
event.addCallbackParameter('foo', 'bar');
Adtrace.trackEvent(event);

اگر http://www.example.com/callback را ثبت کرده‌اید، درخواست اینگونه است:

http://www.example.com/callback?key=value&foo=bar

می‌توانید از placeholder ها در مقادیر پارامتر استفاده کنید (برای مثال {idfa}). در درخواست callback، ادتریس placeholder را با مقدار دستگاه مطابق جایگزین می‌کند.

تأیید در Xcode console

به دنبال callback_params در درخواست رویداد بگردید:

Xcode console (نمونه)

Path:      /event
Parameters:
  callback_params  {"key":"value","foo":"bar"}
  event_token      abc123

افزودن پارامترهای مقدار رویداد

Method signature

- (void)addEventValueParameter:(nonnull NSString *)key value:(nonnull NSString *)value;

پارامتر	نوع	توضیح
key	NSString	نام پارامتر.
value	NSString	مقدار پارامتر.

برای ارسال داده key-value با رویداد، addEventValueParameter:value: را روی instance ADTEvent فراخوانی کنید. اگر کلیدها را در پنل (Settings → Event → Add key) تعریف کرده‌اید، رشته‌های key در کد باید دقیقاً با پنل (حروف بزرگ و کوچک) یکسان باشند.

مهم

درآمد را در پارامترهای مقدار رویداد ارسال نکنید. از setRevenue استفاده کنید.

افزودن پارامترهای Partner

اطلاعات اضافی را با افزودن پارامترهای partner به یک رویداد به network partner های خود ارسال کنید.

ادتریس پارامترهای partner را به partner های خارجی که در پنل راه‌اندازی کرده‌اید ارسال می‌کند. این داده برای آنالیز دقیق‌تر و retargeting مفید است. پارامترها بعد از پیکربندی و فعال‌سازی آن‌ها برای یک partner ارسال می‌شوند.

یادداشت

پارامترهای partner به طور پیش‌فرض در raw data نمایش داده نمی‌شوند. می‌توانید placeholder {partner_parameters} را اضافه کنید تا آن‌ها را به عنوان یک رشته واحد در callback ها دریافت کنید.

Method signature

- (void)addPartnerParameter:(nonnull NSString *)key value:(nonnull NSString *)value;

پارامتر	نوع	توضیح
key	NSString	نام پارامتر partner.
value	NSString	مقدار پارامتر partner.

پارامترهای partner را با فراخوانی addPartnerParameter:value: با جفت‌های string key-value اضافه کنید. برای افزودن پارامترهای متعدد، متد را چند بار فراخوانی کنید.

مثال

Objective-C

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event addPartnerParameter:@"key" value:@"value"];
[event addPartnerParameter:@"foo" value:@"bar"];
[Adtrace trackEvent:event];

Swift

let event = ADTEvent(eventToken: "abc123")
event?.addPartnerParameter("key", value: "value")
event?.addPartnerParameter("foo", value: "bar")
Adtrace.trackEvent(event)

Javascript

let event = new AdtraceEvent('abc123');
event.addPartnerParameter('key', 'value');
event.addPartnerParameter('foo', 'bar');
Adtrace.trackEvent(event);

مثال: فشردن دکمه با پارامترهای partner

این مثال یک رویداد با توکن g3mfiw ثبت می‌کند وقتی کاربر یک دکمه را لمس می‌کند. product_id و user_id را به عنوان پارامترهای partner اضافه می‌کند.

Objective-C

- (IBAction)onTrackUniqueEventTap:(id)sender {
    ADTEvent *event = [ADTEvent eventWithEventToken:@"g3mfiw"];
    [event addPartnerParameter:@"product_id" value:@"29"];
    [event addPartnerParameter:@"user_id" value:@"835"];
    [Adtrace trackEvent:event];
}

Swift

@IBAction func onTrackUniqueEventTap(_ sender: Any) {
    let event = ADTEvent(eventToken: "g3mfiw")
    event?.addPartnerParameter("product_id", value: "29")
    event?.addPartnerParameter("user_id", value: "835")
    Adtrace.trackEvent(event)
}

Javascript

function onTrackUniqueEventTap() {
    let event = new AdtraceEvent('g3mfiw');
    event.addPartnerParameter('product_id', '29');
    event.addPartnerParameter('user_id', '835');
    Adtrace.trackEvent(event);
}

تأیید در Xcode console

به دنبال partner_params در درخواست رویداد بگردید:

Xcode console (نمونه)

Path:      /event
Parameters:
  partner_params  {"product_id":"29","user_id":"835"}
  event_token     g3mfiw

افزودن شناسه Callback

Method signature

- (void)setCallbackId:(nonnull NSString *)callbackId;

پارامتر	نوع	توضیح
callbackId	NSString	یک شناسه string سفارشی برای این instance رویداد.

می‌توانید یک شناسه string سفارشی به هر رویدادی که ردیابی می‌کنید اضافه کنید. ادتریس این شناسه را در callback های موفقیت و شکست رویداد گزارش می‌دهد تا بتوانید بدانید کدام رویدادها با موفقیت ردیابی شدند.

setCallbackId: را روی instance ADTEvent خود قبل از trackEvent فراخوانی کنید.

مثال

Objective-C

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event setCallbackId:@"Your-Custom-Id"];
[Adtrace trackEvent:event];

Swift

let event = ADTEvent(eventToken: "abc123")
event?.setCallbackId("Your-Custom-Id")
Adtrace.trackEvent(event)

Javascript

let event = new AdtraceEvent('abc123');
event.setCallbackId('Your-Custom-Id');
Adtrace.trackEvent(event);

ارسال یک رویداد

بعد از پیکربندی instance ADTEvent خود، هر زمان که اقدام در اپ اتفاق افتاد trackEvent را فراخوانی کنید.

Method signature

+ (void)trackEvent:(nullable ADTEvent *)event;

پارامتر	نوع	توضیح
event	ADTEvent	instance رویداد پیکربندی‌شده برای ارسال.

مثال

Objective-C

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

Swift

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

Javascript

let event = new AdtraceEvent('abc123');
Adtrace.trackEvent(event);

مثال: ردیابی فشردن دکمه

این مثال یک رویداد با توکن abc123 ثبت می‌کند هر بار که کاربر یک دکمه را لمس می‌کند.

Objective-C

- (IBAction)onTrackSimpleEventTap:(id)sender {
    ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
    [Adtrace trackEvent:event];
}

Swift

@IBAction func onTrackSimpleEventTap(_ sender: Any) {
    let event = ADTEvent(eventToken: "abc123")
    Adtrace.trackEvent(event)
}

Javascript

function onTrackSimpleEventTap() {
    let event = new AdtraceEvent('abc123');
    Adtrace.trackEvent(event);
}

تأیید در Xcode console

سطح لاگ را روی ADTLogLevelVerbose یا ADTLogLevelDebug تنظیم کنید، سپس رویداد را ارسال کنید. یک درخواست موفق /event شامل توکن و محیط شما می‌شود:

Xcode console (نمونه)

Path:      /event
Parameters:
  app_token        {YourAppToken}
  environment      sandbox
  event_count      3
  event_token      abc123
  os_name          ios

فیلدهای کلیدی: event_token، event_count، environment

تأیید رویدادهای شما

قبل از ارسال رویدادها در production:

1. مطمئن شوید install با موفقیت ردیابی شده روی دستگاه تست.
2. سطح لاگ را روی ADTLogLevelVerbose یا ADTLogLevelDebug تنظیم کرده و درخواست‌های /event را در Xcode console تأیید کنید.
3. Testing Console را در پنل بررسی کنید (Settings → Testing Console).

برای اجرای کد هنگام موفقیت یا شکست رویداد، به ارسال اطلاعات callback مراجعه کنید.

مرتبط

• مرور کلی ردیابی رویداد
• تنظیم پارامترهای callback Session
• شروع کار با iOS SDK
• ارسال اطلاعات callback
• پیکربندی
• iOS SDK README (event tracking)