پرش به مطلب اصلی
نسخه: 2.6.0

ویژگی‌های اضافی

Callback اتریبیوشن​

می‌توانید یک listener ثبت کنید تا از تغییرات اتریبیوشن ردیاب مطلع شوید. به دلیل منابع مختلفی که برای اتریبیوشن در نظر گرفته می‌شوند، این اطلاعات نمی‌توانند به‌صورت همزمان ارائه شوند. ساده‌ترین روش ایجاد یک listener ناشناس است که هر بار که مقدار اتریبیوشن کاربر تغییر کند فراخوانی می‌شود:

با instance AdTraceConfig، قبل از راه‌اندازی SDK، listener ناشناس را اضافه کنید:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setAttributionCallbackListener(function(attribution) {
    // چاپ همه ویژگی‌های اتریبیوشن.
    console.log("Attribution changed!");
    console.log(attribution.trackerToken);
    console.log(attribution.trackerName);
    console.log(attribution.network);
    console.log(attribution.campaign);
    console.log(attribution.adgroup);
    console.log(attribution.creative);
    console.log(attribution.clickLabel);
    console.log(attribution.adid);
    console.log(attribution.costType);
    console.log(attribution.costAmount);
    console.log(attribution.costCurrency);
});

AdTrace.create(adtraceConfig);

در تابع listener به پارامترهای attribution دسترسی دارید. خلاصه‌ای از ویژگی‌های آن:

  • trackerToken توکن ردیاب اتریبیوشن جاری.
  • trackerName نام ردیاب اتریبیوشن جاری.
  • network سطح‌بندی شبکه اتریبیوشن جاری.
  • campaign سطح‌بندی کمپین اتریبیوشن جاری.
  • adgroup سطح‌بندی گروه تبلیغاتی اتریبیوشن جاری.
  • creative سطح‌بندی creative اتریبیوشن جاری.
  • clickLabel برچسب کلیک اتریبیوشن جاری.
  • adid شناسه دستگاه Adtrace.
  • costType نوع هزینه.
  • costAmount مقدار هزینه.
  • costCurrency ارز هزینه.

اتریبیوشن کاربر​

این Callback مانند بخش Callback اتریبیوشن، هر بار که اتریبیوشن تغییر کند اطلاعاتی ارائه می‌دهد. اگر می‌خواهید در هر زمان دیگری به وضعیت اتریبیوشن جاری کاربر دسترسی داشته باشید، می‌توانید متد getAttribution را روی instance AdTrace فراخوانی کرده و Callback را به‌عنوان پارامتر ارسال کنید:

AdTrace.getAttribution((attribution) => {
    console.log("Tracker token = " + attribution.trackerToken);
    console.log("Tracker name = " + attribution.trackerName);
    console.log("Network = " + attribution.network);
    console.log("Campaign = " + attribution.campaign);
    console.log("Adgroup = " + attribution.adgroup);
    console.log("Creative = " + attribution.creative);
    console.log("Click label = " + attribution.clickLabel);
    console.log("Adid = " + attribution.adid);
});
یادداشت

اطلاعات وضعیت اتریبیوشن جاری کاربر تنها پس از ردیابی نصب اپلیکیشن توسط backend Adtrace و فعال‌سازی Callback اتریبیوشن در دسترس است. از آن لحظه به بعد، Adtrace SDK اطلاعات اتریبیوشن کاربر را دارد. پس، امکان دسترسی به مقدار اتریبیوشن کاربر قبل از راه‌اندازی SDK و فعال‌سازی Callback اتریبیوشن وجود ندارد.

پارامترهای Session​

برخی پارامترها برای ارسال در هر Event و Session از Adtrace SDK ذخیره می‌شوند. پس از اضافه کردن هر یک از این پارامترها، نیازی نیست هر بار آن‌ها را اضافه کنید زیرا به‌صورت محلی ذخیره می‌شوند. اگر همان پارامتر را دوبار اضافه کنید، تأثیری نخواهد داشت.

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

پارامترهای Callback برای Session​

پارامترهای Callback Session رابطی مشابه پارامترهای Callback Event دارند. به جای اضافه کردن کلید و مقدار به یک Event، از طریق فراخوانی متد addSessionCallbackParameter روی instance AdTrace اضافه می‌شوند:

AdTrace.addSessionCallbackParameter("foo", "bar");

