iOS SDK 설정 시 CocoaPods 프레임워크 서명 오류 해결 방법

Swift 프로젝트 아키텍처에서 SDK 엔진 초기화하기

프레임워크를 연결한 후 애플리케이션 라이프사이클 델리게이트 내에서 SDK를 초기화합니다. 정확한 SDK 릴리스에 문서화된 라이프사이클 시점에서 SDK를 초기화하세요. 현재 공개된 예제에서는 콜드 스타트 유니버설 링크(Universal Link) 파라미터와 동적 설치 페이로드를 캡처하기 위해 application(_:didFinishLaunchingWithOptions:)에서 초기화합니다. 배포된 정확한 OpoInstall SDK 버전에 대해 델리게이트 프로토콜 및 데이터 모델 타입 이름(예: OpoinstallData 또는 OpoInstallData)을 확인하세요.

개발자는 상세한 델리게이트 메서드 정의와 동적 파라미터 콜백 서명에 대해 iOS 어트리뷰션 SDK 문서를 검토할 수 있습니다.

아래의 구현 스니펫은 OpoInstallDelegate를 채택하고 최신 Swift 코드베이스 전반에서 SDK 초기화를 트리거하는 방법을 보여줍니다.

// AppDelegate.swift - OpoInstall iOS SDK 초기화
// iOS 애플리케이션 델리게이트 내부에 배치하세요

import UIKit
import libOpoInstallSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate, OpoInstallDelegate {

    var window: UIWindow?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        // 델리게이트 리스너와 함께 OpoInstall SDK 초기화
        OpoInstallSDK.initWith(self)
        
        return true
    }

    // 콜백 메서드: 딥 링크를 통해 앱이 실행될 때 검색된 파라미터 처리
    func getWakeUpParams(_ appData: OpoinstallData?) {
        if let customData = appData?.data {
            print("OpoInstall SDK: Custom Launch Parameters = \(customData)")
        }
        if let channelCode = appData?.channelCode {
            print("OpoInstall SDK: Channel ID = \(channelCode)")
        }
    }
}

iOS 프로젝트 타깃을 위한 수동 프레임워크 임포트 워크플로

엔터프라이즈 빌드 환경에서 CocoaPods보다 수동 임포트를 선택해야 하는 경우

CocoaPods는 패키지 관리를 단순화하지만, 특정 엔터프라이즈 개발 환경은 엄격한 보안 또는 빌드 환경 제약을 강제합니다. 다음과 같은 경우 수동 프레임워크 통합이 선호됩니다.

• 저장소 격리: 빌드 시스템이 아웃바운드 인터넷 연결을 제한하여 컴파일 중 pod install 의존성 가져오기를 방지합니다.
• 빌드 파이프라인 속도: CocoaPods 분석 및 스크립트 실행 단계를 제거하여 CI/CD 컴파일 시간을 단축합니다.
• 직접 바이너리 제어: 보안 규정 준수 정책에 따라 프로젝트에 포함하기 전에 정확한 .xcframework 아티팩트에 대한 정적 바이너리 분석이 요구됩니다.

XCFramework 아티팩트 다운로드 및 임베딩

의존성 관리자 없이 SDK를 수동으로 임포트하려면 최신 iOS SDK 프레임워크 패키지를 다운로드합니다. 배포 아카이브를 압축 해제하여 컴파일된 OpoInstallSDK.xcframework 디렉터리를 찾습니다.

임베딩하기 전에 XCFramework 슬라이스가 정적(static)인지 동적(dynamic)인지 식별하려면 터미널에서 file 명령어를 실행합니다.

# 바이너리 아키텍처 슬라이스 유형 조회
file OpoInstallSDK.xcframework/ios-arm64/OpoInstallSDK.framework/OpoInstallSDK

바이너리를 Xcode에 통합하려면 다음 단계를 따르세요.

• 1단계: Xcode에서 메인 애플리케이션 프로젝트를 엽니다.
• 2단계: OpoInstallSDK.xcframework 디렉터리를 기본 타깃 프레임워크 그룹 아래의 Xcode 프로젝트 내비게이터로 드래그합니다.
• 3단계: 대화 상자 프롬프트에서 Copy items if needed(필요한 경우 항목 복사)를 체크하고 Add to targets(타깃에 추가) 아래에서 기본 애플리케이션 타깃을 선택합니다.

Link Binary With Libraries 및 프레임워크 검색 경로 구성

Xcode 내에서 애플리케이션의 타깃 구성으로 이동합니다.

