تنظیمات پایه

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

یک اپلیکیشن نمونه در دایرکتوری example وجود دارد.

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

مراحل یکپارچه‌سازی Adtrace SDK در پروژه React Native را توضیح می‌دهیم. می‌توانید از هر ویرایشگر متنی یا IDE برای توسعه React Native استفاده کنید.

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

ابتدا کتابخانه را از npm دانلود کنید:

$ npm install react-native-adtrace --save

یا

$ yarn add react-native-adtrace

برای اپلیکیشن iOS مطمئن شوید به پوشه ios رفته و وابستگی‌های Cocoapods را نصب کنید:

$ cd ios && pod install

پس از این مراحل، Adtrace SDK باید به اپلیکیشن شما اضافه شده باشد.

یکپارچه‌سازی SDK در اپلیکیشن

باید import statement زیر را در بالای فایل .js خود اضافه کنید:

import { AdTrace, AdTraceEvent, AdTraceConfig } from 'react-native-adtrace';

در فایل App.js کد زیر را برای راه‌اندازی Adtrace SDK اضافه کنید:

constructor(props) {
    super(props);
    const adtraceConfig = new AdTraceConfig("{YourAppToken}", AdTraceConfig.EnvironmentSandbox);
    AdTrace.create(adtraceConfig);
}

componentWillUnmount() {
  AdTrace.componentWillUnmount();
}

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

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

AdTraceConfig.EnvironmentSandbox
AdTraceConfig.EnvironmentProduction

مهم

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

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

لاگ‌های Adtrace

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

adtraceConfig.setLogLevel(AdTraceConfig.LogLevelVerbose);   // فعال‌سازی همه لاگ‌ها
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelDebug);     // لاگ‌های بیشتر
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelInfo);      // پیش‌فرض
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelWarn);      // غیرفعال کردن info logging
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelError);     // غیرفعال کردن warnings
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelAssert);    // غیرفعال کردن errors
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelSuppress);  // غیرفعال کردن همه لاگ‌ها

تنظیمات پروژه Adtrace

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

مجوزهای Android

Adtrace SDK به‌طور پیش‌فرض دو مجوز به فایل AndroidManifest.xml اپلیکیشن اضافه می‌کند:

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

مجوز INTERNET ممکن است در هر لحظه‌ای توسط SDK مورد نیاز باشد. مجوز ACCESS_WIFI_STATE اگر اپلیکیشن Google Play Store را هدف نمی‌گیرد و از Google Play Services استفاده نمی‌کند، مورد نیاز است.

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

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

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

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

Google Play Services

از اول اگوست ۲۰۱۴، اپلیکیشن‌های موجود در Google Play Store باید از Google Advertising ID استفاده کنند. برای اینکه Adtrace SDK از آن استفاده کند، باید Google Play Services را یکپارچه کنید.

فایل build.gradle اپلیکیشن را باز کنید و بلاک dependencies را پیدا کنید. خط زیر را اضافه کنید:

implementation 'com.google.android.gms:play-services-analytics:18.0.1'

یادداشت

نسخه Google Play Services library که استفاده می‌کنید برای Adtrace SDK اهمیتی ندارد، تا زمانی که بخش analytics آن در اپلیکیشن وجود داشته باشد.

تنظیمات 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.** { *; }

Install referrer

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

مهم

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

Google Play Referrer API

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

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

کتابخانه installreferrer بخشی از Google Maven repository است، پس باید آن را به فایل build.gradle اضافه کنید:

allprojects {
    repositories {
        jcenter()
        maven {
            url "https://maven.google.com"
        }
    }
}

همچنین این قانون Proguard را اضافه کنید:

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

Google Play Store intent

Adtrace install referrer broadcast receiver به‌طور پیش‌فرض به اپلیکیشن شما اضافه می‌شود. می‌توانید آن را در فایل AndroidManifest.xml که بخشی از پلاگین React Native ماست ببینید:

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

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

Huawei Referrer API

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

فریم‌ورک‌های iOS

پروژه را در Project Navigator انتخاب کنید. در سمت چپ نمای اصلی، target را انتخاب کنید. در تب Build Phases، گروه Link Binary with Libraries را گسترش دهید. در پایین آن بخش روی دکمه + کلیک کنید. فریم‌ورک‌های زیر را انتخاب کرده و Status آن‌ها را روی Optional تنظیم کنید:

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

