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

تنظیمات پایه

شروع سریع​

اپلیکیشن‌های نمونه​

چند اپلیکیشن Flutter نمونه در دایرکتوری example موجود است. می‌توانید در آنجا ببینید چگونه Adtrace SDK می‌تواند یکپارچه شود.

اضافه کردن SDK به پروژه​

می‌توانید Adtrace SDK را به اپلیکیشن Flutter خود اضافه کنید؛ کافی است موارد زیر را به فایل pubspec.yaml اضافه کنید:

dependencies:
  adtrace_sdk_flutter: ^1.5.0

سپس در ترمینال به پروژه‌تان رفته و این دستور را اجرا کنید:

flutter packages get
Install

اگر از Visual Studio Code برای توسعه استفاده می‌کنید، پس از ویرایش pubspec.yaml این دستور به‌طور خودکار اجرا می‌شود و نیازی به اجرای دستی نیست.

Android​

اضافه کردن Google Play Services​

از اول اگوست ۲۰۱۴، اپلیکیشن‌های موجود در Google Play Store باید از Google Advertising ID برای شناسایی منحصربه‌فرد دستگاه‌ها استفاده کنند. برای اینکه Adtrace SDK بتواند از Google Advertising ID استفاده کند، باید Google Play Services را یکپارچه کنید. اگر این کار را انجام نداده‌اید، وابستگی مربوطه را به بلاک dependencies در فایل build.gradle اپلیکیشن‌تان برای Android اضافه کنید:

implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
نکته

Adtrace SDK به نسخه خاصی از بخش play-services-ads-identifier از Google Play Services وابسته نیست. می‌توانید از آخرین نسخه یا هر نسخه دیگری که نیاز دارید استفاده کنید.

اضافه کردن مجوزها​

در صورتی که هنوز در فایل AndroidManifest.xml موجود نیستند، مجوزهای زیر را که Adtrace SDK به آن‌ها نیاز دارد اضافه کنید:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

اگر Google Play Store را هدف نمی‌گیرید، مجوز زیر را هم اضافه کنید:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

اضافه کردن مجوز برای دریافت Google advertising ID​

اگر Android 12 و بالاتر (API level 31) را هدف می‌گیرید، باید مجوز com.google.android.gms.AD_ID را برای خواندن advertising ID دستگاه اضافه کنید. خط زیر را به AndroidManifest.xml اضافه کنید:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

برای اطلاعات بیشتر، مستندات AdvertisingIdClient.Info گوگل را ببینید.

تنظیمات Proguard​

اگر از Proguard استفاده می‌کنید، این خطوط را به فایل Proguard اضافه کنید:

-keep class io.adtrace.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
    int SUCCESS;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
    com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
}
-keep public class com.android.installreferrer.** { *; }

اگر اپلیکیشن‌تان را در Google Play Store منتشر نمی‌کنید، فقط قوانین مربوط به پکیج io.adtrace.sdk کافی است:

-keep public class io.adtrace.sdk.** { *; }

Install referrer​

برای اتریبیوشن صحیح نصب اپلیکیشن به منبع آن، Adtrace به اطلاعاتی درباره install referrer نیاز دارد. این اطلاعات می‌تواند از طریق Google Play Referrer API یا با دریافت Google Play Store intent از طریق broadcast receiver به دست آید.

نکته

Google Play Referrer API به‌تازگی توسط گوگل معرفی شده تا روشی مطمئن‌تر و امن‌تر برای دریافت اطلاعات install referrer ارائه دهد. استفاده از آن در اپلیکیشن بسیار توصیه می‌شود. Google Play Store intent روش کمتر امنی است و در آینده منسوخ خواهد شد.

Google Play Referrer API​

برای پشتیبانی از این روش، وابستگی زیر را به فایل build.gradle اپلیکیشن‌تان اضافه کنید:

implementation 'com.android.installreferrer:installreferrer:2.2'

همچنین مطمئن شوید قوانین Proguard را اضافه کرده‌اید، به‌خصوص این قانون:

-keep public class com.android.installreferrer.** { *; }

Google Play Store intent​

برای دریافت INSTALL_REFERRER intent از Google Play Store، باید از یک broadcast receiver استفاده کنید. اگر از broadcast receiver خودتان استفاده نمی‌کنید، تگ receiver زیر را داخل تگ application در فایل AndroidManifest.xml اضافه کنید:

<receiver
    android:name="io.adtrace.sdk.AdTraceReferrerReceiver"
    android:permission="android.permission.INSTALL_PACKAGES"
    android:exported="true" >
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

از این broadcast receiver برای دریافت install referrer و ارسال آن به backend استفاده می‌کنیم.

اگر از broadcast receiver دیگری برای INSTALL_REFERRER intent استفاده می‌کنید، دستورالعمل‌ها را دنبال کنید تا broadcast receiver Adtrace را نیز اضافه کنید.

Huawei Referrer API​

از نسخه v2.0.2، Adtrace SDK از ردیابی نصب روی دستگاه‌های Huawei با نسخه Huawei App Gallery 10.4 و بالاتر پشتیبانی می‌کند. برای اطلاعات بیشتر نحوه استفاده از oaid native plugin در Flutter را ببینید.

