모바일 앱

이 가이드는 k-ID 연령 확인을 모바일 애플리케이션에 통합하는 모범 사례를 다룹니다. 웹에서는 k-ID 인터페이스가 일반적으로 iframe에 임베드되지만, 모바일 앱은 확인 URL을 효과적으로 표시하기 위해 다른 접근 방식이 필요합니다.

개요

모바일에서 지원되는 웹 임베드는 관할권을 인식하는 확인 인터페이스(AgeKeys, 얼굴 연령 추정, ID 확인 및 기타 방법)를 제시하는 호스팅된 URL입니다. 두 가지 종류가 지원됩니다:

연령 확인 URL: /age-verification/perform-access-age-verification 엔드포인트가 반환하는 url(AgeKit+ 독립형 확인)
연령 보증 챌린지 URL: /age-gate/check가 반환하는 CHALLENGE_AGE_GATE_AGE_ASSURANCE 챌린지의 challenge.url(Automatic age assurance가 활성화된 경우) 또는 /session/upgrade가 반환하는 CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE 챌린지의 challenge.url

이 가이드의 예제는 /age-verification/perform-access-age-verification 엔드포인트를 사용하지만, 동일한 표시 방법과 결과 처리가 이러한 URL 모두에 적용됩니다.

이러한 URL 중 하나를 모바일 애플리케이션에 임베드할 때 표시할 수 있는 여러 옵션이 있으며, 각각 다른 기능과 트레이드오프가 있습니다. 주요 고려 사항은 다음과 같습니다:

AgeKeys 지원: 사용자가 향후 확인을 위해 AgeKeys(FIDO 기반 패스키)를 생성하고 사용할 수 있는지 여부
결과 통신: 확인 결과가 앱으로 전달되는 방식
사용자 경험: 통합 수준과 네이티브 느낌
기기 방향: 확인은 세로 방향에서 가장 잘 작동합니다. 인앱 브라우저 환경은 앱의 방향을 상속하므로, 앱이 가로로 고정된 경우 대신 기본 외부 브라우저를 사용하여 사용자가 세로로 회전할 수 있도록 하세요. 기기 방향을 참조하세요

연령 게이트 및 end-to-end 위젯은 모바일에서 권장되지 않음

연령 확인 및 연령 보증 챌린지 URL은 모바일에서 지원되는 유일한 웹 임베드입니다. 연령 게이트 및 end-to-end 위젯은 모바일 앱에 권장되지 않습니다. 대신 사용자 정의 워크플로를 사용하고 CDK UX 가이드라인에 따라 연령 게이트와 동의 UX 요소를 네이티브로 구축하세요.

모바일 구현 방법

Android 옵션

Android는 확인 URL을 표시하는 세 가지 주요 방법을 제공합니다:

Custom Tabs ⭐ 권장 - 앱의 브랜딩을 유지하는 맞춤형 Chrome 브라우저 탭에서 확인 URL을 엽니다. 이를 통해 사용자를 앱의 컨텍스트 내에 유지하면서 전체 브라우저 기능을 제공합니다. Custom Tabs는 Chrome과 쿠키 및 인증 상태를 공유하여 원활한 경험을 가능하게 합니다.
WebView - Android의 네이티브 WebView 컴포넌트를 사용하여 앱 내에 웹 콘텐츠를 직접 임베드합니다. 구현이 간단하지만 WebView는 최신 웹 표준에 대한 지원이 제한적이며 특정 브라우저 기능에 액세스할 수 없습니다.

권장하지 않음

WebView는 AgeKeys에 필요한 WebAuthn을 지원하지 않습니다. WebView를 사용하여 확인 URL을 임베드하는 경우 사용자는 AgeKeys를 생성하거나 사용할 수 없습니다. 전체 AgeKeys 지원을 갖춘 최상의 사용자 경험을 위해서는 대신 Custom Tabs를 사용하세요.

