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

Callback اتریبیوشن

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

این مراحل را برای اضافه کردن Callback اختیاری در اپلیکیشن دنبال کنید:

یک متد با signature delegate Action<AdTraceAttribution> ایجاد کنید.
پس از ایجاد شیء AdTraceConfig، متد adtraceConfig.setAttributionChangedDelegate را با متد ایجادشده فراخوانی کنید. همچنین می‌توانید از lambda با همان signature استفاده کنید.
اگر به جای AdTrace.prefab از اسکریپت AdTrace.cs به یک GameObject دیگر اضافه شده، حتماً نام آن GameObject را به‌عنوان پارامتر دوم AdTraceConfig.setAttributionChangedDelegate ارسال کنید.

چون Callback با استفاده از instance AdTraceConfig پیکربندی می‌شود، adtraceConfig.setAttributionChangedDelegate را قبل از AdTrace.start فراخوانی کنید:

using io.adtrace.sdk;

public class ExampleGUI : MonoBehaviour {
    void OnGUI() {
        if (GUI.Button(new Rect(0, 0, Screen.width, Screen.height), "callback")) {
            AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
            adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
            adtraceConfig.setAttributionChangedDelegate(this.attributionChangedDelegate);

            AdTrace.start(adtraceConfig);
        }
    }

    public void attributionChangedDelegate(AdTraceAttribution attribution) {
        Debug.Log("Attribution changed");

        // ...
    }
}

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

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

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

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

AdTraceAttribution attribution = AdTrace.getAttribution();

مهم

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

Callback های Session و Event

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

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

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
adtraceConfig.setEventSuccessDelegate(EventSuccessCallback);

AdTrace.start(adtraceConfig);

// ...

public void EventSuccessCallback(AdTraceEventSuccess eventSuccessData) {
    // ...
}

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

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
adtraceConfig.setEventFailureDelegate(EventFailureCallback);

AdTrace.start(adtraceConfig);

// ...

public void EventFailureCallback(AdTraceEventFailure eventFailureData) {
    // ...
}

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

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
adtraceConfig.setSessionSuccessDelegate(SessionSuccessCallback);

AdTrace.start(adtraceConfig);

// ...

public void SessionSuccessCallback (AdTraceSessionSuccess sessionSuccessData) {
    // ...
}

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

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
adtraceConfig.setSessionFailureDelegate(SessionFailureCallback);

AdTrace.start(adtraceConfig);

// ...

public void SessionFailureCallback (AdTraceSessionFailure sessionFailureData) {
    // ...
}

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

string Message پیام از سرور یا خطای لاگ‌شده توسط SDK
string Timestamp timestamp از سرور
string Adid شناسه منحصربه‌فرد دستگاه ارائه‌شده توسط AdTrace
Dictionary<string, object> JsonResponse شیء JSON با پاسخ از سرور

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

string EventToken توکن Event، اگر بسته ردیابی‌شده یک Event بود
string CallbackId شناسه Callback سفارشی تنظیم‌شده روی شیء Event

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

bool WillRetry نشان می‌دهد آیا تلاشی برای ارسال مجدد بسته صورت می‌گیرد

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

Adtrace SDK شناسه‌های دستگاه را در دسترس قرار می‌دهد.

IDFA (شناسه iOS)

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

string idfa = AdTrace.getIdfa();

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 فقط می‌تواند در یک thread پس‌زمینه خوانده شود. اگر متد getGoogleAdId روی instance AdTrace را با delegate Action<string> فراخوانی کنید، در هر موقعیتی کار می‌کند:

AdTrace.getGoogleAdId((string googleAdId) => {
    // ...
});

به Google advertising ID به‌عنوان متغیر googleAdId دسترسی خواهید داشت.

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

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

String adid = AdTrace.getAdid();

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

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

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

هشدار

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

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

AdTraceConfig.setExternalDeviceId("{Your-External-Device-Id}")

توجه

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

ردیاب پیش‌فرض

یک ردیاب جدید در پنل ایجاد کنید.
ردیاب پیش‌فرض config را تنظیم کنید:

adtraceConfig.setDefaultTracker("{TrackerToken}");

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

Default tracker: 'abc123'

حالت آفلاین

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

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

AdTrace.setOfflineMode(true);

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

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

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

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

AdTrace.setEnabled(false);

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

بافرینگ Event

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

AdTraceConfig adtraceConfig = new AdTraceConfig("{YourAppToken}", "{YourEnvironment}");

adtraceConfig.setEventBufferingEnabled(true);

AdTrace.start(adtraceConfig);

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

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

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

AdTraceConfig adtraceConfig = new AdTraceConfig("{YourAppToken}", "{YourEnvironment}");

adtraceConfig.setSendInBackground(true);

AdTrace.start(adtraceConfig);

Callback اتریبیوشن​

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

Callback های Session و Event​

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

IDFA (شناسه iOS)​

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

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

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

ردیاب پیش‌فرض​

حالت آفلاین​

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

بافرینگ Event​

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