پرش به مطلب اصلی

سوالات متداول

سوالات رایج درباره یکپارچه‌سازی iOS SDK، تست، App Tracking Transparency، رویدادها و Session ها.

یکپارچه‌سازی​

کجا می‌توانم نمونه‌های واقعی پیاده‌سازی ببینم؟​

مخزن GitHub iOS ادتریس شامل پروژه‌های نمونه برای use case های مختلف است:

آیا می‌توانم از ادتریس در پروژه‌های Swift استفاده کنم؟​

بله. iOS SDK هم از Objective-C و هم Swift پشتیبانی می‌کند. به شروع کار با iOS SDK مراجعه کنید.

چطور به جای CocoaPods از Swift Package Manager استفاده کنم؟​

SDK را از طریق File → Add Packages… اضافه کنید و آدرس مخزن را وارد کنید:

https://github.com/adtrace/adtrace_sdk_iOS

برای گزینه‌های SPM، CocoaPods و Carthage به افزودن Adtrace SDK مراجعه کنید.

آیا ادتریس XCFramework ارائه می‌دهد؟​

بله. هر release شامل framework های از پیش ساخته‌شده روی صفحه GitHub releases است. همچنین می‌توانید با استفاده از اسکریپت build در مخزن، به صورت محلی build کنید.

توکن اپلیکیشن خودم را کجا پیدا کنم؟​

یک اپ در پنل ادتریس ایجاد کنید. ادتریس یک توکن اپلیکیشن hash-like تولید می‌کند که اپلیکیشن شما را برای backend شناسایی می‌کند. آن را زیر Settings → App Token پیدا کنید.

هیچ لاگی از ادتریس نمی‌بینم​

ادتریس لاگ‌ها را در سطوح مختلف چاپ می‌کند. سطح لاگ را روی Verbose تنظیم کنید تا تمام خروجی را ببینید. به راه‌اندازی لاگ‌گیری مراجعه کنید.

مطمئن شوید در حین توسعه از ADTEnvironmentSandbox استفاده می‌کنید: حالت sandbox برای تست در نظر گرفته شده و خروجی لاگ دارد.

هیچ تغییری در آمار پنل ادتریس نمی‌بینم​

وقتی SDK به درستی یکپارچه شده، داده‌ها را به backend ارسال می‌کند و آمار در پنل نمایش داده می‌شود. اگر تغییری نمی‌بینید بررسی کنید:

حداقل نیازمندی برای Adtrace SDK چیست؟​

ادتریس ویژگی‌های زیادی ارائه می‌دهد، اما آنالیتیک و آمار نیاز به یکپارچه‌سازی پایه دارند:

اگر به یک مرجع کاری نیاز دارید اپ‌های نمونه را بررسی کنید.

حالت Sandbox در مقابل حالت Production​

در حین یکپارچه‌سازی و تست، محیط را روی ADTEnvironmentSandbox تنظیم کنید. این ترافیک تست را از production جدا کرده و خروجی لاگ مفیدی فعال می‌کند. قبل از انتشار به ADTEnvironmentProduction تغییر دهید.

به افزودن Adtrace SDK مراجعه کنید. برای حداکثر جزئیات لاگ در حین تست، سطح لاگ را روی Verbose در راه‌اندازی لاگ‌گیری تنظیم کنید.

تست​

چطور مطمئن شوم همه چیز کار می‌کند؟​

قبل از سایر ویژگی‌ها، ادتریس نیاز دارد اپ باز شود و یک install روی دستگاه ثبت شود. سپس تأیید کنید:

برای مراحل کامل Testing Console، تست یکپارچه‌سازی را دنبال کنید.

چطور بدانم install ردیابی شده؟​

دو گزینه:

بررسی install از طریق لاگ‌ها​

ابتدا از حالت sandbox استفاده کنید. در لاگ‌های verbose، به دنبال شیء‌های response از backend بگردید. اگر response شامل فیلد adid با یک مقدار hash-like باشد، install ردیابی شده.

بررسی install از طریق Testing Console​

Settings → Testing Console را در پنل ادتریس باز کنید.

یک شناسه دستگاه ارائه دهید. اگر اپ شما می‌تواند IDFA را بخواند (با مجوز کاربر)، از IDFA استفاده کنید. در غیر این صورت primary_dedupe_token را در لاگ‌ها پیدا کرده و از آن مقدار استفاده کنید.