Trusted Web Activity (TWA) - 주로 Progressive Web Apps용으로 설계된 전체 화면 모드로 웹 콘텐츠를 표시합니다. TWA는 앱과 k-ID 도메인 간에 디지털 자산 링크를 설정해야 합니다. 디지털 자산 링크가 감지되지 않으면 TWA는 자동으로 Custom Tabs로 폴백합니다.

권장하지 않음

Trusted Web Activities는 확인 URL 임베드에 지원되지 않습니다. k-ID의 도메인에서 디지털 자산 링크를 구성해야 하지만 이는 사용할 수 없습니다. 이 경우 TWA가 Custom Tabs로 폴백하므로 더 간단한 구현을 위해 Custom Tabs를 직접 사용하는 것이 좋습니다.

iOS 옵션

iOS는 확인 URL을 표시하는 세 가지 주요 방법을 제공합니다:

ASWebAuthenticationSession ⭐ 권장 - 보안 인증 흐름을 위해 특별히 설계된 이 방법은 시스템 관리 브라우저 보기에서 웹 콘텐츠를 표시합니다. Safari와 쿠키를 공유하고 WebAuthn과 같은 최신 웹 기능에 대한 액세스를 제공하므로 확인 흐름에 이상적입니다.
SFSafariViewController - Safari와 쿠키 및 인증 상태를 공유하는 Safari와 유사한 인터페이스에서 웹 콘텐츠를 표시합니다. 이를 통해 앱 컨텍스트를 유지하면서 친숙한 브라우징 경험을 제공합니다.
WKWebView - 앱 내에 웹 콘텐츠를 임베드하는 Apple의 최신 웹 보기 컴포넌트입니다. Android의 WebView와 유사하게 WKWebView는 특정 웹 표준에 제한이 있으며 모든 브라우저 기능에 액세스할 수 없습니다.

권장하지 않음

WKWebView는 AgeKeys에 필요한 WebAuthn을 지원하지 않습니다. WKWebView를 사용하여 확인 URL을 임베드하는 경우 사용자는 AgeKeys를 생성하거나 사용할 수 없습니다. 전체 AgeKeys 지원을 갖춘 최상의 사용자 경험을 위해서는 대신 ASWebAuthenticationSession을 사용하세요.

기본 브라우저(Android 및 iOS)

기본 외부 브라우저는 Android와 iOS 모두에서 작동합니다. 확인 URL을 인앱 브라우저 환경에서 제시하는 대신 사용자의 기본 브라우저를 별도의 앱으로 실행합니다(Android에서는 Intent.ACTION_VIEW, iOS에서는 UIApplication.open).

전체 AgeKeys 지원 - 브라우저가 WebAuthn을 제공하므로 사용자가 AgeKeys를 생성하고 사용할 수 있습니다.
독립적인 방향 - 브라우저는 별도의 앱이므로 자체 방향을 관리합니다. 이 때문에 가로 방향으로 고정된 앱에 권장되는 방법이며, 사용자가 최상의 확인 경험을 위해 세로로 회전할 수 있습니다. 기기 방향을 참조하세요.
콜백 URL 필요 - 사용자가 앱을 떠나므로 결과는 redirectUrl 콜백을 통해 전달되며, 흐름이 완료되면 앱으로 포커스도 반환됩니다. DOM 메시지는 사용할 수 없습니다.

AgeKeys 지원 제한

AgeKeys는 FIDO 및 WebAuthn 표준을 기반으로 하는 재사용 가능한 익명 연령 증명 자격 증명입니다. 사용자는 한 번 연령을 확인하고 개인 정보를 공개하지 않고 다른 서비스 간에 해당 확인을 재사용할 수 있습니다.

AgeKeys 제한

AgeKeys는 WebAuthn 지원이 필요하며, 이는 Android WebView 또는 iOS WKWebView에서 사용할 수 없습니다. 이러한 컴포넌트를 사용하여 확인 URL을 임베드하는 경우 사용자는 확인 중에 AgeKeys를 옵션으로 볼 수 없으며 확인 성공 후 AgeKeys를 생성할 수 없습니다.

