연령 신호 요청

이 문서에서는 Play 연령 신호 API를 사용하여 연령 신호를 요청하는 방법을 설명합니다.

Play Age Signals 0.0.4 SDK에는 연령 신호 요청을 간소화하고 사용자 선택 기반 모델을 지원하도록 설계된 두 가지 함수 아키텍처가 도입되었습니다. 연령 신호를 요청하려면 다음 대략적인 워크플로를 사용하세요.

ageSignalsStatus를 반환하는 requestAgeSignalsAccess(Activity) 메서드를 호출합니다. ageSignalsStatus 값은 SHARED, NOT_SHARED 또는 VERIFICATION_REQUIRED일 수 있습니다.

  • ageSignalsStatus == NOT_SHARED인 경우: 앱이 API 응답에서 연령 신호를 받지 않습니다.
  • ageSignalsStatus == SHARED인 경우: checkAgeSignals() 메서드를 호출합니다. 사용자 또는 부모가 연령 신호를 공유하기로 결정한 경우 API 응답의 일부로 연령 신호를 수신하며, 응답을 처리하는 방법을 결정할 수 있습니다.
  • ageSignalsStatus == VERIFICATION_REQUIRED: 사용자의 연령을 알 수 없고 사용자가 연령 인증 및 연령 신호 공유가 의무인 관할권 또는 지역에 거주하는 경우 이러한 지역에서 Google Play로부터 연령 신호를 받으려면 사용자에게 Play 스토어를 방문하여 상태를 해결하도록 요청하세요.

requestAgeSignalsAccess(Activity) 메서드는 지역에 필수 연령 공유가 적용되는지 여부에 따라 다른 값을 반환합니다.

  • 앱 스토어에서 개발자에게 인증된 연령 정보를 제공하도록 요구하는 법률이 있는 미국 주에 거주하는 자격 보유자의 경우 인앱 메시지가 트리거되지 않습니다. 대신 사용자가 Play 스토어 앱을 방문할 때 인증 또는 감독 기능을 설정하라는 메시지가 표시됩니다. ageSignalsStatus 값을 사용하여 인증 상태를 확인합니다.
  • 사용자 또는 부모의 선택에 따라 연령 공유가 이루어지는 다른 지역의 사용자의 경우:
    • 사용자의 설정이 공유하기 전에 확인인 경우 인앱 프롬프트가 표시됩니다. 사용자가 연령 공유에 동의하면 ageSignalsStatus 값은 SHARED이고, 그렇지 않으면 NOT_SHARED입니다.
    • 사용자의 설정이 Always Share인 경우 인앱 메시지가 표시되지 않으며 ageSignalsStatus 값은 SHARED입니다.
    • 사용자의 설정이 공유 안함인 경우 인앱 메시지가 표시되지 않고 ageSignalsStatus 값은 NOT_SHARED입니다.
    • 감독 대상 사용자의 경우 부모는 Family Link 앱 설정에서 자녀의 연령을 공유하도록 선택할 수 있습니다. 부모가 연령을 공유하기로 선택하면 ageSignalsStatus 값이 SHARED이 되고, 그렇지 않으면 NOT_SHARED이 됩니다.

인앱 프롬프트 및 연령대 공유 설정을 포함하여 Google Play에서 연령 공유가 작동하는 방식을 이해하려면 Google Play의 연령대 공유를 참고하세요.

다음 예는 연령 신호를 요청하는 방법을 보여줍니다.

Kotlin

// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
val ageSignalsManager = AgeSignalsManagerFactory.create(applicationContext)

// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
val accessRequest = AgeSignalsAccessRequest.builder()
    .setActivity(this)
    .build()

ageSignalsManager.requestAgeSignalsAccess(accessRequest)
    .addOnSuccessListener { accessResult ->
        if (accessResult.ageSignalsStatus() == AgeSignalsStatus.SHARED) {
            // The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
            // Retrieve the actual age signals.
            retrieveAgeSignals(ageSignalsManager)
        } else {
            // Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
        }
    }
    .addOnFailureListener { exception ->
        // Handle API/Play Store connection and system errors
        handleAgeSignalsError(exception)
    }

private fun retrieveAgeSignals(manager: AgeSignalsManager) {
    // 3. Perform the actual age signals query once sharing is active.
    manager.checkAgeSignals(AgeSignalsRequest.builder().build())
        .addOnSuccessListener { ageSignalsResult ->
            val installId = ageSignalsResult.installId()
            val ageLower = ageSignalsResult.ageLower()
            val ageUpper = ageSignalsResult.ageUpper()
            val significantChangeDate = ageSignalsResult.significantChangeApprovalDate()
            val ageRangeSource = ageSignalsResult.ageRangeSource()

            if (ageLower != null) {
                if (ageUpper != null) {
                    // The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
                } else {
                    // The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
                }
            } else {
                // Both bounds are null: The user is not sharing their age
            }
        }
        .addOnFailureListener { exception ->
            handleAgeSignalsError(exception)
        }
}

자바

// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
AgeSignalsManager ageSignalsManager = AgeSignalsManagerFactory.create(getApplicationContext());

// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
AgeSignalsAccessRequest accessRequest = AgeSignalsAccessRequest.builder()
    .setActivity(this)
    .build();

ageSignalsManager.requestAgeSignalsAccess(accessRequest)
    .addOnSuccessListener(accessResult -> {
        Integer status = accessResult.ageSignalsStatus();
        if (status == AgeSignalsStatus.SHARED) {
            // The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
            // Retrieve the actual age signals.
            retrieveAgeSignals(ageSignalsManager);
        } else {
            // Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
        }
    })
    .addOnFailureListener(exception -> {
        // Handle API/Play Store connection and system errors
    });

private void retrieveAgeSignals(AgeSignalsManager manager) {
    // 3. Perform the actual age signals query once sharing is active.
    manager.checkAgeSignals(AgeSignalsRequest.builder().build())
        .addOnSuccessListener(ageSignalsResult -> {
            String installId = ageSignalsResult.installId();
            Integer ageLower = ageSignalsResult.ageLower();
            Integer ageUpper = ageSignalsResult.ageUpper();
            Date significantChangeDate = ageSignalsResult.significantChangeApprovalDate();
            @AgeRangeSource Integer ageRangeSource = ageSignalsResult.ageRangeSource();

            if (ageLower != null) {
                if (ageUpper != null) {
                    // The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
                } else {
                    // The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
                }
            } else {
                // Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
            }
        })
        .addOnFailureListener(exception -> {
            handleAgeSignalsError(exception);
        });
}

코드에 관한 핵심 사항

  • requestAgeSignalsAccess(Activity) 메서드는 사용자의 현재 연령 신호 및 연령 신호 공유 상태를 차단하는 검사를 실행합니다.
  • requestAgeSignalsAccess(Activity)를 호출하면 Play는 감독 대상이 아닌 사용자에게만 내장된 인앱 메시지를 표시합니다. 감독 대상 사용자의 부모는 Family Link 앱에서 연령 공유 설정을 관리하여 자녀의 연령을 공유할지 선택할 수 있습니다.
  • 사용자가 연령 공유를 닫거나 거부하면 인앱 메시지가 몇 번 표시된 후 표시가 중단됩니다.
  • checkAgeSignals() 메서드는 API 응답에서 연령 신호 값을 가져옵니다. 이 메서드는 ageRangeSource, ageUpper, ageLower, 기타 중요한 변경 값을 반환합니다.