"دستگاه تست" چیست؟​

وقتی اپ روی یک دستگاه نصب می‌شود، آن دستگاه به خاطر سپرده می‌شود. حذف و نصب مجدد به عنوان install جدید محاسبه نمی‌شود. برای تست install، از دستگاهی استفاده کنید که هرگز install را برای اپ شما ثبت نکرده: یک دستگاه تست.

چطور دستگاه خودم را "فراموش" کنم؟​

در پنل ادتریس، به Settings → Testing Console بروید، شناسه دستگاه خود را وارد کنید و داده‌های آن را از backend پاک کنید.

آیا پنل برای آنچه می‌خواهم ببینم پیکربندی شده؟​

هنگام مشاهده آمار، تأیید کنید:

  • locale و time zone
  • بازه زمانی انتخاب‌شده
  • تنظیمات fraud detection
  • فیلترهای فعال

چرا بعد از نصب مجدد تغییری در install ها وجود ندارد؟​

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

App Tracking Transparency​

آیا ادتریس اپ مرا مجبور می‌کند درخواست مجوز ردیابی کند؟​

خیر. به طور پیش‌فرض، Adtrace SDK درخواست مجوز App Tracking Transparency نمی‌کند. IDFA matching را بهبود می‌دهد، اما ادتریس بدون آن با استفاده از شناسه‌های تولید شده توسط SDK هم کار می‌کند. می‌توانید رفتار مرتبط با ATT را غیرفعال کنید اگر نمی‌خواهید prompt های مجوز داشته باشید.

به افزودن framework های iOS و App Tracking Transparency مراجعه کنید.

چطور بدانم آیا کاربر مجوز ردیابی اپ را داد؟​

از wrapper App Tracking Transparency استفاده کنید یا وضعیت مجوز را مستقیم بررسی کنید. SDK می‌تواند وضعیت consent را به backend گزارش دهد وقتی از wrapper داخلی استفاده می‌کنید.

به App Tracking Transparency و افزودن framework های iOS مراجعه کنید.

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

eventToken چیست؟​

یک رویداد ادتریس با یک توکن string شناسایی می‌شود: مجموعه‌ای از کاراکترها بدون معنای ذاتی. وقتی یک رویداد در پنل ادتریس ایجاد می‌کنید، توکن آن را برای استفاده در کد دریافت می‌کنید.

به ردیابی رویداد مراجعه کنید.

رویداد یکتا چیست؟​

یک رویداد یکتا فقط یک بار در طول عمر اپ دریافت می‌شود: برای اقدامات یک‌باره مانند ایجاد حساب مفید است. این را در پنل هنگام ایجاد رویداد پیکربندی کنید؛ هیچ کد اضافی SDK لازم نیست.

چند رویداد می‌توانم به ازای هر کاربر یا بازه زمانی ردیابی کنم؟​

هیچ محدودیتی وجود ندارد. می‌توانید هر تعداد رویداد در هر فاصله‌ای ارسال کنید.

چند رویداد مختلف باید تعریف کنم؟​

هیچ محدودیت فنی سختی وجود ندارد، اما طرح رویداد خود را قابل مدیریت نگه دارید. یک مجموعه کوچک از رویدادهای قابل استفاده مجدد با پارامترهای مقدار را بر ده‌ها رویداد با نام محدود ترجیح دهید.

پرهیز از:

event 1: purchase_cloth
event 2: purchase_hat
event 3: purchase_watch
...

ترجیح دهید:

event 1: purchase
event 2: open_page
event 3: add_to_cart
event 4: share

برای پارامترها، درآمد و deduplication به ردیابی رویداد مراجعه کنید.

چطور تأیید کنم رویداد ارسال شده؟​

SDK callback های موفقیت و شکست برای هر رویداد ارائه می‌دهد. به callback های رویداد و Session مراجعه کنید. همچنین می‌توانید لاگ‌های verbose را در حین تست sandbox بررسی کنید.

آیا ادتریس درآمد را بر اساس ارز تبدیل می‌کند؟​

خیر. ارزی که به درآمد ضمیمه می‌کنید مقادیر را در گزارش‌ها جدا می‌کند؛ ادتریس تبدیل ارز انجام نمی‌دهد. به طور ثابت از یک ارز واحد استفاده کنید (برای مثال تومان، ریال یا USD).