فریم‌ورک AppTrackingTransparency

یادداشت

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

برای هر بسته ارسال‌شده، backend Adtrace یکی از چهار وضعیت زیر را برای دسترسی به داده‌های مرتبط با اپلیکیشن دریافت می‌کند:

• Authorized (مجاز)
• Denied (رد شده)
• Not Determined (تعیین نشده)
• Restricted (محدود)

پس از دریافت درخواست مجوز، وضعیت برگشتی یا Authorized یا Denied خواهد بود.

قبل از ارسال درخواست مجوز، وضعیت Not Determined خواهد بود.

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

SDK مکانیزم داخلی برای دریافت وضعیت به‌روزشده پس از پاسخ کاربر به dialog popup دارد. برای ارتباط راحت و کارآمد وضعیت جدید رضایت به backend، Adtrace SDK یک wrapper دور متد مجوز ردیابی اپلیکیشن ارائه می‌دهد که در فصل بعدی توضیح داده شده.

App-tracking authorisation wrapper

یادداشت

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

Adtrace SDK امکان درخواست مجوز کاربر برای دسترسی به داده‌های مرتبط با اپلیکیشن را فراهم می‌کند. Adtrace SDK یک wrapper روی متد requestTrackingAuthorizationWithCompletionHandler ارائه می‌دهد که می‌توانید متد Callback را برای دریافت پاسخ کاربر تعریف کنید. مقدار integer از طریق Callback با این معانی تحویل داده می‌شود:

• 0: ATTrackingManagerAuthorizationStatusNotDetermined
• 1: ATTrackingManagerAuthorizationStatusRestricted
• 2: ATTrackingManagerAuthorizationStatusDenied
• 3: ATTrackingManagerAuthorizationStatusAuthorized

برای استفاده از این wrapper:

Adtrace.requestTrackingAuthorizationWithCompletionHandler(function(status) {
    switch (status) {
        case 0:
            // حالت ATTrackingManagerAuthorizationStatusNotDetermined
            break;
        case 1:
            // حالت ATTrackingManagerAuthorizationStatusRestricted
            break;
        case 2:
            // حالت ATTrackingManagerAuthorizationStatusDenied
            break;
        case 3:
            // حالت ATTrackingManagerAuthorizationStatusAuthorized
            break;
    }
});

قبل از فراخوانی این متد، مطمئن شوید Info.plist اپلیکیشن iOS شما شامل entry برای کلید NSUserTrackingUsageDescription است. در غیر این صورت، اپلیکیشن crash خواهد کرد.

دریافت وضعیت مجوز جاری

برای دریافت وضعیت جاری مجوز ردیابی اپلیکیشن، متد getAppTrackingAuthorizationStatus را فراخوانی کنید:

• 0: از کاربر هنوز نپرسیده شده
• 1: دستگاه کاربر محدود است
• 2: کاربر دسترسی به IDFA را رد کرده
• 3: کاربر دسترسی به IDFA را مجاز دانسته
• -1: وضعیت در دسترس نیست

فریم‌ورک SKAdNetwork

اگر Adtrace iOS SDK نسخه v2.+ را پیاده‌سازی کرده‌اید و اپلیکیشن روی iOS 14 و بالاتر اجرا می‌شود، ارتباط با SKAdNetwork به‌طور پیش‌فرض فعال است. Adtrace به‌طور خودکار هنگام راه‌اندازی SDK برای اتریبیوشن SKAdNetwork ثبت‌نام می‌کند.

برای غیرفعال‌سازی ارتباط خودکار با SKAdNetwork:

adtraceConfig.deactivateSKAdNetworkHandling();

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

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

AdTrace.updateConversionValue(6);

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

می‌توانید Callback ثبت کنید تا هر بار که Adtrace SDK مقدار تبدیل کاربر را به‌روز می‌کند مطلع شوید:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setConversionValueUpdatedCallbackListener(function(conversionValue) {
    console.log("Conversion value updated callback received");
    console.log("Conversion value: " + conversionValue.conversionValue);
  });

AdTrace.create(adtraceConfig);