پارامترهای Callback Session با پارامترهای Callback اضافه‌شده به یک Event ادغام می‌شوند. پارامترهای Callback اضافه‌شده به یک Event بر پارامترهای Callback Session اولویت دارند.

هشدار

هر دو پارامتر در این متد باید رشته باشند. اگر یکی از پارامترهای ارسال‌شده رشته نباشد، جفت کلید-مقدار به لیست پارامترها اضافه نمی‌شود.

می‌توان یک پارامتر Callback Session خاص را با ارسال کلید مورد نظر به متد removeSessionCallbackParameter روی instance AdTrace حذف کرد:

AdTrace.removeSessionCallbackParameter("foo");

اگر می‌خواهید همه کلیدها و مقادیرشان را از پارامترهای Callback Session حذف کنید، می‌توانید آن را با متد resetSessionCallbackParameters روی instance AdTrace ریست کنید:

AdTrace.resetSessionCallbackParameters();

پارامترهای partner برای Session​

مانند پارامترهای Callback Session، پارامترهای partner Session هم وجود دارند که در هر Event یا Session از Adtrace SDK ارسال می‌شوند.

این‌ها به شرکای شبکه برای یکپارچه‌سازی‌هایی که در پنل Adtrace فعال شده‌اند ارسال خواهند شد.

پارامترهای partner Session رابطی مشابه پارامترهای partner Event دارند. از طریق فراخوانی متد addSessionPartnerParameter روی instance AdTrace اضافه می‌شوند:

AdTrace.addSessionPartnerParameter("foo", "bar");

پارامترهای partner Session با پارامترهای partner اضافه‌شده به یک Event ادغام می‌شوند. پارامترهای partner اضافه‌شده به یک Event بر پارامترهای partner Session اولویت دارند.

هشدار

هر دو پارامتر در این متد باید رشته باشند. اگر یکی از پارامترهای ارسال‌شده رشته نباشد، جفت کلید-مقدار به لیست پارامترها اضافه نمی‌شود.

می‌توان یک پارامتر partner Session خاص را با متد removeSessionPartnerParameter روی instance AdTrace حذف کرد:

AdTrace.removeSessionPartnerParameter("foo");

اگر می‌خواهید همه کلیدها و مقادیر را از پارامترهای partner Session حذف کنید، آن را با متد resetSessionPartnerParameters روی instance AdTrace ریست کنید:

AdTrace.resetSessionPartnerParameters();

Callback های Session و Event​

می‌توانید یک Callback ثبت کنید تا از Event ها و/یا Session های موفق و ناموفق مطلع شوید.

تابع Callback برای ردیابی موفق Event ها:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setEventTrackingSucceededCallbackListener(function(eventSuccess) {
    // چاپ همه ویژگی‌های موفقیت Event.
    console.log("Event tracking succeeded!");
    console.log(eventSuccess.message);
    console.log(eventSuccess.timestamp);
    console.log(eventSuccess.eventToken);
    console.log(eventSuccess.callbackId);
    console.log(eventSuccess.adid);
    console.log(eventSuccess.jsonResponse);
});

AdTrace.create(adtraceConfig);

تابع Callback برای ردیابی ناموفق Event ها:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setEventTrackingFailedCallbackListener(function(eventFailure) {
    // چاپ همه ویژگی‌های شکست Event.
    console.log("Event tracking failed!");
    console.log(eventFailure.message);
    console.log(eventFailure.timestamp);
    console.log(eventFailure.eventToken);
    console.log(eventFailure.callbackId);
    console.log(eventFailure.adid);
    console.log(eventFailure.willRetry);
    console.log(eventFailure.jsonResponse);
});

AdTrace.create(adtraceConfig);

برای Session های موفق:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setSessionTrackingSucceededCallbackListener(function(sessionSuccess) {
    // چاپ همه ویژگی‌های موفقیت Session.
    console.log("Session tracking succeeded!");
    console.log(sessionSuccess.message);
    console.log(sessionSuccess.timestamp);
    console.log(sessionSuccess.adid);
    console.log(sessionSuccess.jsonResponse);
});

AdTrace.create(adtraceConfig);

و برای Session های ناموفق:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setSessionTrackingFailedCallbackListener(function(sessionFailure) {
    // چاپ همه ویژگی‌های شکست Session.
    console.log("Session tracking failed!");
    console.log(sessionFailure.message);
    console.log(sessionFailure.timestamp);
    console.log(sessionFailure.adid);
    console.log(sessionFailure.willRetry);
    console.log(sessionFailure.jsonResponse);
});