사용자에게 AgeKeys를 활성화하려면 다음 방법 중 하나를 사용해야 합니다:

Android: Custom Tabs
iOS: ASWebAuthenticationSession 또는 SFSafariViewController

기기 방향

연령 확인은 세로 방향에서 가장 잘 작동합니다. 얼굴 연령 추정 및 ID 문서 캡처와 같은 방법은 기기가 세워져 있을 때 완료하기 더 쉬우며, 확인 인터페이스는 세로 방향에 맞게 배치되어 있습니다.

인앱 브라우저 환경(Custom Tabs, ASWebAuthenticationSession, SFSafariViewController 및 WebView/WKWebView)은 앱의 방향 제약 조건을 상속합니다. 게임이나 앱이 가로로 고정되면 확인 인터페이스도 가로로 강제되어 경험이 저하됩니다.

가로 고정 앱을 위한 권장 사항

앱이 가로 방향으로 고정되어 있다면 인앱 브라우저 환경 대신 기기의 기본 외부 브라우저에서 확인 URL을 여세요. 외부 브라우저는 별도의 앱으로 실행되며 자체 방향을 관리하므로, 사용자가 최상의 경험을 위해 기기를 세로로 회전할 수 있습니다.

확인 URL을 생성할 때 redirectUrl 콜백을 설정하세요. 사용자가 확인 흐름을 완료하면 브라우저가 딥 링크로 리디렉션하여 앱이나 게임으로 포커스를 반환합니다.

외부 브라우저는 AgeKeys를 완전히 지원합니다(WebAuthn 사용 가능). Custom Tabs 및 ASWebAuthenticationSession과 마찬가지로 DOM 메시지는 사용할 수 없으므로 결과를 받으려면 콜백 URL을 사용해야 합니다.

다음과 같이 기본 브라우저에서 확인 URL을 엽니다:

iOS (Swift)
Android (Kotlin)

import UIKit

func displayVerificationInBrowser(verificationUrl: URL) {
    // 시스템 기본 브라우저(별도의 앱)를 엽니다. 이 브라우저는 앱의 고정된
    // 방향과 관계없이 자체 방향을 관리합니다.
    UIApplication.shared.open(verificationUrl)
}

import android.app.Activity
import android.content.Intent
import android.net.Uri

fun displayVerificationInBrowser(activity: Activity, verificationUrl: String?) {
    if (verificationUrl == null) {
        // 오류 처리: 확인 URL 생성 실패
        return
    }
    // ACTION_VIEW는 사용자의 기본 브라우저를 별도의 앱으로 실행하며,
    // 앱의 고정 방향과 관계없이 자체 방향을 관리합니다.
    val intent = Intent(Intent.ACTION_VIEW, Uri.parse(verificationUrl))
    activity.startActivity(intent)
}

반환되는 딥 링크는 4단계에 표시된 대로 정확히 처리하세요.

확인 결과 수신

모바일 앱은 사용자가 확인 흐름을 완료한 후 결과를 수신해야 합니다. 두 가지 접근 방식이 있으며 각각 다른 가용성이 있습니다:

필드 존재 규칙, 상태 유형, 구현 가이드를 포함한 확인 결과 분석에 대한 자세한 내용은 확인 이벤트 계약을 참조하세요.

콜백 URL(범용 방법)

권장 접근 방식

모든 구현 방법에 권장되는 접근 방식은 콜백 URL을 사용하는 것입니다. 확인 URL을 생성하기 위해 API를 호출할 때 redirectUrl 매개변수를 포함하세요. 확인 흐름이 완료되면 결과를 쿼리 매개변수로 포함하여 이 URL로 리디렉션합니다.

콜백 URL의 장점:

모든 구현 방법에서 작동
DOM 메시지보다 더 안정적
모바일 앱의 표준 딥 링크 패턴
앱이 백그라운드로 이동해도 결과가 항상 전달됨

콜백 URL 작동 방식

