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

راه‌اندازی

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

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

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

   • مجوزها: مجوز ACCESS_ADSERVICES_TOPICS را برای دسترسی برنامه‌تان به API موضوعات (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 ، مشخص کنید. برای اعطای دسترسی به همه SDKها از ویژگی allowAllToAccess یا برای اعطای دسترسی به SDKهای منفرد از ویژگی allowSdksToAccess استفاده کنید. درباره مجوزهای سرویس‌های تبلیغاتی و کنترل دسترسی SDK بیشتر بدانید.

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

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

   adb shell setprop debug.adservices.disable_topics_enrollment_check true
   

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

   adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"

   adb shell setprop debug.adservices.disable_topics_enrollment_check true

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

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

عملکرد اصلی 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 و پارامترهای لازم برای دریافت داده‌های topics را مقداردهی اولیه کنید. GetTopicsRequest اطلاعات مورد نیاز برای بازیابی داده‌های API مربوط به Topics، از جمله یک پرچم برای نشان دادن اینکه آیا فراخواننده قرار است به عنوان ناظر عمل کند یا خیر، را ارسال می‌کند. هنگامی که به عنوان ناظر عمل نمی‌کند ، فراخوانی getTopics یک موضوع از دوره قبل را برمی‌گرداند، اما داده‌های topics مربوط به دوره بعد را تحت تأثیر قرار نمی‌دهد. فراخوانی 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);

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

/Internet & Telecom/Text & Instant Messaging

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

آزمایش

API موضوعات، موضوعات مرتبط و جدیدی را بر اساس میزان استفاده از برنامه ارائه می‌دهد. این نسخه اولیه، پیش‌نمایشی از رفتارهای API را ارائه می‌دهد و ما کیفیت موضوعات را در نسخه‌های آینده بهبود خواهیم بخشید.

برای به دست آوردن کامل‌ترین تجربه، توصیه می‌کنیم از یک محیط آزمایشی با چندین برنامه استفاده کنید که در آن می‌توانید getTopics() را فراخوانی کنید تا ببینید موضوعات چگونه انتخاب می‌شوند. مخزن APIهای زمان اجرا و حفظ حریم خصوصی SDK در GitHub شامل مجموعه‌ای از پروژه‌های جداگانه اندروید استودیو برای کمک به شما در شروع کار است، از جمله نمونه‌هایی که نحوه مقداردهی اولیه و فراخوانی API موضوعات را نشان می‌دهند.

محاسبه موضوعات در پایان یک دوره (epoch) انجام می‌شود. به طور پیش‌فرض، هر دوره ۷ روز طول می‌کشد، اما می‌توانید این فاصله را برای رسیدن به نتیجه تغییر دهید. این دستور پوسته Android Debug Bridge طول دوره را به ۵ دقیقه کاهش می‌دهد:

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

برای فعال کردن دستی محاسبه‌ی دوره (epoch)، دستور زیر را اجرا کنید:

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

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

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

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

API تاپیک‌ها از پیاده‌سازی یک‌باره‌ی HPKE (رمزگذاری کلید عمومی ترکیبی) پشتیبانی می‌کند. ما انتظار داریم که تماس‌گیرنده‌ی ثبت‌نام‌شده، یک کلید عمومی ۳۲ بیتی را در نقطه‌ی پایانی URL رمزگذاری عمومی ارائه شده در طول ثبت‌نام میزبانی کند. انتظار می‌رود این کلیدها با رمزگذاری Base64 باشند.

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

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

محدودیت‌ها

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

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

بازخورد شما بخش مهمی از Privacy Sandbox در اندروید است. هرگونه مشکلی که پیدا می‌کنید یا ایده‌هایی برای بهبود Privacy Sandbox در اندروید را با ما در میان بگذارید .

مراحل بعدی

کنترل و شفافیت

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

بررسی اجمالی موضوعات در اندروید

نحوه عملکرد Topics در Android را بدانید و با مراحل اصلی جریان API آشنا شوید.

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

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

• نمونه برنامه‌ها، همکاری‌ها و ویدیوهای راهنما را بررسی کنید.
• ببینید کاربران و توسعه دهندگان چگونه می توانند API را کنترل کنند .
• برای پرسیدن سؤال، مشارکت و به اشتراک گذاشتن بازخورد ، منابع پشتیبانی را بررسی کنید.