داده درآمد را از طریق پارامترهای مقدار رویداد ارسال نکنید. به جای آن از API درآمد اختصاصی استفاده کنید. به ثبت درآمد رویداد مراجعه کنید.

چرا deduplication درآمد مهم است و چطور استفاده کنم؟​

درآمد رویداد اغلب با داده‌های خرید واقعی مقایسه می‌شود. کاربران ممکن است وقتی اپ کند است چندین بار روی دکمه خرید بزنند و درآمد تکراری برای یک خرید ارسال کنند.

یک orderId یکتا به ازای هر خرید هنگام ردیابی درآمد اختصاص دهید. اگر همان رویداد بیش از یک بار با همان order ID ارسال شود، ادتریس آن را deduplicate می‌کند.

به deduplication درآمد مراجعه کنید.

چطور می‌توانم اطلاعات سفارشی به یک رویداد اضافه کنم؟​

از پارامترهای مقدار استفاده کنید: جفت‌های string key/value که به یک رویداد ضمیمه می‌شوند. برای هر تنوع به توکن رویداد جداگانه‌ای نیاز ندارید.

به پارامترهای مقدار رویداد مراجعه کنید.

چند پارامتر می‌توانم به یک رویداد اضافه کنم؟​

هیچ محدودیت سختی وجود ندارد، اما از یک ساختار کلید ثابت در رویدادها استفاده کنید.

پرهیز از:

event 1: { "first_name": "John", "last_name": "Brown", "time": "15:49PM" }
event 2: { "name": "John Brown", "cost": "1000$", "date": "10-8-2021" }

ترجیح دهید:

event 1: { "name": "John Brown", "item_type": "mobile", "item_name": "Samsung Galaxy S23 Ultra", "user_id": "123456789" }
event 2: { "name": "Sara Wills", "item_type": "keyboard", "item_name": "Keychron Q6", "user_id": "987654321" }

رویدادها از قبل شامل timestamp هستند؛ تاریخ/زمان را در پارامترهای مقدار تکرار نکنید.

Session ها​

چطور باید یک Session ارسال کنم؟​

بعد از یکپارچه‌سازی پایه، ادتریس Session ها را به صورت خودکار ارسال می‌کند. هیچ کد اضافی لازم نیست.

به یکپارچه‌سازی مراجعه کنید.

چطور تأیید کنم Session ارسال شده؟​

Session ها callback های موفقیت و شکست ارائه می‌دهند. به callback های رویداد و Session مراجعه کنید.

عیب‌یابی​

مشکلات با تأخیر در مقداردهی اولیه SDK​

Adtrace SDK را در didFinishLaunching یا didFinishLaunchingWithOptions در app delegate مقداردهی اولیه کنید: تا حد ممکن زود. تأخیر در مقداردهی اولیه بر موارد زیر تأثیر می‌گذارد:

ویژگیتأثیر تأخیر در init
ردیابی رویدادهر فراخوانی trackEvent قبل از init برای همیشه از دست می‌رود
حالت آفلاینذخیره نمی‌شود: همیشه به false reset می‌شود
فعال / غیرفعالtoggle قبل از init نادیده گرفته می‌شود؛ وضعیت از آخرین init باقی می‌ماند
Reattribution deep linkappWillOpenUrl: قبل از init: داده‌های attribution برای همیشه از دست می‌رود
ردیابی Sessionاعداد DAU ممکن است اشتباه باشند؛ install ها ممکن است هرگز گزارش نشوند

اگر SDK نمی‌تواند ابتدا مقداردهی اولیه شود، یک مکانیزم صف‌بندی سفارشی در اپ خود بسازید تا فراخوانی‌ها را تا بعد از بازگشت appDidLaunch نگه دارد.

ردیابی Session و DAU​

اگر SDK دیر مقداردهی اولیه شود: برای مثال فقط وقتی یک view controller خاص بارگذاری می‌شود: این موارد پیش می‌آید:

  • کاربر اپ را قبل از رسیدن به صفحه SDK-initialized باز کرده و حذف می‌کند → install هرگز ردیابی نمی‌شود.
  • کاربر قبل از نیمه‌شب باز می‌کند، SDK بعد از نیمه‌شب مقداردهی اولیه می‌شود → داده به روز اشتباه نسبت داده می‌شود.

