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

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

Callback اتریبیوشن​

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

با instance تنظیمات، قبل از راه‌اندازی SDK، Callback اتریبیوشن را اضافه کنید:

AdTraceConfig adtraceConfig = new AdTraceConfig(yourAppToken, environment);
config.attributionCallback = (AdTraceAttribution attributionChangedData) {
    print('[AdTrace]: Attribution changed!');

    if (attributionChangedData.trackerToken != null) {
      print('[AdTrace]: Tracker token: ' + attributionChangedData.trackerToken!);
    }
    if (attributionChangedData.trackerName != null) {
      print('[AdTrace]: Tracker name: ' + attributionChangedData.trackerName!);
    }
    if (attributionChangedData.campaign != null) {
      print('[AdTrace]: Campaign: ' + attributionChangedData.campaign!);
    }
    if (attributionChangedData.network != null) {
      print('[AdTrace]: Network: ' + attributionChangedData.network!);
    }
    if (attributionChangedData.creative != null) {
      print('[AdTrace]: Creative: ' + attributionChangedData.creative!);
    }
    if (attributionChangedData.adgroup != null) {
      print('[AdTrace]: Adgroup: ' + attributionChangedData.adgroup!);
    }
    if (attributionChangedData.clickLabel != null) {
      print('[AdTrace]: Click label: ' + attributionChangedData.clickLabel!);
    }
    if (attributionChangedData.adid != null) {
      print('[AdTrace]: Adid: ' + attributionChangedData.adid!);
    }
    if (attributionChangedData.costType != null) {
      print('[AdTrace]: Cost type: ' + attributionChangedData.costType!);
    }
    if (attributionChangedData.costAmount != null) {
      print('[AdTrace]: Cost amount: ' +
          attributionChangedData.costAmount!.toString());
    }
    if (attributionChangedData.costCurrency != null) {
      print('[AdTrace]: Cost currency: ' +
          attributionChangedData.costCurrency!);
    }
};
AdTrace.start(adtraceConfig);

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

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

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

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

AdTraceAttribution attribution = AdTrace.getAttribution();
یادداشت

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

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

Adtrace SDK امکان دریافت برخی از شناسه‌های دستگاه را فراهم می‌کند.

IDFA (شناسه iOS)​

برای دریافت IDFA، متد getIdfa روی instance AdTrace را فراخوانی کنید:

AdTrace.getIdfa().then((idfa) {
  // از مقدار رشته‌ای idfa استفاده کنید.
});

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

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

مهم

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

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

برای دریافت Google Advertising ID دستگاه، باید یک تابع Callback به AdTrace.getGoogleAdId ارسال کنید که Google Advertising ID را به‌عنوان آرگومان دریافت می‌کند:

AdTrace.getGoogleAdId().then((googleAdId) {
  // از مقدار رشته‌ای googleAdId استفاده کنید.
});

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

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

AdTrace.getAdid().then((adid) {
  // از مقدار رشته‌ای adid استفاده کنید.
});

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

امضای SDK​

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

یک App Secret با فراخوانی setAppSecret روی instance تنظیمات تنظیم می‌شود:

AdTraceConfig adtraceConfig = new AdTraceConfig(yourAppToken, environment);
adtraceConfig.setAppSecret(secretId, info1, info2, info3, info4);
AdTrace.start(adtraceConfig);

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

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

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

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

همان پارامترهای Callback که برای Event ها ثبت می‌شوند، می‌توانند برای ارسال در هر Event یا Session از Adtrace SDK نیز ذخیره شوند.

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

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

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

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

AdTrace.removeSessionCallbackParameter('foo');

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

AdTrace.resetSessionCallbackParameters();

Callback های Session و Event​

می‌توانید یک Callback ثبت کنید تا هنگام ردیابی Event ها یا Session ها مطلع شوید. چهار Callback وجود دارد: یکی برای ردیابی موفق Event، یکی برای ردیابی ناموفق Event، یکی برای ردیابی موفق Session و یکی برای ردیابی ناموفق Session. پس از ایجاد شیء config می‌توانید هر تعدادی Callback اضافه کنید:

AdTraceConfig adtraceConfig = new AdTraceConfig(yourAppToken, environment);
// تنظیم delegate ردیابی موفق Session.
config.sessionSuccessCallback = (AdTraceSessionSuccess sessionSuccessData) {
    print('[AdTrace]: Session tracking success!');

    if (sessionSuccessData.message != null) {
      print('[AdTrace]: Message: ' + sessionSuccessData.message!);
    }
    if (sessionSuccessData.timestamp != null) {
      print('[AdTrace]: Timestamp: ' + sessionSuccessData.timestamp!);
    }
    if (sessionSuccessData.adid != null) {
      print('[AdTrace]: Adid: ' + sessionSuccessData.adid!);
    }
    if (sessionSuccessData.jsonResponse != null) {
      print('[AdTrace]: JSON response: ' + sessionSuccessData.jsonResponse!);
    }
};
// تنظیم delegate ردیابی ناموفق Session.
config.sessionFailureCallback = (AdTraceSessionFailure sessionFailureData) {
    print('[AdTrace]: Session tracking failure!');

    if (sessionFailureData.message != null) {
      print('[AdTrace]: Message: ' + sessionFailureData.message!);
    }
    if (sessionFailureData.timestamp != null) {
      print('[AdTrace]: Timestamp: ' + sessionFailureData.timestamp!);
    }
    if (sessionFailureData.adid != null) {
      print('[AdTrace]: Adid: ' + sessionFailureData.adid!);
    }
    if (sessionFailureData.willRetry != null) {
      print('[AdTrace]: Will retry: ' + sessionFailureData.willRetry.toString());
    }
    if (sessionFailureData.jsonResponse != null) {
      print('[AdTrace]: JSON response: ' + sessionFailureData.jsonResponse!);
    }
};

// تنظیم delegate ردیابی موفق Event.
config.eventSuccessCallback = (AdTraceEventSuccess eventSuccessData) {
    print('[AdTrace]: Event tracking success!');

    if (eventSuccessData.eventToken != null) {
      print('[AdTrace]: Event token: ' + eventSuccessData.eventToken!);
    }
    if (eventSuccessData.message != null) {
      print('[AdTrace]: Message: ' + eventSuccessData.message!);
    }
    if (eventSuccessData.timestamp != null) {
      print('[AdTrace]: Timestamp: ' + eventSuccessData.timestamp!);
    }
    if (eventSuccessData.adid != null) {
      print('[AdTrace]: Adid: ' + eventSuccessData.adid!);
    }
    if (eventSuccessData.callbackId != null) {
      print('[AdTrace]: Callback ID: ' + eventSuccessData.callbackId!);
    }
    if (eventSuccessData.jsonResponse != null) {
      print('[AdTrace]: JSON response: ' + eventSuccessData.jsonResponse!);
    }
};
// تنظیم delegate ردیابی ناموفق Event.
config.eventFailureCallback = (AdTraceEventFailure eventFailureData) {
    print('[AdTrace]: Event tracking failure!');

    if (eventFailureData.eventToken != null) {
      print('[AdTrace]: Event token: ' + eventFailureData.eventToken!);
    }
    if (eventFailureData.message != null) {
      print('[AdTrace]: Message: ' + eventFailureData.message!);
    }
    if (eventFailureData.timestamp != null) {
      print('[AdTrace]: Timestamp: ' + eventFailureData.timestamp!);
    }
    if (eventFailureData.adid != null) {
      print('[AdTrace]: Adid: ' + eventFailureData.adid!);
    }
    if (eventFailureData.callbackId != null) {
      print('[AdTrace]: Callback ID: ' + eventFailureData.callbackId!);
    }
    if (eventFailureData.willRetry != null) {
      print('[AdTrace]: Will retry: ' + eventFailureData.willRetry.toString());
    }
    if (eventFailureData.jsonResponse != null) {
      print('[AdTrace]: JSON response: ' + eventFailureData.jsonResponse!);
    }
};

AdTrace.start(adtraceConfig);

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

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

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

  • eventToken توکن Event رشته‌ای، اگر بسته ردیابی‌شده یک Event بود.

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

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

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

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

زمان تأخیر اولیه را به ثانیه با عضو delayStart روی instance config تنظیم کنید:

adtraceConfig.delayStart = 5.5;

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

هشدار

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

فریم‌ورک SKAdNetwork​

یادداشت

این ویژگی فقط در پلتفرم iOS وجود دارد.

اگر Adtrace SDK نسخه v2 یا بالاتر را پیاده‌سازی کرده‌اید و اپلیکیشن شما روی iOS 14 و بالاتر اجرا می‌شود، ارتباط با SKAdNetwork به‌طور پیش‌فرض فعال است، اگرچه می‌توانید آن را غیرفعال کنید. هنگام فعال بودن، Adtrace به‌طور خودکار هنگام راه‌اندازی SDK برای اتریبیوشن SKAdNetwork ثبت‌نام می‌کند. اگر Event ها در پنل Adtrace برای دریافت مقادیر تبدیل تنظیم شده باشند، backend Adtrace داده‌های مقدار تبدیل را به SDK ارسال می‌کند. SDK سپس مقدار تبدیل را تنظیم می‌کند. پس از دریافت داده‌های Callback SKAdNetwork توسط Adtrace، در پنل نمایش داده می‌شود.