• Build Phases: Link Binary With Libraries 섹션을 확장합니다. OpoInstallSDK.xcframework가 나열되어 있는지 확인합니다.
• Build Settings: Framework Search Paths(FRAMEWORK_SEARCH_PATHS)를 검색합니다. 수동으로 추가된 프레임워크를 포함하는 디렉터리 경로가 있는지 확인합니다.
• 시스템 의존성: 통합 중인 정확한 SDK 릴리스에 문서화된 Apple 시스템 프레임워크(예: AdSupport.framework 또는 WebKit.framework)만 추가합니다. 검증되지 않은 레거시 프레임워크는 추가하지 마세요.

동적 바이너리와 정적 바이너리 간 Embed 및 Sign 정책 설정

애플리케이션 타깃을 선택하고 General 탭으로 이동합니다. Frameworks, Libraries, and Embedded Content 섹션을 찾습니다.

• 동적 프레임워크: 임베드 옵션을 Embed & Sign으로 설정합니다. 동적 프레임워크는 런타임에 동적 링커(dyld)가 로드할 수 있도록 최종 앱 번들의 Frameworks 디렉터리 내에 상주해야 하며, Xcode는 아카이빙 중에 개발팀의 코드 서명을 적용합니다.
• 리소스가 없는 정적 프레임워크: 바이너리를 연결하는 것으로 충분하며, 정적 코드는 메인 애플리케이션 실행 파일에 직접 컴파일되므로 일반적으로 프레임워크를 임베딩할 필요가 없습니다.
• 리소스가 포함된 정적 프레임워크(프라이버시 매니페스트 포함): SDK 벤더의 배포 지침을 따릅니다. 임베디드 리소스를 패키징하도록 구축된 Xcode 15+ 정적 프레임워크의 경우, Apple은 Embed & Sign으로 프레임워크를 추가하는 것을 문서화하고 있습니다. Xcode는 이미 정적으로 연결된 실행 파일 바이너리를 생략하면서 프레임워크 번들과 그 임베디드 리소스는 보존하고 서명합니다.

CocoaPods에서 PrivacyInfo.xcprivacy 서명 충돌 문제 해결

서드파티 프레임워크 의존성에 대한 Apple 프라이버시 매니페스트 요구사항

서드파티 SDK는 API 사용량, 데이터 수집 관행, 추적 동작 및 SDK가 명시적 매니페스트 요구사항이 적용되는 Apple의 공개 SDK 목록에 속하는지 여부에 따라 PrivacyInfo.xcprivacy 매니페스트를 포함해야 할 수 있습니다.

현재 OpoInstall 배포판에는 PrivacyInfo.xcprivacy 매니페스트가 포함되어 있습니다. 개발자는 아카이빙하기 전에 배포된 특정 SDK 버전과 Apple의 최신 제출 지침에 대해 해당 선언을 확인해야 합니다.

중복된 프라이버시 매니페스트 리소스 충돌 해결

여러 서드파티 의존성을 통합하는 애플리케이션을 빌드할 때, Xcode는 아카이브된 앱과 연결된 SDK 번들 전반에서 프라이버시 매니페스트를 찾아내며, 통합된 프라이버시 선언을 감시하기 위한 Xcode 프라이버시 보고서를 생성할 때 해당 선언을 집계합니다.

프로젝트가 메인 타깃의 Copy Bundle Resources 단계 내에 중복된 프라이버시 매니페스트 파일을 잘못 포함하는 경우, Xcode가 다음과 같은 빌드 경고나 오류를 발생시킬 수 있습니다.

Multiple commands produce '.../PrivacyInfo.xcprivacy'

이 충돌을 해결하려면:

프라이버시 매니페스트 위치: iOS XCFramework의 경우, PrivacyInfo.xcprivacy는 XCFramework 루트 컨테이너 디렉터리에 배치되는 것이 아니라 각 플랫폼별 프레임워크 변형 내(예: OpoInstallSDK.xcframework/ios-arm64/OpoInstallSDK.framework/PrivacyInfo.xcprivacy)에 위치해야 합니다.
메인 앱 리소스: 호스트 애플리케이션 프라이버시 선언은 메인 타깃 리소스에 유지하고, SDK 프레임워크 변형이 각자의 매니페스트 파일을 내부적으로 관리하도록 허용합니다.

PrivacyInfo.xcprivacy 내의 필수 이유 API 선언 검증