앱에 딥 링크 핸들러를 등록합니다(예: myapp://verification-complete)
API를 호출할 때 딥 링크를 redirectUrl로 포함합니다
확인 페이지가 완료 후 딥 링크로 리디렉션합니다
앱이 딥 링크를 처리하고 결과를 추출합니다

참고

리디렉션은 확인 URL이 브라우저 또는 웹 보기에서 직접 열릴 때만 발생하며 iframe에 임베드된 경우에는 발생하지 않습니다.

콜백 URL 매개변수

확인 페이지가 콜백 URL로 리디렉션할 때 흐름과 관련된 쿼리 매개변수가 포함됩니다. 예를 들어:

연령 확인에는 verificationId와 result가 포함됩니다
URL이 세션 업그레이드에서 온 경우 sessionId와 상태 정보도 포함될 수 있습니다

콜백 URL 예:

myapp://verification-complete?verificationId=7854909b-9124-4bed-9282-24b44c4a3c97&result=PASS

콜백 URL 구현

연령 확인 API를 호출할 때 요청에 redirectUrl을 포함합니다. URL은 다음 중 하나일 수 있습니다:

HTTPS URL: https://example.com/verification-complete
사용자 지정 딥 링크: myapp://verification-complete

DOM 메시지(WebView/WKWebView만)

Android WebView 또는 iOS WKWebView를 사용하는 경우 확인 페이지에서 전송되는 JavaScript 메시지를 수신할 수 있습니다. 이를 통해 다음이 가능합니다:

확인 결과를 실시간으로 수신
웹 보기를 닫는 시점 제어
확인 이벤트에 따라 앱의 UI 업데이트

연령 확인 인터페이스는 Verification.Result 이벤트를 발생시키며, 여기에는 status(예: PASS 또는 FAIL)와 성공 시 확인된 ageCategory가 포함됩니다.

DOM 메시지는 네이티브 코드에서 가로챌 수 있는 postMessage 이벤트로 전송됩니다. 사용 가능한 이벤트에 대한 자세한 내용은 DOM 이벤트 개요를 참조하세요.

제한된 가용성

DOM 메시지는 AgeKeys를 지원하지 않는 WebView와 WKWebView에서만 작동합니다. Custom Tabs, Trusted Web Activity, ASWebAuthenticationSession 또는 SFSafariViewController에서는 사용할 수 없습니다. 이러한 컴포넌트는 AgeKeys를 생성할 수 없으므로 대신 권장 표시 방법과 함께 콜백 URL을 사용하세요.

플랫폼별 구현

iOS WKWebView의 경우 kid라는 이름의 메시지 핸들러를 등록하여 k-ID 이벤트를 네이티브로 수신할 수 있습니다. 확인 페이지가 이 핸들러를 자동으로 감지하고 이벤트를 직접 전송합니다. 그러나 Android WebView에는 postMessage 이벤트를 수신하는 네이티브 메커니즘이 없습니다. JavaScript를 삽입하여 메시지를 수신하고 JavaScript 인터페이스를 통해 네이티브 코드로 전달해야 합니다.

서드파티 앱 인증 흐름

ConnectID와 같은 일부 인증 방법은 인증 프로세스의 일부로 사용자를 서드파티 모바일 앱으로 리디렉션해야 합니다. 예를 들어, ConnectID는 사용자의 은행 앱을 열어 본인 확인을 완료합니다.

서드파티 앱 흐름의 작동 방식

서드파티 앱을 사용하는 인증 방법을 사용할 때 흐름은 여러 애플리케이션을 거쳐 앱으로 돌아옵니다:

단계별 설명:

앱이 서버에 인증 URL을 요청합니다
서버가 API 키를 사용하여 k-ID API를 호출하며 앱의 redirectUrl을 포함합니다
k-ID가 인증 인터페이스를 포함하는 URL을 서버에 반환합니다
서버가 앱에 URL을 반환합니다
앱이 웹 컴포넌트(ASWebAuthenticationSession 또는 Custom Tabs)에서 URL을 엽니다
사용자가 ConnectID와 같은 인증 방법을 선택하면 k-ID UI가 서드파티 인증 앱(예: 은행 앱)으로 딥 링크합니다
인증이 완료되면 서드파티 앱은 기기의 네이티브 브라우저에서 k-ID 결과 페이지로 리디렉션합니다
k-ID가 저장된 redirectUrl을 검색하고 인증 결과와 함께 사용자를 앱으로 리디렉션합니다

서드파티 앱 흐름의 주요 고려 사항

웹 컴포넌트 요구 사항: 이러한 인증 방법은 임베디드 WebView가 아닌 시스템 브라우저 컨텍스트(ASWebAuthenticationSession, Custom Tabs 또는 SFSafariViewController)에서 열어야 합니다. 서드파티 앱 리디렉션 흐름이 올바르게 작동하려면 전체 브라우저 컨텍스트가 필요합니다.

네이티브 브라우저 핸드오프: 서드파티 앱이 인증을 완료한 후 원래 웹 컴포넌트로 직접 돌아가는 대신 기기의 네이티브 브라우저에서 열리는 k-ID URL로 리디렉션됩니다. 이는 모바일 기기에서 앱 간 리디렉션이 작동하는 방식의 플랫폼 제한입니다.

콜백 URL은 필수: 인증 흐름이 여러 앱과 브라우저를 거치기 때문에 redirectUrl 매개변수는 완료 후 사용자를 앱으로 돌려보내는 데 중요합니다. 서드파티 앱 방법을 사용할 수 있는 인증을 시작할 때 항상 redirectUrl을 포함하세요.

서드파티 앱 흐름 테스트

다음 인증 방법은 서드파티 앱 리디렉션을 사용합니다:

ConnectID: 모바일 애플리케이션에서 리디렉션 흐름을 검증하기 위한 테스트 앱이 포함되어 있습니다.

방법 비교

방법	플랫폼	AgeKeys	DOM 메시지	콜백 URL	최적 용도
WebView	Android	❌	✅	✅	권장하지 않음(AgeKeys 지원 없음)
Custom Tabs	Android	✅	❌	✅	대부분의 사용 사례(권장)
Trusted Web Activity	Android	✅	❌	✅	권장하지 않음(디지털 자산 링크 필요)
WKWebView	iOS	❌	✅	✅	권장하지 않음(AgeKeys 지원 없음)
ASWebAuthenticationSession	iOS	✅	❌	✅	대부분의 사용 사례(권장)
SFSafariViewController	iOS	✅	❌	✅	Safari와 유사한 경험
기본 외부 브라우저	Android & iOS	✅	❌	✅	가로 고정 앱(세로 회전 허용)

권장 구현

Android: Custom Tabs

기능과 사용자 경험의 최적 균형을 위해 콜백 URL과 함께 Custom Tabs를 사용합니다.

Custom Tabs를 선택하는 이유:

WebAuthn을 통한 전체 AgeKeys 지원
모든 최신 웹 기능에 대한 액세스
앱 브랜딩을 통한 원활한 사용자 경험
안정적인 콜백 메커니즘
Chrome과 인증 상태 공유

구현 단계:

콜백 URL에 대한 딥 링크 핸들러를 등록합니다
API 요청에 redirectUrl을 포함합니다
Custom Tabs를 사용하여 확인 URL을 엽니다
확인 결과로 딥 링크 콜백을 처리합니다

iOS: ASWebAuthenticationSession

안전하고 네이티브한 규정 준수 흐름을 위해 콜백 URL과 함께 ASWebAuthenticationSession을 사용합니다.

ASWebAuthenticationSession을 선택하는 이유:

WebAuthn을 통한 전체 AgeKeys 지원
모든 최신 웹 기능에 대한 액세스
시스템 관리 보안 UI
Safari와 쿠키 공유
안정적인 콜백 메커니즘

구현 단계:

콜백 URL에 대한 URL 스킴 핸들러를 등록합니다
API 요청에 redirectUrl을 포함합니다
ASWebAuthenticationSession을 사용하여 확인 URL을 표시합니다
확인 결과로 URL 스킴 콜백을 처리합니다

완전한 구현 예제

권장 접근 방식을 구현하는 단계별 예제와 완전한 코드 샘플은 다음과 같습니다:

1단계: 딥 링크 핸들러 등록

iOS (Swift)
Android (Kotlin)

Info.plist에 URL 스킴을 등록합니다:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

AndroidManifest.xml에 인텐트 필터를 추가합니다:

<activity
    android:name=".MainActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" android:host="verification-complete" />
    </intent-filter>
</activity>

2단계: 서버에서 확인 URL 생성

중요

확인 URL은 모바일 앱에서 직접 생성하지 않고 서버에서 생성해야 합니다. 이는 클라이언트 측 코드에 API 키가 노출되는 것을 방지합니다. 모바일 앱은 자체 서버 API를 호출하고, 서버가 k-ID로 서버 간 호출을 수행해야 합니다.

아키텍처 개요

서버 구현

서버는 API 키를 사용하여 /age-verification/perform-access-age-verification 엔드포인트를 호출하며, redirectUrl 딥 링크를 포함합니다:

POST https://game-api.k-id.com/api/v1/age-verification/perform-access-age-verification
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "jurisdiction": "US-CA",
  "criteria": {
    "ageCategory": "DIGITAL_YOUTH_OR_ADULT"
  },
  "options": {
    "redirectUrl": "myapp://verification-complete"
  }
}

