운영 키와 콜백 URL은 운영 콘솔에서 설정합니다. 공통 GAD 매체사 계정으로 로그인하며 운영 데이터와 설정은 스테이징과 분리됩니다.

iOS SDK 빠른 시작

GAD iOS SDK 0.9.0 을 앱에 넣고 프로덕션 서버의 광고 목록을 띄웁니다.

운영 콘솔에서 iOS SDK 매체를 등록하고 운영 미디어키를 확보한 뒤 아래 설치를 진행하세요. 운영 매체 등록과 키 확인은 운영 콘솔에서 진행합니다.

1. 설치

Swift Package Manager (권장)

Xcode 의 File ▸ Add Package Dependencies… 에 아래 주소를 넣고 Exact Version으로 0.9.0을 고릅니다.

https://github.com/GPA-KOREA/gad-ios-sdk

Package.swift 로 관리한다면 다음과 같이 적습니다.

dependencies: [
    .package(url: "https://github.com/GPA-KOREA/gad-ios-sdk", exact: "0.9.0")
]

CocoaPods

CocoaPods trunk 에는 등록돼 있지 않습니다. Podfile 에 podspec 주소를 직접 지정합니다.

pod 'GadSDK', :podspec => 'https://raw.githubusercontent.com/GPA-KOREA/gad-ios-sdk/0.9.0/GadSDK.podspec'

2. 초기화와 환경 지정

매체 앱의 사용자 로그인을 마친 뒤 미디어키와 사용자 ID 로 초기화합니다. environment 로 환경을 넘깁니다. 모든 API 는 @MainActor 컨텍스트에서 호출합니다. 로그인 직후 아래 함수를 호출해 초기화하고, 광고 목록을 열 때마다 다시 초기화하지 않습니다.

import GadSDK

@MainActor
func setupGad(mediaKey: String, userId: String) {
    // 프로덕션 서버로 초기화
    Gad.initialize(mediaKey: mediaKey, userId: userId, environment: .production)
}

• environment 를 주지 않는 Gad.initialize(mediaKey:userId:) 는 운영 서버로 접속합니다.
• 이 문서의 초기화 예제는 .production 을 사용합니다. 운영 API 주소는 https://gad.api.gpakorea.com 입니다. 앱의 초기화 설정과 실제 요청 대상을 함께 확인하세요.
• 스테이징으로 초기화한 뒤 환경 없는 초기화를 다시 부르면 운영으로 바뀝니다. 초기화 호출은 한 곳에만 둡니다.
• Gad.setDebugServer 는 폐기 예정입니다. 서버는 environment 로 고릅니다.
• 출시 빌드에는 스테이징 지정을 남기지 않습니다.

3. 광고 목록 띄우기

현재 화면의 UIViewController 에서 호출합니다.

Gad.showAdList(from: self)

SwiftUI 앱에서도 로그인 직후 위 setupGad(mediaKey:userId:) 로 초기화를 마친 뒤, 광고 목록을 열 때 아래 함수를 호출합니다. 현재 최상위 UIViewController 를 찾아 넘깁니다.

import UIKit

@MainActor
func openOfferwall() {
    guard let presenter = UIApplication.shared.connectedScenes
        .compactMap({ $0 as? UIWindowScene })
        .first(where: { $0.activationState == .foregroundActive })?
        .windows.first(where: \.isKeyWindow)?
        .rootViewController else { return }
    Gad.showAdList(from: presenter)
}

4. 확인

1. 운영 콘솔에서 발급한 iOS SDK 미디어키를 사용합니다. 스테이징 키와 구분하세요.
2. 초기화 환경이 .production 으로 지정되어 있고 요청 대상이 https://gad.api.gpakorea.com 인지 확인합니다. 광고 목록에서 운영 광고가 표시되는지 확인합니다.
3. 포스트백 수신 서버의 운영 콜백 URL과 중복 지급 방지 처리가 준비되어 있는지 확인합니다.

테스트 광고로 연동을 검증하려면 상단 환경 이동 버튼으로 스테이징으로 전환하세요.

5. 추적 권한과 개인정보 항목

• SDK 는 광고 ID(IDFA)를 수집하지 않으므로 NSUserTrackingUsageDescription 도 앱 추적 투명성(ATT) 요청도 SDK 때문에 필요하지 않습니다.
• 기기 구분에는 identifierForVendor(IDFV)를 쓰고, 값이 없으면 키체인에 저장한 임의 UUID 를 씁니다. SDK 가 서버로 보내는 adid 가 이 값입니다.
• SDK 에 PrivacyInfo.xcprivacy 가 들어 있습니다. 추적(NSPrivacyTracking)은 하지 않는다고 선언하고, 수집 항목으로 기기 ID·사용자 ID(매체가 넘긴 userId)·고객센터 문의 회신용 이메일을 선언합니다.
• App Store Connect 의 앱 개인정보 항목에는 위 세 가지(기기 ID, 사용자 ID, 이메일)가 SDK 에서 나간다는 점을 반영합니다.

운영 수신 서버의 본문과 재전송 처리는 포스트백 규격을 보세요. 테스트 광고의 검증 절차는 상단 환경 이동 버튼으로 스테이징으로 전환한 뒤 확인합니다.