Topics API 개발자 가이드

의견 보내기

Topics API는 사용자의 앱 사용을 기반으로 기기 내에서 대략적인 관심분야 신호를 추론합니다. 이러한 신호를 주제라고 하며, 앱 전체에서 개별 사용자를 추적하지 않고 관심분야 기반 광고를 지원하도록 광고주와 공유합니다. 디자인 제안서에서 Topics API에 관해 자세히 알아보세요.

설정

Topics 분류는 오픈소스 Chrome 분류와 유사하며 향후 출시는 기기 내 분류를 포함한 Android 관련 시스템으로 변경됩니다. Android 개인 정보 보호 샌드박스 개발자 프리뷰 SDK를 사용 중인지 확인하세요. 이 버전이 개인 정보 보호 API가 포함된 유일한 SDK 버전이기 때문입니다. 아래와 같이 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 리소스를 지정합니다(예: res/xml/ad_services_config.xml). allowAllToAccess 속성을 사용하여 모든 SDK에 대한 액세스 권한을 부여하거나 allowSdksToAccess 속성을 사용하여 개별 SDK에 대한 액세스 권한을 부여합니다.

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

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

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

public void getTopics (GetTopicsRequest getTopicsRequest, Executor executor,
    OutcomeReceiver<GetTopicsResponse, AdServicesException> callback)

이 메서드를 사용하려면 TopicsManager 객체와 주제 데이터를 수신하는 데 필요한 매개변수를 초기화합니다. 매개변수를 초기화하려면 GetTopicsRequest, Executor, 콜백의 OutcomeReceiver를 만듭니다. GetTopicsRequest는 주제 데이터를 가져오는 데 필요한 정보를 전달하고 Executor는 getTopics()가 UI 스레드에서 실행되도록 허용하며 OutcomeReceiver 콜백은 결과를 비동기적으로 처리합니다. 예를 들면 다음과 같습니다.

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val getTopicsRequest = GetTopicsRequest.Builder(mContext)
    mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback)
}

private var mCallback: OutcomeReceiver<GetTopicsResponse, GetTopicsException> =
    object : OutcomeReceiver<GetTopicsResponse, GetTopicsException> {
        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: GetTopicsException) {
            // 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();
    GetTopicsRequest.Builder getTopicsRequest = new GetTopicsRequest.Builder(mContext);
    mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback);
}

OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse,
                                                GetTopicsException>() {
    @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 GetTopicsException error) {
        // handle error
        Log.i("Topic", "Error, did not return successfully");

    }
};

주제 모음 요청

설정이 준비되면 getTopics() 메서드의 결과로 GetTopicsResponse를 수신하도록 호출할 수 있습니다.

mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, GetTopicsException>)

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

위 호출을 통해, 오픈소스 분류 중에서 사용자와 관련된 주제에 해당하는 ID 값이 포함된 Topics 객체의 목록이나 관련 오류가 제공됩니다. 주제는 다음 예와 유사합니다.

/Internet & Telecom/Text & Instant Messaging

반환될 수 있는 가능한 주제 목록은 분류를 참고하세요. 이 분류는 변경될 수 있습니다.

테스트

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

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

주제 계산은 '에포크'가 끝날 때 이루어집니다. 기본적으로 각 에포크는 7일이지만 다음 Android 디버그 브리지 셸 명령어를 사용하면 더 빠르게 결과를 얻도록 이 간격을 수정할 수 있습니다.

# Shortens the epoch length to 5 minutes.
adb shell setprop debug.adservices.topics_epoch_job_period_ms 300000

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

adb shell getprop debug.adservices.topics_epoch_job_period_ms

에포크 계산을 수동으로 트리거하려면 다음 명령어를 실행하세요.

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

제한사항

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

버그 및 문제 신고

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