iOS SDK 개발 체크리스트

iOS SDK 개발 체크리스트 (필수 주의사항)

대상: Swift/Objective‑C 혼합 환경, XCFramework 배포, Swift Package Manager(권장), CocoaPods/Carthage 호환 고려.

---

1) 공개 API 설계

• 최소 공개 면적(Minimal Surface): public/open은 꼭 필요한 것만. 나머지는 internal/private/fileprivate.
• 초기화·수명 주기: SDK.start(config:) 이후 idempotent 보장(여러 번 호출해도 안전). 종료/리셋 API 필요 시 명확히 설계.
• Thread‑safe: 모든 public API의 스레드 안전성 명시(메인 스레드 요구 vs. 내부 큐 처리).
• 동시성 모델: Swift Concurrency(async/await) 사용 시, 콜백 기반도 병행 지원하거나 어댑터 제공.
• Objective‑C 브리지: App이 Obj‑C라면 @objc/NS_SWIFT_NAME/NS_UNAVAILABLE 등으로 깔끔한 인터페이스 제공.
• 동작 보장(Contracts): 타임아웃, 재시도, 순서 보장, 최대 큐 길이 등 명확히 문서화.
• 에러 모델: Error 프로토콜 + 에러 도메인/코드 정의. 복구 가능/불가 에러 구분, 샘플 핸들링 코드 제공.
• 로그 정책: OSLog 기반 레벨(OFF/ERROR/WARN/INFO/DEBUG). 기본값은 소음 최소화. PII 불로그.
• Deprecated 정책: @available/문서/ChangeLog로 예고 후 제거.

2) 플랫폼·빌드 구성(배포 형식)

• XCFramework: iOS Device(arm64), iOS Simulator(arm64, x86_64) 모두 포함.
• 정적 vs 동적: 충돌/중복 의존성 최소화를 위해 정적 라이브러리 권장(대부분의 SDK).
• 패키징: SPM(Binary or Source) 우선 지원. 필요 시 CocoaPods/Carthage 스펙 제공.
• Swift/ABI: Swift 5+ ABI 안정성 준수. 모듈 호환되는 Swift 버전 명시.
• 리소스 번들: 이미지/Localization은 별도 .bundle로 분리. SPM의 resources: 사용 시 경로 추상화.
• dSYM 제공: 크래시 심볼화 위해 dSYM 배포 옵션 제공(개발사 내부 수집 금지). Bitcode는 iOS 16+에서 폐지됨.
• 빌드 플래그: BUILD_LIBRARY_FOR_DISTRIBUTION=YES, OTHER_SWIFT_FLAGS/GCC_SYMBOLS_PRIVATE_EXTERN 점검.
• 사이즈 관리: 심볼 스트립, dead‑code 제거, 중복 종속성 제거.

3) 종속성과 호환성

• 경량 의존성: 제3자 라이브러리 최소화(보안·크기·충돌 리스크 감소).
• 버전 상한: SPM/Pods에서 SemVer 상한 지정(.upToNextMajor)으로 호환성 유지.
• iOS 타겟: 최소 지원 버전 명시(예: iOS 13+). App Extension/Widget/Watch 지원 여부 문서화.
• Scene/Background: Scene 기반 앱/백그라운드 제약(API 사용 가능 여부) 고려.

4) 네트워크·성능·자원 관리

• URLSession: 단일 공유 세션/전용 세션 캡슐화. 타임아웃/재시도(지수 백오프)/Cancel 지원.
• 오프라인 큐잉: 디스크 큐/메모리 큐 전략, 최대 용량/보관 기간/플러시 정책 명시.
• 전송 정책: 배치/속도 제한/전력 친화(배터리, 저전력 모드) 고려. 백그라운드 업로드 시 BGTaskScheduler/backgroundSession 검토.
• ATS: App Transport Security 준수. TLS 설정/핀닝(옵션) 가이드.
• 성능 예산: 메모리/CPU/Start‑up 영향 측정. 콜드 스타트 페널티 최소화.
• 메인스레드 작업 금지: I/O, JSON 파싱, 크립토 등은 백그라운드 큐 사용.
• Deadlock/재진입: 내부 큐 설계 명확화(Serial vs Concurrent), 리엔트런시 테스트.

5) 데이터·보안·프라이버시

