Apple 푸시 알림 서비스(APN) 설정 가이드
Apple 푸시 알림 서비스 인증서 및 프로비저닝 프로필을 구성하여 Singular SDK를 사용하는 iOS 앱의 푸시 알림 전달 및 제거 추적을 사용하도록 설정합니다.
개요
전제 조건
Apple 개발자 회원 센터에서 SSL 인증서 및 프로비저닝 프로필을 생성하여 APN 푸시 알림을 사용하도록 설정합니다.
필수 구성 요소:
- SSL 인증서: 푸시 알림에 대해 구성된 앱 ID와 연결됨
- 프로비저닝 프로필: 개발 및 테스트 중에 앱을 실행할 수 있도록 디바이스에 권한 부여
- Apple 개발자 계정: 인증서 생성에 필요한 활성 멤버십
- Mac 컴퓨터: 키체인 액세스 및 인증서 생성에 필요
Apple 개발자 포털: 모든 인증서 및 프로필 관리는 Apple 개발자 회원 센터에서 이루어집니다. 조직의 개발자 팀에 적절한 권한이 있는지 확인하세요.
인증서 유형
Apple은 서로 다른 환경을 위한 두 가지 유형의 APN SSL 인증서를 제공합니다.
| 인증서 유형 | 환경 | 사용 사례 |
|---|---|---|
| 개발 SSL 인증서 | 샌드박스 | 내부 테스트 및 개발 빌드 |
| 프로덕션 SSL 인증서 | 프로덕션 | 앱 스토어 릴리스 및 TestFlight 빌드 |
환경 일치 중요: 앱은 빌드 환경과 일치하는 인증서를 사용해야 합니다. 개발 인증서가 있는 프로덕션 앱은 푸시 알림을 수신하지 못합니다.
1단계: 인증서 서명 요청 생성
Mac에서 CSR(인증서 서명 요청) 파일을 만들어 SSL 인증서 생성을 인증합니다.
CSR 파일 만들기
키체인 액세스 사용
macOS에서 키체인 액세스 애플리케이션을 통해 CSR을 생성합니다.
- 키체인 액세스를 엽니다: 애플리케이션 → 유틸리티 → 키체인 액세스로 이동하거나 스포트라이트 검색(Cmd+스페이스)을 사용합니다.
- 인증서 도우미에 액세스: 메뉴 모음에서 키체인 액세스 → 인증서 도우미 → 인증 기관에서 인증서 요청...을 선택합니다.
-
사용자 정보를 입력합니다:
- 사용자 이메일 주소: 이메일 주소를 입력합니다(Apple 개발자 계정에서 사용).
- 일반 이름: 설명적인 이름을 입력합니다(예: "YourCompany APNs 인증서").
- CA 이메일 주소: 비워둡니다.
- 요청 유형을 선택합니다: "디스크에 저장" 옵션을 선택합니다(수동 인증서 만들기에 필요).
- CSR 파일 저장: 계속을 클릭하고 .certSigningRequest 파일을 Mac의 기억하기 쉬운 위치에 저장합니다.
개인 키 저장소: 키체인 액세스는 CSR을 만들 때 개인 키를 자동으로 생성하여 저장합니다. 이 개인 키는 나중에 Apple에서 다운로드할 SSL 인증서와 쌍을 이룹니다.
2단계: 앱 ID 생성 또는 구성
새 앱 ID를 만들거나 기존 앱 ID를 구성하여 푸시 알림 기능을 사용하도록 설정합니다.
앱 ID 이해
앱 ID 구조
앱 ID는 iOS 애플리케이션을 고유하게 식별하며, 푸시 알림을 지원하려면 와일드카드가 아닌 명시적 식별자이어야 합니다.
형식: 역방향 도메인 표기법(예: com.yourcompany.appname)
명시적 앱 ID 필수: 와일드카드 앱 ID(* 포함)는 푸시 알림을 사용할 수 없습니다. 기존 와일드카드 앱 ID가 있는 경우 푸시 사용 앱에 대한 명시적 앱 ID를 새로 생성하세요.
새 앱 ID 만들기
앱 ID 구성 단계
푸시 알림이 활성화된 상태에서 Apple 개발자 포털에서 새 앱 ID를 생성합니다.
- 개발자 포털에 액세스합니다: Apple 개발자 회원 센터로이동하여 로그인합니다.
- 인증서 및 식별자를 엽니다: "인증서, 식별자 및 프로필"을 선택합니다.
- 식별자로 이동합니다: 왼쪽 사이드바에서 "식별자"를 선택합니다.
- 플랫폼을 선택합니다: 왼쪽 상단 드롭다운에서 "iOS 앱"(또는 최신 인터페이스에서는 "iOS, tvOS, watchOS")을 선택합니다.
- 식별자 만들기: "+" 버튼을 클릭하여 새 앱 ID를 생성합니다.
앱 ID 세부 정보 구성
앱 ID 정보를 입력하고 푸시 알림 기능을 활성화합니다.
- 유형을 선택합니다: 앱 클립이 아닌 "앱 ID"를 선택합니다.
- 번들 유형을 선택합니다: 유형으로 "앱"을 선택합니다.
- 설명을 입력합니다: 의미 있는 이름을 입력합니다(예: "YourApp Production").
- 번들 ID 설정: 앱 ID 접두사 섹션에서 기본 팀 ID를 사용합니다.
-
명시적 번들 ID 입력: 번들 ID 필드에 앱의 식별자를 Xcode에 표시되는 그대로 입력합니다(예:
com.yourcompany.appname).
번들 ID 일치: 번들 ID 값은 앱의 Info.plist 파일 및 Xcode 프로젝트 설정에 있는 식별자와 정확히 일치해야 합니다. 대소문자 구분이 중요합니다.
푸시 알림 활성화
앱 서비스 섹션에서 푸시 알림 기능을 활성화합니다.
- 기능으로 스크롤합니다: "앱 서비스" 섹션을 찾습니다.
- 푸시 알림을 활성화합니다: "푸시 알림" 확인란을 선택합니다.
- 구성을 검토합니다: 계속을 클릭하고 설정을 확인합니다.
- 앱 ID를 확인합니다: 식별자에 번들 ID가 올바르게 표시되는지 확인합니다.
- 상태를 확인합니다: 푸시 알림이 "구성 가능"으로 표시되는지 확인합니다.
- 앱 ID를 등록합니다: 제출을 클릭하여 앱 ID를 생성합니다.
3단계: 푸시 알림 인증서 구성
푸시 알림용 SSL 인증서를 생성하여 앱과 APN이 통신할 수 있도록 합니다.
앱 ID 설정에 액세스
앱 ID 구성 편집
앱 ID 설정을 열어 개발 및 프로덕션 환경용 SSL 인증서를 생성합니다.
- 식별자로 이동합니다: Apple 개발자 포털에서 인증서, 식별자 및 프로필 → 식별자로 이동합니다.
- 앱 ID를 선택합니다: 생성했거나 구성하려는 앱 ID를 클릭합니다.
- 구성 편집: "편집" 버튼을 클릭합니다(또는 앱 ID가 편집 모드에서 바로 열립니다).
- 푸시 알림을 찾습니다: 기능 목록에서 "푸시 알림" 섹션으로 스크롤합니다.
개발 SSL 인증서 만들기
개발 인증서 생성
개발 중 푸시 알림을 테스트하기 위해 개발 인증서를 생성합니다.
- 인증서 생성을 시작합니다: 푸시 알림 섹션에서 개발 SSL 인증서 아래의 "인증서 만들기..."를 클릭합니다.
- 지침을 검토합니다: "CSR(인증서 서명 요청) 만들기 정보"를 읽습니다.
- 계속을 클릭합니다: 계속: 계속 버튼을 클릭합니다.
- CSR을 업로드합니다: "파일 선택..."을 클릭하고 1단계에서 만든 .certSigningRequest 파일을 선택합니다.
- 생성하기: 계속(또는 생성)을 클릭하여 인증서를 만듭니다.
인증서 다운로드 및 설치
SSL 인증서를 다운로드하여 푸시 알림에 사용할 수 있도록 Mac 키체인에 설치합니다.
- 인증서 다운로드: "다운로드" 버튼을 클릭하여 .cer 파일을 Mac에 저장합니다.
- 프로세스 완료: "완료"를 클릭하여 인증서 생성 과정을 닫습니다.
- 인증서 설치하기: 다운로드한 .cer 파일을 찾아서 더블 클릭하여 키체인에 추가합니다.
- 설치 확인: 키체인 액세스를 열고 "내 인증서" 카테고리로 이동합니다.
- 인증서 찾기: 연결된 개인 키가 있는 "Apple 개발 iOS 푸시 서비스: your.bundle.id" 인증서를 찾습니다.
인증서 페어링: 다운로드한 인증서는 CSR 생성 시 생성된 개인 키와 자동으로 페어링됩니다. 푸시 알림이 작동하려면 둘 다 키체인에 있어야 합니다.
인증서를 .p12로 내보내기
P12 파일 생성
인증서와 개인 키를 .p12 파일로 내보내어 푸시 알림 서비스(예: Singular)에 업로드합니다.
- 키체인 액세스를 엽니다: "내 인증서" 카테고리로 이동합니다.
- 인증서를 펼칩니다: "Apple 개발 iOS 푸시 서비스" 인증서 옆의 공개 삼각형을 클릭하여 개인 키를 공개합니다.
- 두 항목을 모두 선택합니다: Command 키를 누른 상태에서 클릭하여 인증서와 개인 키를 모두 선택합니다.
- 내보내기: 선택 항목을 마우스 오른쪽 버튼으로 클릭하고 "2개 항목 내보내기..."를 선택합니다.
- 파일 이름: 설명이 포함된 이름으로 저장합니다(예: "YourApp_Development_APNs.p12").
- 형식을 선택합니다: 파일 형식으로 "개인정보 교환(.p12)"이 선택되었는지 확인합니다.
- 비밀번호 설정:.p12 파일을 보호하기 위해 강력한 비밀번호를 입력합니다.
- 내보내기를 확인합니다: 확인을 클릭하고 메시지가 표시되면 Mac 로그인 비밀번호를 입력합니다.
보안 중요:.p12 파일에는 개인 키와 인증서가 포함되어 있습니다. 이 파일을 안전하게 보관하고 공개 저장소에 커밋하지 마세요. 비밀번호는 복구할 수 없으므로 기억해 두세요.
프로덕션 SSL 인증서 만들기
프로덕션 인증서 생성
앱 스토어 릴리스에 필요한 프로덕션 SSL 인증서에 대한 인증서 생성 프로세스를 반복합니다.
- 앱 ID 설정으로 돌아갑니다: Apple 개발자 포털에서 앱 ID 구성으로 돌아갑니다.
- 프로덕션 인증서로 돌아갑니다: 푸시 알림 섹션에서 프로덕션 SSL 인증서 아래의 "인증서 만들기..."를 클릭합니다.
- 동일한 프로세스를 따릅니다: CSR 업로드, 인증서 생성, 다운로드 및 키체인에 설치합니다.
- 프로덕션 P12 내보내기: 설명이 포함된 이름의 .p12로 내보내기(예: "YourApp_Production_APNs.p12")
- 안전한 저장소: 프로덕션 인증서를 개발 인증서와 별도로 안전하게 저장
프로덕션 인증서 필요: 앱 스토어에 제출하고 테스트 비행을 통해 배포하는 앱은 반드시 프로덕션 SSL 인증서를 사용해야 합니다. 개발 인증서는 프로덕션 환경에서 실패합니다.
4단계: 프로비저닝 프로필 생성
프로비저닝 프로필을 생성하여 개발 및 테스트 단계에서 앱을 실행할 수 있도록 디바이스에 권한을 부여합니다.
프로비저닝 프로필 이해
프로필 유형
프로비저닝 프로필은 앱 ID, 인증서 및 등록된 기기를 연결하여 앱 설치 및 테스트를 가능하게 합니다.
| 프로필 유형 | 목적 | 기기 제한 |
|---|---|---|
| iOS 앱 개발 | 등록된 기기에서 내부 테스트 | 프로필당 최대 100대 기기 |
| Ad Hoc | 개발팀 외부의 테스터에게 배포 | 프로필당 최대 100대 기기 |
| 앱 스토어 | 앱 스토어 배포 및 테스트 비행 | 무제한(모든 기기) |
개발 프로필 생성
개발 프로필 설정
푸시 알림 테스트를 위한 iOS 앱 개발 프로비저닝 프로필을 생성합니다.
- 프로비저닝 프로필에 액세스합니다: Apple 개발자 포털에서 인증서, 식별자 및 프로필 → 프로필로 이동합니다.
- 새 프로필 만들기: "+" 버튼을 클릭하여 프로필 만들기를 시작합니다.
- 유형을 선택합니다: 유형 선택: 개발 섹션에서 "iOS 앱 개발"을 선택합니다.
- 계속을 클릭합니다: 계속: 계속 버튼을 클릭합니다.
- 앱 ID를 선택합니다: 드롭다운 메뉴에서 푸시 알림에 대해 구성된 앱 ID를 선택합니다.
- 계속을 클릭합니다: 계속: 계속 버튼을 클릭합니다.
프로필 세부 정보 구성
인증서, 장치를 선택하고 프로비저닝 프로필의 이름을 지정합니다.
- 인증서를 선택합니다: 앱 ID와 연결된 iOS 개발 인증서를 확인합니다.
- 계속을 클릭합니다: 계속: 계속 버튼을 클릭합니다.
- 기기를 선택합니다: 푸시 알림을 테스트할 모든 디바이스를 선택합니다(디바이스 섹션에서 사전 등록해야 함).
- 계속을 클릭합니다: 계속: 계속 버튼을 클릭합니다.
- 이름 프로필: 설명이 포함된 이름을 입력합니다(예: "YourApp 개발 푸시 테스트").
- 프로필 생성: 생성 버튼 클릭
기기 등록: 테스트 기기를 프로비저닝 프로필에 추가하려면 먼저 Apple 개발자 포털에 등록해야 합니다. 디바이스 섹션에서 UDID로 디바이스를 등록합니다.
프로비저닝 프로필 설치
Xcode에서 사용할 프로비저닝 프로필을 다운로드하여 설치합니다.
- 프로필 다운로드: 다운로드 버튼을 클릭하여 .mobileprovision 파일을 저장합니다.
- 프로필 설치: 다운로드한 .mobileprovision 파일을 두 번 클릭하여 Xcode에 추가합니다.
- 설치 확인: Xcode → 환경설정 → 계정 → 세부 정보 보기를 열어 프로파일이 나타나는지 확인합니다.
- 프로젝트에서 선택합니다: Xcode 프로젝트 설정의 서명 및 기능에서 프로비저닝 프로필을 선택합니다.
프로파일 만료: 프로비저닝 프로파일은 1년 후에 만료됩니다. 만료된 프로필은 Apple 개발자 포털에서 갱신하고 새 .mobileprovision 파일을 다운로드합니다.
확인 및 테스트
개발 디바이스에 대한 푸시 알림 전달을 테스트하여 APN 구성이 올바른지 확인합니다.
구성 체크리스트
테스트 전 확인
푸시 알림을 테스트하기 전에 모든 구성 요소가 올바르게 구성되었는지 확인합니다.
- 앱 ID: 푸시 알림 기능이 활성화된 명시적 앱 ID
- SSL 인증서:.p12로 생성 및 내보낸 개발 및 프로덕션 인증서
- 프로비저닝 프로필: 올바른 앱 ID 및 디바이스와 함께 Xcode에 설치된 개발 프로필
- 번들 ID 일치: Xcode 프로젝트 번들 ID가 앱 ID 식별자와 정확히 일치합니다.
- 기능: Xcode 서명 및 기능에서 푸시 알림 기능이 활성화됨
- 키체인: 개인 키가 있는 인증서가 Mac 키체인 "내 인증서"에 있습니다.
푸시 알림 테스트
테스트 절차
테스트 푸시 알림을 보내서 APN 구성을 확인합니다.
- 빌드 및 설치: 개발 프로비저닝 프로필로 앱을 빌드하고 테스트 장치에 설치합니다.
- 권한 요청: 앱을 실행하고 메시지가 표시되면 푸시 알림 권한을 부여합니다.
- 디바이스 토큰 등록: 콘솔 로그에서 앱이 APN 디바이스 토큰을 수신하는지 확인합니다.
- 테스트 알림 보내기: APNs 테스트 도구 또는 푸시 서비스를 사용하여 테스트 알림을 보냅니다.
- 배달 확인: 디바이스에 알림이 표시되는지 확인
일반적인 문제
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 디바이스 토큰을 받지 못함 | 기능에서 푸시 알림이 활성화되지 않음 | Xcode 서명 및 기능 탭에서 푸시 알림을 활성화합니다. |
| 인증서를 찾을 수 없음 오류 | 키체인에서 개인 키가 누락됨 | CSR을 생성한 원래 Mac에서 개인 키를 포함한 인증서 다시 내보내기 |
| 푸시 알림이 전달되지 않음 | 잘못된 환경(개발 환경과 프로덕션 환경) | 인증서 유형이 빌드 구성과 일치하는지 확인 |
| 프로비저닝 프로필이 유효하지 않음 | 프로필이 만료되었거나 장치가 등록되지 않음 | 프로비저닝 프로필을 갱신하고 디바이스가 등록되었는지 확인 |
| 번들 ID 불일치 | Xcode 번들 ID가 앱 ID와 일치하지 않음 | 앱 ID 식별자와 정확히 일치하도록 Xcode에서 번들 ID를 업데이트합니다. |
테스트 도구: Xcode에서 Apple의 푸시 알림 콘솔 또는 푸셔, Knuff 또는 curl 명령과 같은 타사 도구를 사용하여 개발 중에 테스트 알림을 보냅니다.
다음 단계
APN을 구성한 후 앱에서 푸시 알림 처리를 연동하고 제거 추적을 위해 Singular를 구성합니다.
연동 가이드
설정 완료
- iOS 푸시 구현: iOS 앱 코드에서 APN 등록 및 알림 처리 구현하기
- Singular SDK 연동: Singular iOS SDK 구현 가이드에따라 제거 추적을 사용하도록 설정합니다.
- Singular에 인증서 업로드: 제거 추적을 위해 Singular의 앱 구성에 .p12 인증서를 업로드합니다.
- 제거 추적 테스트: 프로덕션 릴리스 전에 제거 감지가 올바르게 작동하는지 확인합니다.
프로덕션 배포
앱 스토어 제출 요구 사항:
- 프로덕션 인증서: 앱 스토어 빌드에 프로덕션 SSL 인증서 사용
- 앱 스토어 프로필: App Store 배포 프로비저닝 프로필 생성 및 사용
- 코드 서명: Xcode 아카이브 설정에서 올바른 인증서 및 프로필을 선택했는지 확인합니다.
- 테스트 비행: TestFlight 빌드는 프로덕션 인증서로 프로덕션 환경 테스트 사용