Android에서 Topics API 구현

설정

Topics API를 구현하려면 먼저 개발 환경을 설정해야 합니다. 다음 설정 단계를 수행하세요.

  1. 최신 Android 개인 정보 보호 샌드박스 SDK를 사용하여 개인 정보 보호 API의 최신 버전을 다운로드하세요.

  2. 매니페스트에 다음을 추가합니다.

    • 권한: 앱에서 Topics API에 액세스할 수 있도록 ACCESS_ADSERVICES_TOPICS 권한을 포함합니다.

      <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 리소스를 지정합니다(예: res/xml/ad_services_config.xml). allowAllToAccess 속성을 사용하여 모든 SDK에 대한 액세스 권한을 부여하거나 allowSdksToAccess 속성을 사용하여 개별 SDK에 대한 액세스 권한을 부여합니다. 광고 서비스 권한 및 SDK 액세스 제어에 관해 자세히 알아보세요.

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

  3. 개인 정보 보호 샌드박스에 광고 기술을 등록하여 SDK에서 Topics API를 호출합니다. 로컬에서 테스트하려면 다음 명령어를 사용하여 Topics 등록 확인을 사용 중지할 수 있습니다.

    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. 기기에서 주제를 가져오는 방법을 숙지하려면 Java 또는 Kotlin 버전의 샘플 앱을 포크하여 구현을 시작합니다.

주제 모음 요청

Topics API의 기본 기능은 다음 예와 같이 TopicsManager 객체 내 getTopics() 메서드에 있습니다.

Kotlin 자바 
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 콜백은 결과를 비동기식으로 처리합니다. 예를 들면 다음과 같습니다.

Kotlin 자바 
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() 메서드의 결과로 이어집니다.

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

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

이 호출은 ID 값이 포함된 Topics 객체 목록을 제공합니다. 오픈소스 분류에서 주제에 해당하는 사용자 또는 관련 오류입니다. 주제는 다음 예와 유사합니다.

/Internet & Telecom/Text & Instant Messaging

반환될 수 있는 주제 목록은 분류를 참고하세요. 이 분류는 오픈소스이므로 이 페이지 상단의 의견 보내기 버튼을 사용하여 변경사항을 제안할 수 있습니다.

테스트

Topics API는 앱 사용에 따라 관련성이 높은 새로운 주제를 제공합니다. 이 초기 버전을 통해 API 동작을 미리 볼 수 있으며 향후 출시를 통해 주제의 품질을 개선할 예정입니다.

최대한의 경험을 얻으려면 getTopics()를 호출하여 주제가 선택되는 방식을 확인하는, 앱이 여러 개 포함된 테스트 환경을 사용하는 것이 좋습니다. GitHub의 SDK 런타임 및 개인 정보 보호 API 저장소에는 Topics API 초기화 및 호출 방법을 보여주는 샘플을 비롯하여 시작하는 데 도움이 되는 개별 Android 스튜디오 프로젝트 집합이 포함되어 있습니다.

주제 계산은 에포크가 끝날 때 이루어집니다. 기본적으로 각 에포크는 7일이지만 이 간격을 수정하여 결과를 얻을 수 있습니다. 이 Android 디버그 브리지 셸 명령어는 에포크 길이를 5분으로 단축합니다.

adb shell device_config put adservices topics_epoch_job_period_ms 300000

get를 사용하여 topics_epoch_job_period_ms 값을 확인할 수 있습니다.

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 객체 목록이 포함된 응답을 생성합니다. 이러한 결과를 복호화하면 이전 Topic 객체와 동일한 JSON 형식의 객체가 생성됩니다.

Topics API는 HPKE (하이브리드 공개 키)의 원샷 구현을 지원합니다. 암호화). 등록된 호출자는 32비트 공개 키를 등록 중에 제공된 공개 암호화 URL 엔드포인트입니다. 이러한 키는 Base64로 인코딩되어야 합니다.

EncryptedTopic 객체에는 3개의 필드가 있습니다. 반환된 주제 목록은 얻은 정보를 공개합니다.

개발 목적으로 Topics API 암호화를 사용 중지하여 테스트할 수 있습니다. 등록 확인 이렇게 하면 API가 테스트 공개 키를 사용하여 암호화하는 방법을 배웠습니다 사용자는 비공개 키를 생성합니다.

제한사항

Topics API의 진행 중인 기능 목록은 출시 노트를 참고하세요.

버그 및 문제 신고

여러분의 의견은 Android의 개인 정보 보호 샌드박스에서 매우 중요한 부분입니다. 발견한 문제나 Android의 개인 정보 보호 샌드박스 개선을 위한 아이디어가 있다면 Google에 알려 주세요.

다음 단계

사용자와 개발자가 사용자의 환경설정 및 요구사항에 맞게 Topics API를 관리하고 맞춤설정하는 방법을 알아보세요.
Android에서 Topics가 작동하는 방식을 이해하고 API 흐름의 핵심 단계를 알아봅니다.

참고 항목

Android의 Topics API에 관해 자세히 알아보려면 리소스를 확인하세요.