iOS​

مطمئن شوید فریم‌ورک‌های iOS زیر با اپلیکیشن iOS شما لینک شده‌اند:

  • iAd.framework - برای کمپین‌های iAd
  • AdServices.framework - برای کمپین‌های iAd
  • AdSupport.framework - برای خواندن iOS Advertising ID (IDFA)
  • CoreTelephony.framework - برای خواندن اطلاعات MCC و MNC
  • StoreKit.framework - برای ارتباط با فریم‌ورک SKAdNetwork
  • AppTrackingTransparency.framework - برای درخواست رضایت کاربر و دریافت وضعیت آن

همه این فریم‌ورک‌ها ویژگی‌های خاصی از SDK را فعال می‌کنند، اما برای کارکرد عادی SDK اجباری نیستند. می‌توانید Status هر یک را در Project Settings → Build Phases → Link Binary With Libraries روی Optional تنظیم کنید.

تنظیمات پایه​

برای شروع، ردیابی Session پایه را تنظیم می‌کنیم.

مطمئن شوید Adtrace SDK را در اسرع وقت در اپلیکیشن Flutter خود راه‌اندازی می‌کنید (هنگام بارگذاری اولین widget). می‌توانید Adtrace SDK را به شکل زیر راه‌اندازی کنید:

AdTraceConfig config = new AdTraceConfig('{YourAppToken}', AdTraceEnvironment.sandbox);
AdTrace.start(config);

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

بسته به اینکه اپلیکیشن را برای تست یا production می‌سازید، باید environment را با یکی از این مقادیر تنظیم کنید:

AdTraceEnvironment.sandbox;
AdTraceEnvironment.production;
نکته

این مقدار باید فقط و فقط زمانی روی AdTraceEnvironment.sandbox باشد که شما یا شخص دیگری در حال تست اپلیکیشن است. قبل از انتشار اپلیکیشن، حتماً environment را به AdTraceEnvironment.production تغییر دهید. هنگام شروع مجدد توسعه و تست، دوباره به AdTraceEnvironment.sandbox برگردید.

از این environment برای تمییز دادن ترافیک واقعی از ترافیک تستی استفاده می‌کنیم. همیشه این مقدار را معنادار نگه دارید!

Session tracking​

هشدار

Session tracking برای عملکرد صحیح SDK ضروری است. SDK باید هنگام باز شدن اپلیکیشن "شروع" و هنگام pause شدن "متوقف" شود تا داده‌ها دقیق جمع‌آوری شوند.

Session tracking برای iOS به‌طور خودکار پشتیبانی می‌شود، اما برای Android نیاز به کار اضافی است که در فصل زیر توضیح داده شده.

Session tracking در Android​

در Android باید به lifecycle متدهای فعالیت اپلیکیشن متصل شوید و هر بار که اپلیکیشن وارد foreground می‌شود AdTrace.onResume() و هر بار که خارج می‌شود AdTrace.onPause() فراخوانی کنید. می‌توانید این کار را به‌صورت global یا به ازای هر widget انجام دهید. مثال:

class AdTraceExampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return new MaterialApp(
      title: 'Adtrace Flutter Example App',
      home: new MainScreen(),
    );
  }
}

class MainScreen extends StatefulWidget {
  @override
  State createState() => new MainScreenState();
}

class MainScreenState extends State<MainScreen> with WidgetsBindingObserver {
  @override
  initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    initPlatformState(); // <-- SDK را اینجا راه‌اندازی کنید.
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.inactive:
        break;
      case AppLifecycleState.resumed:
        AdTrace.onResume();
        break;
      case AppLifecycleState.paused:
        AdTrace.onPause();
        break;
      case AppLifecycleState.detached:
        break;
      case AppLifecycleState.hidden:
        break;
    }
  }
}

لاگ‌های Adtrace​

می‌توانید با تنظیم logLevel روی instance تنظیمات خود، میزان لاگ‌هایی که هنگام تست می‌بینید را کم یا زیاد کنید:

adtraceConfig.logLevel = AdTraceLogLevel.verbose; // فعال‌سازی همه لاگ‌ها
adtraceConfig.logLevel = AdTraceLogLevel.debug; // غیرفعال کردن verbose logs
adtraceConfig.logLevel = AdTraceLogLevel.info; // غیرفعال کردن debug logs (پیش‌فرض)
adtraceConfig.logLevel = AdTraceLogLevel.warn; // غیرفعال کردن info logs
adtraceConfig.logLevel = AdTraceLogLevel.error; // غیرفعال کردن warning logs
adtraceConfig.logLevel = AdTraceLogLevel.suppress; // غیرفعال کردن همه لاگ‌ها

ساخت اپلیکیشن​

اپلیکیشن Flutter خود را بسازید و اجرا کنید. در لاگ‌های Android/iOS می‌توانید لاگ‌های Adtrace SDK را ببینید. برای اطمینان از یکپارچه‌سازی صحیح، تست یکپارچه‌سازی را مشاهده کنید.