참고

테스트를 위해서는 테스트 환경 엔드포인트를 사용하세요: https://game-api.test.k-id.com/api/v1/age-verification/perform-access-age-verification

응답:

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJhbGciOiJFUzM4NCIs...",
  "shortUrl": "https://family.k-id.com/v/7854909b-9124-4bed-9282-24b44c4a3c97?pid=42&s=qr"
}

지원되는 기타 모바일 URL

동일한 표시 및 결과 처리가 연령 보증 챌린지 URL에도 적용됩니다: /age-gate/check의 CHALLENGE_AGE_GATE_AGE_ASSURANCE 챌린지의 challenge.url(Automatic age assurance가 활성화된 경우)과 /session/upgrade의 CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE 챌린지의 challenge.url입니다. URL을 생성하는 엔드포인트만 다릅니다.

모바일 클라이언트 구현

모바일 앱은 서버를 호출하여 확인 URL을 가져옵니다:

iOS (Swift)
Android (Kotlin)

import Foundation

func fetchVerificationUrl(completion: @escaping (URL?) -> Void) {
    // k-ID를 직접 호출하지 말고 여러분의 서버 엔드포인트를 호출하세요
    guard let url = URL(string: "https://your-server.com/api/generate-verification-url") else {
        completion(nil)
        return
    }

    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    // 자체 인증 추가(세션 토큰 등)
    request.setValue("Bearer USER_SESSION_TOKEN", forHTTPHeaderField: "Authorization")

    let requestBody: [String: Any] = [
        "jurisdiction": "US-CA",
        "criteria": [
            "ageCategory": "DIGITAL_YOUTH_OR_ADULT"
        ],
        "options": [
            "redirectUrl": "myapp://verification-complete"
        ]
    ]

    guard let httpBody = try? JSONSerialization.data(withJSONObject: requestBody) else {
        completion(nil)
        return
    }
    request.httpBody = httpBody

    URLSession.shared.dataTask(with: request) { data, response, error in
        guard error == nil,
              let httpResponse = response as? HTTPURLResponse,
              (200...299).contains(httpResponse.statusCode),
              let data = data,
              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
              let verificationUrlString = json["url"] as? String,
              let verificationUrl = URL(string: verificationUrlString) else {
            completion(nil)
            return
        }
        completion(verificationUrl)
    }.resume()
}

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject
import java.io.IOException