در صورتی که نمی‌خواهید Adtrace SDK به‌طور خودکار با SKAdNetwork ارتباط برقرار کند، می‌توانید آن را با فراخوانی متد زیر روی شیء تنظیمات غیرفعال کنید:

adtraceConfig.deactivateSKAdNetworkHandling();

به‌روزرسانی مقدار تبدیل SKAdNetwork​

یادداشت

این ویژگی فقط در پلتفرم iOS وجود دارد.

می‌توانید از متد wrapper Adtrace SDK یعنی updateConversionValue برای به‌روزرسانی مقدار تبدیل SKAdNetwork کاربر استفاده کنید:

AdTrace.updateConversionValue(6);

تنظیم شناسه دستگاه خارجی (آزمایشی)​

اخطار

این ویژگی آزمایشی است.

شناسه دستگاه خارجی یک مقدار سفارشی است که می‌توانید به یک دستگاه یا کاربر اختصاص دهید. این شناسه‌ها می‌توانند در شناسایی کاربران در Session ها و پلتفرم‌های مختلف کمک کنند. همچنین می‌توانند در حذف تکراری نصب‌ها به ازای کاربر مفید باشند.

همچنین می‌توانید از شناسه دستگاه خارجی به‌عنوان یک شناسه سفارشی برای دستگاه استفاده کنید.

یادداشت

این تنظیم نیاز به Adtrace SDK نسخه v2.0.2 یا بالاتر دارد.

برای تنظیم شناسه دستگاه خارجی، شناسه را به ویژگی externalDeviceId روی instance config اختصاص دهید. این کار را قبل از راه‌اندازی Adtrace SDK انجام دهید:

adtraceConfig.externalDeviceId = '{Your-External-Device-Id}';
توجه

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

اگر می‌خواهید از شناسه دستگاه خارجی در تحلیل‌های تجاری استفاده کنید، می‌توانید آن را به‌عنوان پارامتر Callback Session ارسال کنید. بخش پارامترهای Callback Session را ببینید.

می‌توانید شناسه‌های دستگاه خارجی موجود را به AdTrace وارد کنید. این اطمینان می‌دهد که backend داده‌های آینده را با رکوردهای دستگاه موجود شما مطابقت دهد. اگر می‌خواهید این کار را انجام دهید، با نماینده Adtrace خود تماس بگیرید.

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

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

  • یک ردیاب جدید در پنل ایجاد کنید.
  • ردیاب پیش‌فرض شیء config خود را تنظیم کنید:
adtraceConfig.defaultTracker = '{TrackerToken}';

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

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

حالت آفلاین​

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

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

AdTrace.setOfflineMode(true);

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

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

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

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

AdTrace.setEnabled(false);

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

بافرینگ Event​

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

adtraceConfig.eventBufferingEnabled = true;

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

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

adtraceConfig.sendInBackground = true;

رعایت COPPA​

به‌طور پیش‌فرض، Adtrace SDK اپلیکیشن را با COPPA سازگار علامت‌گذاری نمی‌کند. برای این کار، باید متد coppaCompliantEnabled از instance AdTraceConfig را با پارامتر boolean true فراخوانی کنید:

adtraceConfig.coppaCompliantEnabled = true;
یادداشت

با فعال‌سازی این ویژگی، اشتراک‌گذاری با اشخاص ثالث به‌طور خودکار برای کاربران غیرفعال می‌شود. اگر بعداً تصمیم گرفتید دیگر اپلیکیشن را با COPPA سازگار علامت‌گذاری نکنید، اشتراک‌گذاری با اشخاص ثالث به‌طور خودکار مجدداً فعال نخواهد شد. علاوه بر عدم علامت‌گذاری اپلیکیشن با COPPA، باید صریحاً اشتراک‌گذاری با اشخاص ثالث را در صورت تمایل مجدداً فعال کنید.

اپلیکیشن‌های کودکان در Play Store​

به‌طور پیش‌فرض، Adtrace SDK اپلیکیشن را به‌عنوان Play Store Kids App علامت‌گذاری نمی‌کند. برای علامت‌گذاری اپلیکیشن به‌عنوان اپلیکیشن هدف‌گذاری‌شده برای کودکان در Play Store، باید متد playStoreKidsAppEnabled از instance AdTraceConfig را با پارامتر boolean true فراخوانی کنید:

adtraceConfig.playStoreKidsAppEnabled = true;

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

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