> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UMP 연동

> GDPR/CCPA 규정 준수를 위한 Google UMP 연동

## 개요

UMP(User Messaging Platform) SDK는 GDPR(일반 데이터 보호 규정) 및 CCPA(캘리포니아 소비자 개인정보 보호법) 준수를 위해 맞춤형 광고에 대한 사용자 동의를 관리합니다.

<Note>
  UMP 연동에는 `adrop-ads-backfill` 모듈이 필요합니다. [시작하기](/ko/sdk/flutter/overview)의 설치 가이드를 먼저 완료해주세요.
</Note>

***

## 기본 사용법

Adrop 초기화 후 Consent Manager를 사용하여 사용자 동의를 요청합니다.

```dart theme={null}
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

// Adrop.initialize() 호출 후 사용
Adrop.consentManager.requestConsentInfoUpdate((result) {
  if (result.error != null) {
    debugPrint('Consent error: ${result.error}');
  }
});
```

***

## 동의 상태

Consent Manager는 다음 상태 중 하나를 반환합니다:

| 상태            | 설명                |
| ------------- | ----------------- |
| `unknown`     | 동의 상태가 아직 결정되지 않음 |
| `required`    | 동의 필요 (팝업이 표시됨)   |
| `notRequired` | 동의 불필요 (비GDPR 지역) |
| `obtained`    | 이미 동의 완료됨         |

***

## 동의 결과

`requestConsentInfoUpdate` 콜백은 다음 프로퍼티를 가진 `AdropConsentResult` 객체를 반환합니다:

| 프로퍼티                     | 타입                   | 설명                    |
| ------------------------ | -------------------- | --------------------- |
| `status`                 | `AdropConsentStatus` | 현재 동의 상태              |
| `canRequestAds`          | `bool`               | 광고 요청 가능 여부           |
| `canShowPersonalizedAds` | `bool`               | 개인화 광고 표시 가능 여부       |
| `error`                  | `String?`            | 오류 메시지 (오류가 없으면 null) |

```dart theme={null}
Adrop.consentManager.requestConsentInfoUpdate((result) {
  if (result.error != null) {
    debugPrint('동의 오류: ${result.error}');
    return;
  }

  debugPrint('상태: ${result.status}');
  debugPrint('광고 요청 가능: ${result.canRequestAds}');
  debugPrint('개인화 광고 표시 가능: ${result.canShowPersonalizedAds}');
});
```

***

## 추가 메서드

동의 상태와 광고 요청 가능 여부를 개별적으로 조회할 수도 있습니다:

```dart theme={null}
// 현재 동의 상태 조회
final status = await Adrop.consentManager.getConsentStatus();
debugPrint('현재 상태: $status');

// 광고 요청 가능 여부 확인
final canRequest = await Adrop.consentManager.canRequestAds();
if (canRequest) {
  // 광고 로드
}
```

| 메서드                                  | 반환 타입                        | 설명                            |
| ------------------------------------ | ---------------------------- | ----------------------------- |
| `requestConsentInfoUpdate(listener)` | `Future<void>`               | 동의 정보 업데이트 요청 및 필요 시 동의 양식 표시 |
| `getConsentStatus()`                 | `Future<AdropConsentStatus>` | 현재 동의 상태 조회                   |
| `canRequestAds()`                    | `Future<bool>`               | 광고 요청 가능 여부 확인                |
| `setDebugSettings(geography)`        | `Future<void>`               | 테스트용 디버그 지역 설정                |
| `reset()`                            | `Future<void>`               | 동의 정보 초기화                     |

***

## 디버그 설정 (테스트 모드)

개발 중에 GDPR/CCPA 동의 흐름을 테스트하세요:

```dart theme={null}
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

// 동의 요청 전 디버그 지역 설정
// 기기 ID는 자동으로 적용됨
await Adrop.consentManager.setDebugSettings(AdropConsentDebugGeography.eea);  // GDPR 테스트

// 테스트를 위한 동의 초기화
await Adrop.consentManager.reset();
```

### 디버그 지역

| 지역                 | 설명                  |
| ------------------ | ------------------- |
| `disabled`         | 실제 기기 위치 사용         |
| `eea`              | GDPR 테스트 (유럽 경제 지역) |
| `regulatedUSState` | CCPA 테스트 (캘리포니아 등)  |
| `other`            | 규제가 없는 지역 테스트       |

<Warning>
  디버그 설정은 개발 중에만 사용해야 합니다. 프로덕션 배포 전에 제거하거나 비활성화하세요.
</Warning>

***

## 전체 예제

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

class ConsentExample extends StatefulWidget {
  const ConsentExample({super.key});

  @override
  State<ConsentExample> createState() => _ConsentExampleState();
}

class _ConsentExampleState extends State<ConsentExample> {
  String _consentStatus = 'unknown';

  @override
  void initState() {
    super.initState();
    _initializeConsent();
  }

  Future<void> _initializeConsent() async {
    // 먼저 Adrop 초기화
    await Adrop.initialize(false);

    // 디버그 모드에서 디버그 설정
    const bool isDebug = bool.fromEnvironment('dart.vm.product') == false;
    if (isDebug) {
      await Adrop.consentManager.setDebugSettings(AdropConsentDebugGeography.eea);
    }

    // 동의 정보 업데이트 요청
    Adrop.consentManager.requestConsentInfoUpdate((result) {
      if (result.error != null) {
        debugPrint('동의 오류: ${result.error}');
      } else {
        setState(() {
          _consentStatus = result.status.toString();
        });
      }
    });
  }

  Future<void> _resetConsent() async {
    await Adrop.consentManager.reset();
    await _initializeConsent();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('동의 상태: $_consentStatus'),
            const SizedBox(height: 16),
            ElevatedButton(
              onPressed: _resetConsent,
              child: const Text('동의 초기화'),
            ),
          ],
        ),
      ),
    );
  }
}
```

***

## 모범 사례

<CardGroup cols={2}>
  <Card title="조기 요청" icon="clock">
    SDK 초기화 직후, 앱 라이프사이클 초기에 동의를 요청하세요.
  </Card>

  <Card title="오류 처리" icon="triangle-exclamation">
    동의 오류를 적절히 처리하고 대체 동작을 제공하세요.
  </Card>

  <Card title="모든 시나리오 테스트" icon="vial">
    배포 전에 디버그 설정을 사용하여 모든 동의 시나리오를 테스트하세요.
  </Card>

  <Card title="사용자 선택 존중" icon="user-check">
    동의를 얻거나 거부된 후에는 사용자의 선택을 존중하고 반복적으로 요청하지 마세요.
  </Card>
</CardGroup>

***

## 관련 문서

<CardGroup cols={2}>
  <Card title="타겟팅" icon="bullseye" href="/ko/sdk/flutter/targeting">
    사용자 및 문맥 타겟팅 설정
  </Card>

  <Card title="시작하기" icon="rocket" href="/ko/sdk/flutter/overview">
    SDK 설치 및 설정 가이드
  </Card>

  <Card title="레퍼런스" icon="book" href="/ko/sdk/flutter/reference">
    타입, 메서드, 에러 코드
  </Card>
</CardGroup>