fun fetchVerificationUrl(callback: (String?) -> Unit) {
    val client = OkHttpClient()
    val mediaType = "application/json".toMediaType()

    val requestBody = JSONObject().apply {
        put("jurisdiction", "US-CA")
        put("criteria", JSONObject().apply {
            put("ageCategory", "DIGITAL_YOUTH_OR_ADULT")
        })
        put("options", JSONObject().apply {
            put("redirectUrl", "myapp://verification-complete")
        })
    }.toString().toRequestBody(mediaType)

    // k-ID를 직접 호출하지 말고 여러분의 서버 엔드포인트를 호출하세요
    val request = Request.Builder()
        .url("https://your-server.com/api/generate-verification-url")
        .post(requestBody)
        // 자체 인증 추가(세션 토큰 등)
        .addHeader("Authorization", "Bearer USER_SESSION_TOKEN")
        .addHeader("Content-Type", "application/json")
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            if (!response.isSuccessful) {
                callback(null)
                return
            }
            response.body?.use { body ->
                try {
                    val jsonResponse = JSONObject(body.string())
                    val verificationUrl = jsonResponse.optString("url", null)
                    callback(verificationUrl)
                } catch (e: Exception) {
                    callback(null)
                }
            } ?: callback(null)
        }

        override fun onFailure(call: Call, e: IOException) {
            callback(null)
        }
    })
}