AdTrace.create(adtraceConfig);

توابع Callback پس از تلاش SDK برای ارسال بسته به سرور فراخوانی می‌شوند. خلاصه‌ای از ویژگی‌های داده پاسخ Session:

  • var message پیام از سرور یا خطای لاگ‌شده توسط SDK.
  • var timestamp timestamp از سرور.
  • var adid شناسه منحصربه‌فرد دستگاه ارائه‌شده توسط AdTrace.
  • var jsonResponse شیء JSON با پاسخ از سرور.

هر دو شیء داده پاسخ Event شامل:

  • var eventToken توکن Event، اگر بسته ردیابی‌شده یک Event بود.
  • var callbackId شناسه Callback سفارشی تنظیم‌شده روی شیء Event.

و هر دو شیء ناموفق Event و Session شامل:

  • var willRetry نشان می‌دهد آیا تلاشی برای ارسال مجدد بسته در آینده صورت می‌گیرد.

تأخیر در شروع​

تأخیر در شروع Adtrace SDK به اپلیکیشن شما زمانی می‌دهد تا پارامترهای Session مانند شناسه‌های منحصربه‌فرد را که باید در install ارسال شوند دریافت کند.

زمان تأخیر اولیه را به ثانیه با فیلد setDelayStart روی instance AdTraceConfig تنظیم کنید:

adtraceConfig.setDelayStart(5.5);

در این صورت، Adtrace SDK Session نصب اولیه و هر Event ایجادشده را به مدت ۵.۵ ثانیه ارسال نخواهد کرد. پس از انقضای این زمان یا در صورت فراخوانی sendFirstPackages() روی instance AdTrace در این بین، هر پارامتر Session اضافه خواهد شد.

حداکثر تأخیر

حداکثر زمان تأخیر شروع Adtrace SDK ۱۰ ثانیه است.

غیرفعال‌سازی ردیابی​

می‌توانید با فراخوانی متد setEnabled روی instance AdTrace با پارامتر false، Adtrace SDK را از ردیابی غیرفعال کنید. این تنظیم بین Session ها به خاطر سپرده می‌شود، اما فقط پس از اولین Session می‌تواند فعال شود.

AdTrace.setEnabled(false);

می‌توانید با متد isEnabled بررسی کنید Adtrace SDK فعال است یا خیر. همیشه می‌توان با فراخوانی setEnabled با پارامتر true SDK را فعال کرد.

حالت آفلاین​

می‌توانید Adtrace SDK را در حالت آفلاین قرار دهید تا ارسال داده به سرور متوقف شود در حالی که داده‌های ردیابی‌شده حفظ می‌شوند. در حالت آفلاین، تمام اطلاعات در یک فایل ذخیره می‌شود، پس مراقب باشید Event های زیادی در حالت آفلاین فعال نکنید.

می‌توانید حالت آفلاین را با فراخوانی متد setOfflineMode روی instance AdTrace با پارامتر true فعال کنید:

AdTrace.setOfflineMode(true);

برعکس، می‌توانید حالت آفلاین را با false غیرفعال کنید. هنگامی که Adtrace SDK به حالت آنلاین برمی‌گردد، تمام اطلاعات ذخیره‌شده با اطلاعات زمانی صحیح ارسال می‌شود.

برخلاف غیرفعال‌سازی ردیابی، این تنظیم بین Session ها به خاطر سپرده نمی‌شود.

بافرینگ Event​

اگر اپلیکیشن شما از ردیابی Event به‌شدت استفاده می‌کند، شاید بخواهید برخی درخواست‌های HTTP را به تأخیر بیندازید تا هر دقیقه در یک دسته ارسال شوند. می‌توانید بافرینگ Event را با متد setEventBufferingEnabled روی instance AdTraceConfig فعال کنید:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setEventBufferingEnabled(true);

AdTrace.create(adtraceConfig);

امضای SDK​

یک ادمین باید امضای Adtrace SDK را فعال کند. اگر امضای SDK در حساب شما فعال شده و به App Secrets در پنل Adtrace دسترسی دارید، از متد زیر برای یکپارچه‌سازی امضای SDK استفاده کنید.

یک App Secret با ارسال تمام پارامترهای secret (secretId, info1, info2, info3, info4) به متد setAppSecret روی instance AdTraceConfig تنظیم می‌شود:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setAppSecret(secretId, info1, info2, info3, info4);

