API موضوعات را در اندروید پیاده سازی کنید

راه اندازی

برای پیاده سازی Topics API، ابتدا باید محیط توسعه خود را راه اندازی کنید. برای انجام مراحل راه اندازی زیر:

  1. از جدیدترین Android Privacy Sandbox SDK برای دریافت به‌روزترین نسخه از APIهای حفظ حریم خصوصی استفاده کنید.

  2. موارد زیر را به مانیفست خود اضافه کنید:

    • مجوز: شامل مجوز ACCESS_ADSERVICES_TOPICS برای اجازه به برنامه شما برای دسترسی به موضوعات API:

      <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>

  3. فناوری تبلیغات خود را با Privacy Sandbox برای تماس با Topics API در SDK خود ثبت کنید . برای آزمایش محلی، می توانید بررسی ثبت نام موضوعات را با دستورات زیر غیرفعال کنید:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. دسترسی به Topics API را فعال کنید . به طور پیش فرض، Topics API غیرفعال است. شما باید آن را با استفاده از دستورات ADB فعال کنید:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

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

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

عملکرد اصلی 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 دریافت می کند، استفاده کنید.

جزئیات رمزگذاری

با معرفی رمزگذاری، فراخوانی به GetTopics() اکنون پاسخی با لیستی از اشیاء EncryptedTopic ایجاد می کند. رمزگشایی این نتایج منجر به ایجاد یک شی با همان قالب JSON Topic قبلی می شود.

Topics API از اجرای یک شات HPKE (رمزگذاری کلید عمومی ترکیبی) پشتیبانی می کند. انتظار داریم تماس گیرنده ثبت نام شده یک کلید عمومی 32 بیتی را در نقطه پایانی URL رمزگذاری عمومی ارائه شده در حین ثبت نام میزبانی کند. انتظار می رود این کلیدها با کد Base64 باشند.

شی EncryptedTopic دارای 3 فیلد است. لیست موضوعات برگشتی را می توان با استفاده از کلید خصوصی مربوطه برای کلید عمومی به دست آورد.

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

محدودیت ها

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

اشکالات و مشکلات را گزارش کنید

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

مراحل بعدی

بیاموزید که چگونه کاربران و توسعه دهندگان می توانند API موضوعات را مدیریت و سفارشی کنند تا مطابق با اولویت ها و نیازهای کاربر باشد.
نحوه عملکرد Topics در Android را بدانید و با مراحل اصلی جریان API آشنا شوید.

همچنین ببینید

برای درک بهتر Topics API در Android، منابع ما را بررسی کنید.