3단계: 확인 URL 표시

iOS (Swift)
Android (Kotlin)

import AuthenticationServices

// 세션을 속성으로 저장하여 할당 해제 방지
var authSession: ASWebAuthenticationSession?

func displayVerification(verificationUrl: URL) {
    authSession = ASWebAuthenticationSession(
        url: verificationUrl,
        callbackURLScheme: "myapp"
    ) { callbackURL, error in
        if let error = error {
            // 오류 처리(사용자 취소 등)
            return
        }
        if let callbackURL = callbackURL {
            handleVerificationCallback(callbackURL)
        }
    }
    authSession?.presentationContextProvider = self
    authSession?.start()
}

import android.app.Activity
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent

fun displayVerification(activity: Activity, verificationUrl: String?) {
    if (verificationUrl == null) {
        // 오류 처리: 확인 URL 생성 실패
        return
    }
    val builder = CustomTabsIntent.Builder()
    val customTabsIntent = builder.build()
    val uri = Uri.parse(verificationUrl)
    customTabsIntent.launchUrl(activity, uri)
}

4단계: 콜백 처리

iOS (Swift)
Android (Kotlin)

func handleVerificationCallback(_ callbackURL: URL) {
    // 예상하는 콜백 URL인지 확인
    guard callbackURL.scheme == "myapp",
          callbackURL.host == "verification-complete",
          let components = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false),
          let queryItems = components.queryItems else {
        return
    }

    let verificationId = queryItems.first(where: { $0.name == "verificationId" })?.value
    let result = queryItems.first(where: { $0.name == "result" })?.value
    // 확인 URL이 세션 업그레이드에서 온 경우에만 존재
    let sessionId = queryItems.first(where: { $0.name == "sessionId" })?.value

    // 확인 결과에 따라 UI 업데이트
    if result == "PASS" {
        // 성공한 확인 처리
    } else if result == "FAIL" {
        // 실패한 확인 처리
    }

    // 선택 사항: API 엔드포인트를 사용하여 서버 측에서 확인
    if let verificationId = verificationId {
        verifyResultServerSide(verificationId: verificationId)
    } else if let sessionId = sessionId {
        verifyResultServerSide(sessionId: sessionId)
    }
}

import android.content.Intent
import android.net.Uri

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent) // 중요: 새 인텐트가 사용되도록 함
    val data: Uri? = intent.data
    if (data != null && data.scheme == "myapp" && data.host == "verification-complete") {
        val verificationId = data.getQueryParameter("verificationId")
        val result = data.getQueryParameter("result")
        // 확인 URL이 세션 업그레이드에서 온 경우에만 존재
        val sessionId = data.getQueryParameter("sessionId")

        // 확인 결과에 따라 UI 업데이트
        if (result == "PASS") {
            // 성공한 확인 처리
        } else {
            // 실패한 확인 처리
        }

        // 선택 사항: API 엔드포인트를 사용하여 서버 측에서 확인
        if (verificationId != null) {
            verifyResultServerSide(verificationId)
        } else if (sessionId != null) {
            verifyResultServerSide(sessionId)
        }
    }
}