همیشه Adtrace.appDidLaunch(config) را در didFinishLaunching / didFinishLaunchingWithOptions فراخوانی کنید.

خطای build "Adtrace requires ARC" می‌بینم​

پروژه شما از Automatic Reference Counting استفاده نمی‌کند. گزینه‌ها:

  1. پیشنهادی: پروژه را به ARC migrate کنید.
  2. جایگزین: ARC را فقط برای فایل‌های سورس Adtrace فعال کنید. در Xcode، Build Phases → Compile Sources را باز کنید، تمام فایل‌های Adtrace را انتخاب کنید و Compiler Flags را روی -fobjc-arc تنظیم کنید.

خطای [UIDevice adtTrackingEnabled]: unrecognized selector می‌بینم​

این اتفاق می‌افتد وقتی framework SDK بدون linker flag مورد نیاز اضافه شده.

-ObjC را به Other Linker Flags در Build Settings target Xcode خود اضافه کنید. SDK شامل Objective-C category هایی است که برای بارگذاری صحیح به این flag نیاز دارند.

خطای "Session failed (Ignoring too frequent session.)" می‌بینم​

این معمولاً در حین تست install اتفاق می‌افتد. نصب مجدد اپ به تنهایی کافی نیست: سرور ادتریس هنوز وضعیت Session قبلی را برای آن دستگاه نگه می‌دارد.

مقادیر app_token و adid یا idfa را در پیام خطا پیدا کنید:

Session failed (Ignoring too frequent session. Last session: ..., interval: XXs, min interval: 20m)
(app_token: {yourAppToken}, adid: {adidValue})

سپس یکی از URL های زیر را در مرورگر باز کنید (مقادیر را پر کنید):

http://app.adtrace.com/forget_device?app_token={yourAppToken}&adid={adidValue}
http://app.adtrace.com/forget_device?app_token={yourAppToken}&idfa={idfaValue}

Forgot device به معنی موفقیت است. Device not found به معنی اشتباه بودن مقادیر یا از قبل فراموش شده بودن دستگاه است.

"Install tracked" را در لاگ‌ها نمی‌بینم​

اجرا مجدد از Xcode فایل‌های state محلی SDK را پاک نمی‌کند. SDK آن فایل‌ها را می‌بیند و آن را به عنوان یک Session می‌شناسد، نه یک install جدید.

برای شبیه‌سازی install تمیز:

  1. اپ را کاملاً از دستگاه حذف کنید.
  2. با استفاده از Testing Console یا URL forget_device بالا دستگاه را فراموش کنید.
  3. از Xcode روی دستگاه تست اجرا کنید: بعد باید Install tracked را در console ببینید.

پیام "Unattributable SDK click ignored" می‌بینم​

این یک خطای یکپارچه‌سازی نیست. توسط iAd.framework Apple (نسخه ۳+) ایجاد می‌شود که وقتی اپ بدون کلیک واقعی روی iAd banner باز می‌شود به طور مصنوعی بسته‌های sdk_click تولید می‌کند. backend ادتریس آن‌ها را تشخیص داده و نادیده می‌گیرد:

[Adtrace]v: Response: {"message":"Unattributable SDK click ignored."}
[Adtrace]i: Unattributable SDK click ignored.

این پیام به این معنی است که backend به درستی یک کلیک ساختگی را که می‌توانست کاربر شما را به اشتباه attribute کند رد کرده. هیچ اقدامی لازم نیست.

داده‌های درآمدی نادرستی در dashboard می‌بینم​

Adtrace SDK دقیقاً همان عددی که به setRevenue:currency: پاس می‌دهید ارسال می‌کند. نه SDK و نه backend مقدار را تغییر نمی‌دهند. اگر dashboard مقادیر غیرمنتظره نشان می‌دهد، مشکل در منطق محاسبه مقدار قبل از پاس دادن به setRevenue است.

Checklist:

  • تأیید کنید متدی که مقدار درآمد شما را محاسبه می‌کند مقدار صحیح را برمی‌گرداند.
  • trackEvent را فقط بعد از اتمام خرید فراخوانی کنید (مثلاً بعد از SKPaymentTransactionStatePurchased).
  • درآمد را از طریق پارامترهای مقدار رویداد ارسال نکنید: فقط از API اختصاصی setRevenue:currency: استفاده کنید.

به ثبت درآمد رویداد مراجعه کنید.