프라이버시 매니페스트의 내용을 검사하여 선언된 모든 API 카테고리가 Apple의 공식 필수 이유 API(Required Reason API) 사양과 일치하는지 확인합니다. Xcode에서 PrivacyInfo.xcprivacy를 속성 목록(Property List) 또는 원본 XML로 엽니다. 선언은 필요한 API 사용량에 엄격히 대응해야 합니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>CA92.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>

SDK의 실제 구현 요구사항에 해당하는 API 카테고리와 승인된 이유 코드만 포함하세요.

최종 App Store Connect IPA 제출물 검증

App Store Connect에 애플리케이션 업데이트를 제출하기 전에 로컬에서 컴파일된 IPA 아카이브를 검증합니다.

• 1단계: Xcode에서 Product > Archive를 선택합니다.
• 2단계: 아카이브가 완료되면 Organizer 창에서 Validate App을 클릭합니다.
• 3단계: Xcode가 임베디드 프라이버시 서명, 프로비저닝 권한 및 프라이버시 매니페스트 스키마를 Apple 유효성 검사 서버와 대조하여 확인합니다.

성공적인 검증은 아카이브가 해당 제출 전 유효성 검사 단계를 통과했음을 나타내며, TestFlight 또는 프로덕션 제출 전 필수 빌드 검증 단계 역할을 합니다.

CocoaPods와 수동 iOS 프레임워크 임포트 비교 분석

유지보수, 서명 격리 및 빌드 자동화 측면의 트레이드오프

CocoaPods와 수동 프레임워크 통합 중 선택하는 것은 팀 워크플로, 빌드 서버 기능, 의존성 유지보수 오버헤드를 평가하는 것과 관련이 있습니다. CocoaPods는 버전 업데이트를 자동화하지만, Xcode 버전 업그레이드는 변경되는 Apple 서명 정책에 맞추기 위해 Podfile post_install 훅 업데이트를 요구할 수 있습니다.

아래 표는 두 임포트 전략에 대한 상세한 기술적 비교를 제공합니다.

엔터프라이즈 모바일 팀 전반의 의존성 관리 전략 평가

CocoaPods는 Podfile.lock을 통한 자동화된 의존성 해결 및 중앙 집중식 버전 고정 덕분에 Podfile 기반 의존성 관리를 이미 표준화한 팀에게 실용적인 옵션으로 남아 있습니다. 범위가 지정된 Ruby 서명 오버라이드 스크립트를 통합하면 팀 워크스테이션과 CI/CD 빌드 환경 전반에서 타깃 수준의 서명 막힘을 해결하는 데 도움이 됩니다.

iOS SDK를 효율적으로 임포트하려면 프로젝트 툴체인에 적절한 의존성 메커니즘을 선택하는 동시에 Xcode 코드 서명 엄격성을 완화해야 합니다. 범위가 지정된 post_install 훅과 함께 CocoaPods를 활용하면 영향을 받는 리소스 번들 서명 실패를 해결할 수 있으며, 수동 XCFramework 임베딩은 빌드 아티팩트에 대한 직접적인 제어 기능을 제공합니다.

Apple이 App Store Connect 검증 규칙을 계속 다듬어감에 따라, 클라이언트 의존성을 프라이버시 매니페스트 표준에 맞게 준수 상태로 유지하는 것이 중요합니다. 업데이트된 SDK 버전을 배포하고 자동화된 Podfile 훅을 유지 관리함으로써 엔터프라이즈 팀은 반복되는 빌드 막힘을 줄이고 통합 일관성을 향상할 수 있습니다.

프로젝트 키를 초기화할 준비가 된 개발자는 OpoInstall 개발자 콘솔에 등록하거나 추가 플랫폼 지침에 대해 모바일 어트리뷰션 구현 레퍼런스를 검토할 수 있습니다.

관련 자료

• 개념: iOS SDK, 코드 서명 ID, 리소스 번들 서명, 프라이버시 매니페스트 집계

• 기술: CocoaPods, Xcode 빌드 툴체인, XCFramework, Swift Package Manager

• 표준: Apple App Store Connect 제출 지침, Apple 프라이버시 매니페스트 요구사항

• API: OpoInstall iOS SDK 델리게이트 API, Apple UIPasteboard API, 유니버설 링크 연관 도메인 API

• 공식 문서 및 레퍼런스:

  • 프라이버시 매니페스트 파일에 대한 Apple 개발자 가이드

  • 서드파티 SDK 요구사항에 대한 Apple 문서

  • 필수 이유 API에 대한 Apple 개발자 기술 노트

  • 정적 프레임워크 생성에 대한 Apple Xcode 가이드

  • Podfile 훅을 위한 CocoaPods 구문 레퍼런스