راهنمای توسعه‌دهنده موضوعات API

پیش نمایش برنامه نویس بتا

همانطور که در اسناد Android Sandbox Privacy می خوانید، از دکمه Developer Preview یا Beta برای انتخاب نسخه برنامه ای که با آن کار می کنید استفاده کنید، زیرا ممکن است دستورالعمل ها متفاوت باشد.

---

ارائه بازخورد

Topics API سیگنال های علاقه دانه درشت را بر اساس استفاده کاربر از برنامه استنتاج می کند. این سیگنال‌ها، که موضوعات نامیده می‌شوند، با تبلیغ‌کنندگان به اشتراک گذاشته می‌شوند تا از تبلیغات مبتنی بر علاقه بدون ردیابی کاربران در سراسر برنامه‌ها پشتیبانی کنند. درباره موضوعات API در طرح پیشنهادی بیشتر بیاموزید. مهم: دکمه انتشار برنامه‌های افزودنی SDK یا پیش‌نمایش برنامه‌نویس را برای انتخاب نسخه برنامه‌ای که با آن کار می‌کنید انتخاب کنید، زیرا ممکن است دستورالعمل‌ها متفاوت باشد.

برپایی

از جدیدترین Android Privacy Sandbox SDK برای دریافت به‌روزترین نسخه از APIهای حفظ حریم خصوصی استفاده کنید. برای اینکه برنامه شما بتواند از Topics API استفاده کند، باید یک مجوز اضافه کنید و یک پیکربندی Ad Services را در مانیفست خود ایجاد کنید:

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

به پیکربندی سرویس‌های تبلیغاتی در عنصر <application> مانیفست خود ارجاع دهید:

<property android:name="android.adservices.AD_SERVICES_CONFIG"
   android:resource="@xml/ad_services_config" />

منبع XML Ad Services را که در مانیفست ارجاع داده شده است، مشخص کنید، مانند res/xml/ad_services_config.xml . از ویژگی allowAllToAccess برای اعطای دسترسی به همه SDKها یا از ویژگی allowSdksToAccess برای اعطای دسترسی به تک تک SDKها استفاده کنید. درباره مجوزهای Ad Services و کنترل دسترسی SDK بیشتر بیاموزید.

<ad-services-config>
    <topics allowAllToAccess="true" />
</ad-services-config>

علاوه بر این، باید دسترسی به Topics API (به طور پیش فرض غیرفعال) را با این دستورات adb فعال کنید .

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

عملکرد اصلی Topics API در متد getTopics() در داخل شی TopicsManager قرار دارد، همانطور که در این مثال نشان داده شده است:

کاتلین

fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

جاوا

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

برای استفاده از این روش، شی TopicsManager و پارامترهای لازم برای دریافت داده های موضوعات را مقداردهی اولیه کنید. GetTopicsRequest اطلاعات مورد نیاز را برای بازیابی داده های Topics API، از جمله پرچمی برای نشان دادن اینکه تماس گیرنده به عنوان ناظر عمل می کند یا خیر، ارسال می کند. هنگامی که به عنوان ناظر عمل نمی کند، فراخوانی getTopics موضوعی را از دوره قبلی برمی گرداند، اما بر داده های موضوع برای دوره بعدی تأثیری نخواهد داشت. پاسخ تماس OutcomeReceiver نتیجه را به صورت ناهمزمان مدیریت می کند. مثلا:

کاتلین

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    override fun onResult(result: GetTopicsResponse) {
        // handle successful result
        val topicsResult = result.topics
        for (i in topicsResult.indices) {
            Log.i("Topic", topicsResult[i].getTopicId().toString())
        }
        if (topicsResult.size == 0) {
            Log.i("Topic", "Returned Empty")
        }
    }
    override fun onError(error: java.lang.Exception) {
        // handle error
        Log.i("Topic", "Error, did not return successfully")
    }
}

جاوا

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        //Handle Successful Result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicId().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }
    @Override
    public void onError(@NonNull Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

مجموعه ای از موضوعات را درخواست کنید

هنگامی که راه اندازی شما آماده شد، می توانید برای دریافت یک GetTopicsResponse در نتیجه از متد getTopics() تماس بگیرید:

کاتلین

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

جاوا

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

فراخوانی فوق فهرستی از اشیاء موضوعات حاوی مقادیر شناسه را ارائه می دهد که با موضوعاتی در طبقه بندی منبع باز مرتبط با کاربر یا یک خطای مرتبط مطابقت دارد. موضوعات مشابه این مثال خواهند بود:

/Internet & Telecom/Text & Instant Messaging

برای فهرستی از موضوعات احتمالی قابل بازگشت به طبقه بندی مراجعه کنید. این طبقه بندی منبع باز است و تغییرات پیشنهادی را می توان با استفاده از دکمه بازخورد در بالای این صفحه ثبت کرد.

آزمایش کردن

Topics API موضوعات مرتبط و تازه را بر اساس استفاده از برنامه ارائه می دهد. این نسخه اولیه پیش نمایشی از رفتارهای API ارائه می دهد و ما کیفیت موضوعات را نسبت به نسخه های بعدی بهبود خواهیم داد. برای به دست آوردن کامل ترین تجربه، یک محیط آزمایشی با چندین برنامه را توصیه می کنیم که در آن با getTopics() تماس بگیرید تا ببینید موضوعات چگونه انتخاب می شوند. مخزن SDK Runtime and Privacy Preserving APIs در GitHub شامل مجموعه‌ای از پروژه‌های مجزای Android Studio است که به شما در شروع کار کمک می‌کند، از جمله نمونه‌هایی که نحوه تنظیم اولیه و فراخوانی Topics API را نشان می‌دهند.

محاسبه موضوعات در پایان یک "دوران" صورت می گیرد. به طور پیش فرض، هر دوره 7 روز است، اما می توانید این فاصله را تغییر دهید تا نتیجه بگیرید. این دستور پوسته Debug Bridge اندروید طول دوره را به 5 دقیقه کوتاه می کند:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

می توانید مقدار topics_epoch_job_period_ms را با get تأیید کنید:

adb shell device_config get adservices topics_epoch_job_period_ms

برای راه اندازی دستی محاسبه دوره، دستور زیر را اجرا کنید:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

علاوه بر استفاده از برنامه نمونه، یک colab وجود دارد که می توانید از آن برای آزمایش ترکیب های مختلف اطلاعات برنامه در برابر طبقه بندی موضوعات استفاده کنید. از این colab برای مشاهده انواع نتایجی که برنامه شما احتمالاً هنگام تماس با getTopics دریافت می کند، استفاده کنید.

محدودیت ها

برای فهرستی از قابلیت‌های در حال پیشرفت برای Topics API، به یادداشت‌های انتشار مراجعه کنید.

گزارش اشکالات و مشکلات

بازخورد شما بخش مهمی از جعبه ایمنی حریم خصوصی در Android است! هر مشکلی را که پیدا کردید یا ایده ای برای بهبود Privacy Sandbox در Android به ما اطلاع دهید .

{% کلمه به کلمه %}