• 개인정보 최소 수집: 필요 데이터만. PII/민감정보 수집 금지 기본. 수집 항목/목적 투명화.
• 프라이버시 매니페스트: Xcode 15+/iOS 17+ Privacy Manifest 작성(필수 수집 항목, API 사용 이유).
• 법규 준수: GDPR/CCPA/국내법 준수. 데이터 보관 기간/삭제 API 제공.
• 식별자 처리: IDFA(ATT 동의 필요), IDFV, Vendor ID 등 사용 시 동의 흐름·대체키 설계.
• 암호화 저장: 토큰/키는 Keychain. 민감 데이터는 암호화, 전송은 HTTPS/TLS1.2+.
• 옵트아웃/동의: 추적/로그 전송 옵트아웃, 사용자 동의 변경 반영 API.
• 민감 API: 마이크/카메라/클립보드 접근 금지 또는 이유 명시. Private API 호출 금지.

6) 안정성(크래시·충돌 예방)

• 예외 안전: Objective‑C 예외(NSException)와 Swift Error 구분. 예외는 삼키지 말고 fail‑safe.
• Swizzling 최소화: 필요 시 문서화/충돌 방지 네임스페이스/토글 제공.
• KVO/Notification: 관찰자 제거 보장(Deinit/withToken 패턴). 메모리 누수 점검.
• 단일톤/전역 상태: 재초기화 가능/테스트 가능 설계. 상태 격리.
• 리소스 누수: 파일 핸들/Timer/RunLoop 소유권 종료 시 정리.
• 호환성 충돌: 다른 SDK와 카테고리/심볼 충돌 방지(접두사, 모듈 네임스페이스).

7) 문서화·개발자 경험(DX)

• 빠른 시작: 5분 내 동작하는 QuickStart. SPM 추가 → 초기화 → 첫 호출 예제.
• DocC/README: 주요 타입/메서드, 에러코드, 스레드 정책, 샘플 코드.
• 마이그레이션 가이드: 브레이킹 체인지 시 단계별 가이드 제공.
• FAQ/트러블슈팅: 흔한 빌드 오류/심볼 충돌/네트워크 차단 해결법.
• 체인지로그/버전 규칙: SemVer. Breaking은 MAJOR, 기능은 MINOR, 버그픽스 PATCH.
• 지원 창구: GitHub Issues, 이메일, 템플릿(환경/로그 첨부 방법).

8) 테스트·품질 보증

• 유닛 테스트: 비동기/에러/경계 케이스. 의존성 주입(DI)로 네트워크/스토리지 모킹.
• 통합 테스트: 샘플 앱(Obj‑C/Swift) 2종 이상. 다양한 iOS 버전/디바이스.
• 회귀 테스트: 퍼블릭 API 스냅샷 테스트/계약 테스트.
• Smoke 테스트: 배포 아티팩트(XCFramework/SPM) 설치 후 냉부팅 동작 확인.
• CI 파이프라인: xcodebuild test, 린트(SwiftLint), 라이선스 체크, 사이즈 관찰.
• 퍼포먼스 측정: Time Profiler/Memory Graph/OSSignpost로 핵심 시나리오 추적.

9) 배포·릴리스 체크리스트

• 버전 태깅: Git 태그와 아티팩트 이름 동기화.
• SPM Release: Package.swift/제품 타겟/리소스/조건부 컴파일 확인.
• 서명/Notarization: 필요 시 개발자 ID 서명. 샘플 앱 실행 확인.
• 릴리스 노트: 변경점/마이그레이션/알려진 이슈.
• 라이선스: SDK 및 서드파티 라이선스 동봉.
• 역호환 테스트: 직전 2~3개 마이너 버전과 상호 동작 확인.

10) 트래킹/분석 SDK 특이 주의(예: 이벤트 전송 SDK)

• 배치·재시도: 지수 백오프, 최대 재시도, 순서 보장 정책.
• 오프라인 저장소: 크기 상한/만료/정전 복구. 경쟁 상태 방지(락, 트랜잭션).
• 세션 정의: 포그라운드/백그라운드/Scene 전환과 세션 경계 명확화.
• 식별 키 회전: 로그인/로그아웃/사용자 전환 시 식별자 교체·머지 전략.
• 샘플링/필터: 전송량 제한/필드 마스킹/PII 차단.
• 실패 내성: 서버 장애 시 앱 기능에 영향 X(실패는 조용히 degrade).