AdTrace.create(adtraceConfig);

ردیابی در پس‌زمینه​

رفتار پیش‌فرض Adtrace SDK این است که هنگامی که اپلیکیشن در پس‌زمینه است، ارسال درخواست‌های HTTP متوقف می‌شود. می‌توانید این را با فراخوانی متد setSendInBackground روی instance AdTraceConfig تغییر دهید:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setSendInBackground(true);

AdTrace.create(adtraceConfig);

اگر چیزی تنظیم نشود، ارسال در پس‌زمینه به‌طور پیش‌فرض غیرفعال است.

شناسه‌های دستگاه​

برخی سرویس‌ها (مانند Google Analytics) نیاز دارند که Device ID و Client ID را هماهنگ کنید تا از گزارش تکراری جلوگیری شود.

IDFA (شناسه iOS)​

می‌توانید با فراخوانی متد getIdfa روی instance AdTrace و ارسال Callback، به مقدار IDFA دستگاه iOS دسترسی داشته باشید:

AdTrace.getIdfa((idfa) => {
    console.log("IDFA = " + idfa);
});

GPS AdId (شناسه تبلیغاتی Google Play Services)​

شناسه تبلیغاتی Google Play Services (Google advertising ID) یک شناسه منحصربه‌فرد برای دستگاه است. کاربران می‌توانند از اشتراک‌گذاری آن خودداری کنند. هنگامی که کاربر این تنظیم را فعال کرده باشد، Adtrace SDK رشته‌ای از صفرها برمی‌گرداند.

هشدار

اگر Android 12 و بالاتر (API level 31) را هدف می‌گیرید، باید مجوز com.google.android.gms.AD_ID را اضافه کنید. بدون این مجوز، حتی اگر کاربر از اشتراک‌گذاری شناسه انصراف نداده باشد، نمی‌توانید آن را بخوانید.

برای دریافت Google advertising ID دستگاه Android، متد getGoogleAdId را فراخوانی کنید و Callback را ارسال کنید:

AdTrace.getGoogleAdId((googleAdId) => {
    console.log("Google Ad Id = " + googleAdId);
});

AdId (شناسه دستگاه Adtrace)​

برای هر دستگاهی که اپلیکیشن شما روی آن نصب است، backend Adtrace یک شناسه دستگاه Adtrace منحصربه‌فرد (adid) ایجاد می‌کند. برای دریافت این شناسه، متد getAdid را فراخوانی کرده و Callback را ارسال کنید:

AdTrace.getAdid((adid) => {
    console.log("Adid = " + adid);
});
هشدار

اطلاعات مربوط به adid تنها پس از ردیابی نصب اپلیکیشن توسط backend Adtrace در دسترس است. پس، امکان دسترسی به مقدار adid قبل از راه‌اندازی SDK و ردیابی موفق نصب وجود ندارد.

ردیاب‌های pre-installed​

اگر می‌خواهید از Adtrace SDK برای شناسایی کاربرانی که دستگاه‌هایشان با اپلیکیشن شما از قبل نصب‌شده آمده استفاده کنید، این مراحل را دنبال کنید:

  1. یک ردیاب جدید در پنل ایجاد کنید.
  2. ردیاب پیش‌فرض instance AdTraceConfig را تنظیم کنید:
 var adtraceConfig = new AdTraceConfig(appToken, environment);

 adtraceConfig.setDefaultTracker("{TrackerToken}");

 AdTrace.create(adtraceConfig);

{TrackerToken} را با توکن ردیابی که در مرحله ۲ ایجاد کردید جایگزین کنید. توجه داشته باشید که پنل یک URL ردیاب (شامل http://app.adtrace.io/) نمایش می‌دهد. در کد منبع، باید فقط توکن شش‌کاراکتری و نه URL کامل را مشخص کنید.

  1. اپلیکیشن را بسازید و اجرا کنید. باید خطی مانند زیر در خروجی لاگ اپلیکیشن ببینید:
 Default tracker: 'abc123'

خواندن OAID (دستگاه‌های Huawei)​

برای اینکه Adtrace بتواند OAID را روی دستگاه‌های Android بخواند، باید پلاگین برای oaid پیاده‌سازی کنید. برای اطلاعات بیشتر نگاهی به مثال GitHub برای oaid روی React Native بیندازید.