모범 사례

보안 및 데이터 무결성을 위해 클라이언트 측 데이터에만 의존하지 않고 적절한 API 엔드포인트를 사용하여 서버 측에서 결과를 항상 확인하세요. 확인의 경우 /age-verification/get-status 엔드포인트를 사용하고, 확인 URL이 세션 업그레이드에서 온 경우 /session/get을 사용하세요. 필드 존재 규칙, 상태 유형, 구현 가이드를 포함한 확인 결과 분석에 대한 자세한 내용은 확인 이벤트 계약을 참조하세요. 웹훅을 사용하는 경우 재시도 정책과 누락된 이벤트 복구 방법에 대해 전달, 재시도 및 복구를 참조하세요.

지원되는 모바일 웹 임베드

모바일에서는 다음 호스팅된 URL만 임베드하세요. 모두 동일한 방식으로 표시되고 처리됩니다:

Access age verification의 연령 확인 URL(/age-verification/perform-access-age-verification): 세션이 없는 독립형 연령 확인(AgeKit+). 워터폴 플로우와 단일 방식 흐름을 지원합니다.
/age-gate/check의 CHALLENGE_AGE_GATE_AGE_ASSURANCE 챌린지 URL: 제품에 Automatic age assurance가 활성화되어 있고 플레이어가 신고한 연령을 증명해야 할 때 반환되는 challenge.url입니다.
/session/upgrade의 CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE 챌린지 URL: 권한에 연령 보증이 필요할 때 반환되는 challenge.url입니다.

연령 게이트 및 동의 흐름 자체는 연령 게이트 및 end-to-end 위젯이 모바일에서 권장되지 않으므로, 사용자 정의 워크플로로 UX를 네이티브로 구축하고 CDK UX 가이드라인을 따르세요.

개요​

모바일 구현 방법​

Android 옵션​

iOS 옵션​

기본 브라우저(Android 및 iOS)​

AgeKeys 지원 제한​

기기 방향​

확인 결과 수신​

콜백 URL(범용 방법)​

콜백 URL 작동 방식​

콜백 URL 매개변수​

콜백 URL 구현​

DOM 메시지(WebView/WKWebView만)​

서드파티 앱 인증 흐름​

서드파티 앱 흐름의 작동 방식​

서드파티 앱 흐름의 주요 고려 사항​

서드파티 앱 흐름 테스트​

방법 비교​

권장 구현​

Android: Custom Tabs​

iOS: ASWebAuthenticationSession​

완전한 구현 예제​

1단계: 딥 링크 핸들러 등록​

2단계: 서버에서 확인 URL 생성​

아키텍처 개요​

서버 구현​

모바일 클라이언트 구현​

3단계: 확인 URL 표시​

4단계: 콜백 처리​

지원되는 모바일 웹 임베드​

개요

모바일 구현 방법

Android 옵션

iOS 옵션

기본 브라우저(Android 및 iOS)

AgeKeys 지원 제한

기기 방향

확인 결과 수신

콜백 URL(범용 방법)

콜백 URL 작동 방식

콜백 URL 매개변수

콜백 URL 구현

DOM 메시지(WebView/WKWebView만)

서드파티 앱 인증 흐름

서드파티 앱 흐름의 작동 방식

서드파티 앱 흐름의 주요 고려 사항

서드파티 앱 흐름 테스트

방법 비교

권장 구현

Android: Custom Tabs

iOS: ASWebAuthenticationSession

완전한 구현 예제

1단계: 딥 링크 핸들러 등록

2단계: 서버에서 확인 URL 생성

아키텍처 개요

서버 구현

모바일 클라이언트 구현

3단계: 확인 URL 표시

4단계: 콜백 처리

지원되는 모바일 웹 임베드