메인 콘텐츠로 건너뛰기

개요

iOS 푸시 알림은 iOS 앱에서 지속적인 사용자 참여와 유지율을 높이는 데 필수적입니다. 실시간 업데이트, 리마인더 및 개인화된 메시지를 사용자에게 직접 전달하여 앱의 전반적인 사용자 경험과 고착도를 향상시킬 수 있습니다. OneSignal의 SDK를 앱과 통합하면 Apple Push Notification Service(APNS)를 활용하여 iOS 기기 전반에 걸쳐 알림이 원활하게 전달되도록 할 수 있습니다. 이 가이드는 iOS 앱에 SDK를 통합하는 과정을 안내합니다.

요구 사항

  • Xcode 14+가 설치된 macOS(설정 지침은 Xcode 16.2 사용)
  • iOS 12+, iPadOS 12+ 또는 iOS 16.2+를 실행하는 Xcode 시뮬레이터가 있는 기기
  • 구성된 OneSignal 앱 및 플랫폼

配置您的 OneSignal 应用和平台

推送通知所需设置 要开始使用 OneSignal 发送推送通知,您必须首先为您支持的所有平台配置 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。
如果您的组织已有 OneSignal 账户,请要求邀请您为管理员角色以配置应用。否则,请注册免费账户以开始使用。
您可以在单个 OneSignal 应用下管理多个平台(iOS、Android、华为、Amazon、Web)。
1

创建或选择您的应用

  • 要向现有应用添加平台,请在 OneSignal 控制台中转到 设置 > 推送和应用内
  • 要重新开始,请点击 新应用/网站 并按照提示操作。
2

设置并激活平台

  • 为您的应用和组织选择一个清晰且易识别的名称。
  • 选择您要配置的平台(iOS、Android 等)。
  • 点击 下一步:配置您的平台
3

配置平台凭据

根据您的平台按照提示操作:输入您的凭据后点击 保存并继续
4

选择目标 SDK

选择与您的开发平台匹配的 SDK(例如,iOS、Android、React Native、Unity),然后点击 保存并继续
5

安装 SDK 并保存您的应用 ID

配置好您的平台后,将显示您的 OneSignal 应用 ID。复制并保存此 ID——在安装和初始化 SDK 时您将需要它。如果与他人协作,请使用 邀请 按钮添加开发人员或团队成员,然后点击 完成 以完成设置。
完成后,请遵循您所选平台的 SDK 安装指南以完成 OneSignal 集成。

iOS 설정

배지, 확인된 전달 및 이미지 지원을 포함하여 iOS 앱에 푸시 알림을 추가하려면 다음 단계를 따르세요.

1. 앱 타겟에 Push Notifications 기능 추가

Push Notifications 기능을 사용하면 앱이 푸시 토큰을 등록하고 알림을 받을 수 있습니다.
  1. Xcode에서 앱의 .xcworkspace 파일을 여세요.
  2. 앱 타겟 > Signing & Capabilities를 선택하세요
  3. + Capability를 클릭하고 Push Notifications 기능을 추가하세요

2. 앱 타겟에 Background Modes 기능 추가

이를 통해 푸시 알림이 도착할 때 앱이 백그라운드에서 깨어날 수 있습니다.
  1. Background Modes 기능을 추가하세요
  2. Remote notifications를 활성화하세요

3. App Group에 앱 타겟 추가

App Groups를 사용하면 앱과 Notification Service Extension 간에 데이터를 공유할 수 있습니다. 확인된 전달 및 배지에 필요합니다.
  1. App Groups 기능을 추가하세요
  2. App Groups 기능에서 **+**를 클릭하세요
  3. 다음 형식으로 새 컨테이너 ID를 추가하세요: group.your_bundle_id.onesignal
  • group..onesignal 접두사와 접미사를 유지하세요. **your_bundle_id**를 앱의 번들 식별자로 바꾸세요.
  • 예를 들어, 번들 식별자 com.onesignal.MyApp는 컨테이너 이름 group.com.onesignal.MyApp.onesignal을 갖습니다.
App Group 이름은 모든 타겟에서 번들 ID의 철자 및 대소문자와 정확히 일치해야 합니다.

4. Notification Service Extension 추가

Notification Service Extension (NSE)은 리치 알림 및 확인된 전달 분석을 활성화합니다.
  1. Xcode에서: File > New > Target…
  2. Notification Service Extension을 선택한 다음 Next를 클릭하세요.
  3. 제품 이름을 OneSignalNotificationServiceExtension으로 설정하고 Finish를 누르세요.
  4. Activate scheme 프롬프트에서 Don’t Activate를 누르세요.
OneSignalNotificationServiceExtension Minimum Deployment Target을 메인 앱과 일치하도록 설정하세요(iOS 15+ 권장).
CocoaPods를 사용하는 경우 Podfile에서도 배포 버전을 설정하세요.

5. NSE 타겟을 앱 그룹에 추가

3단계에서 추가한 것과 동일한 App Group ID를 사용하세요.
  1. OneSignalNotificationServiceExtension > Signing & Capabilities로 이동하세요
  2. App Groups를 추가하세요
  3. 정확히 동일한 그룹 ID를 추가하세요
사용자 정의 App Group 이름을 사용하고 group.your_bundle_id.onesignal이 아닌 경우 App Target 및 OneSignalNotificationServiceExtension Target의 Info.plist 둘 다에 App Group ID를 추가해야 합니다! 자세한 내용은 3단계를 참조하세요.

6. NSE 코드 업데이트

  1. OneSignalNotificationServiceExtension 폴더로 이동하세요
  2. NotificationService.swift 또는 NotificationService.m 파일의 내용을 다음으로 바꾸세요:
import UserNotifications
import OneSignalExtension

class NotificationService: UNNotificationServiceExtension {
    var contentHandler: ((UNNotificationContent) -> Void)?
    var receivedRequest: UNNotificationRequest!
    var bestAttemptContent: UNMutableNotificationContent?

    // Note this extension only runs when `mutable_content` is set
    // Setting an attachment or action buttons automatically sets the property to true
    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.receivedRequest = request
        self.contentHandler = contentHandler
        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent {
            // DEBUGGING: Uncomment the 2 lines below to check this extension is executing
//            print("Running NotificationServiceExtension")
//            bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

            OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
        }
    }
}
OneSignal 패키지가 설치되지 않아 오류가 표시됩니다. 이는 다음 단계에서 해결됩니다.

SDK 설정

이 섹션에서는 OneSignal의 핵심 기능을 통합하는 과정을 안내합니다. 이 섹션이 끝나면 인앱 메시지를 트리거하고 푸시 알림을 받을 수 있는 SDK와의 기본 통합이 완료됩니다.

1. SDK 추가

Xcode Package Dependencies Manager (Swift Package Manager) 또는 CocoaPods를 사용하여 SDK를 추가하세요. 4개의 사용 가능한 라이브러리가 있습니다. 인앱 메시지 및/또는 위치 추적을 원하지 않는 경우 이러한 패키지를 생략할 수 있습니다.
라이브러리타겟필수 여부
OneSignalExtensionOneSignalNotificationServiceExtension
OneSignalFrameworkApp
OneSignalInAppMessagesApp권장
OneSignalLocationApp선택 사항
**File > Add Package Dependencies…**로 이동하여 OneSignal SDK 저장소의 URL을 입력하세요:https://github.com/OneSignal/OneSignal-XCFrameworkonesignal-xcframework 패키지를 선택하고 Add Package를 클릭하세요.OneSignal-XCFramework에 대한 패키지 제품을 선택하세요.
  • 중요: OneSignalNotificationServiceExtension Target에 OneSignalExtension을 추가하세요.
  • 앱 타겟에 OneSignalFramework를 추가하세요.
  • 인앱 메시지(권장) 및/또는 위치 추적을 사용할 계획이라면 해당 패키지도 앱 타겟에 추가하세요.
자세한 내용은 Apple의 패키지 종속성 추가 문서를 참조하세요.

2. SDK 초기화

Xcode 인터페이스 설정에 따라 다음 옵션을 따라 OneSignal을 초기화하세요.
SwiftUI 인터페이스를 사용하는 경우 <APP_NAME>App.swift 파일로 이동하여 제공된 메서드로 OneSignal을 초기화하세요.OneSignal 대시보드 **Settings > Keys & IDs**에서 찾은 OneSignal 앱 ID로 YOUR_APP_ID를 바꾸세요. OneSignal 앱에 액세스할 수 없는 경우 팀 멤버에게 초대를 요청하세요.
import SwiftUI
import OneSignalFramework

@main
struct YOURAPP_NAME: App {
  //Connect the SwiftUI app to the UIKit app delegate
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {

       // Enable verbose logging for debugging (remove in production)
       OneSignal.Debug.setLogLevel(.LL_VERBOSE)
       // Initialize with your OneSignal App ID
       OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)
       // Use this method to prompt for push notifications.
       // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
       OneSignal.Notifications.requestPermission({ accepted in
         print("User accepted notifications: \(accepted)")
       }, fallbackToSettings: false)

       return true
    }
}

OneSignal SDK 통합 테스트

이 가이드는 푸시 알림, 구독 등록 및 인앱 메시징을 테스트하여 OneSignal SDK 통합이 올바르게 작동하는지 확인하는 데 도움이 됩니다.

모바일 구독 확인

1

테스트 기기에서 앱을 실행하세요.

초기화 중에 requestPermission 메서드를 추가한 경우 기본 푸시 권한 프롬프트가 자동으로 나타나야 합니다.
2

OneSignal 대시보드 확인

프롬프트를 수락하기 전에 OneSignal 대시보드를 확인하세요:
  • Audience > Subscriptions로 이동하세요.
  • “Never Subscribed” 상태의 새 항목이 표시되어야 합니다.
3

앱으로 돌아가서 프롬프트에서 허용을 탭하세요.

4

OneSignal 대시보드 Subscription 페이지를 새로고침하세요.

구독 상태가 이제 Subscribed로 표시되어야 합니다.
모바일 구독을 성공적으로 생성했습니다. 모바일 구독은 사용자가 기기에서 앱을 처음 열거나 동일한 기기에 앱을 제거했다가 다시 설치할 때 생성됩니다.

테스트 구독 설정

테스트 구독은 메시지를 보내기 전에 푸시 알림을 테스트하는 데 유용합니다.
1

테스트 구독에 추가.

대시보드에서 구독 옆에 있는 Options (세 개의 점) 버튼을 클릭하고 Add to Test Subscriptions를 선택하세요.
2

구독 이름 지정.

나중에 Test Subscriptions 탭에서 기기를 쉽게 식별할 수 있도록 구독 이름을 지정하세요.
3

테스트 사용자 세그먼트 생성.

Audience > Segments > New Segment로 이동하세요.
4

세그먼트 이름 지정.

세그먼트 이름을 Test Users로 지정하세요(나중에 사용되므로 이름이 중요함).
5

Test Users 필터를 추가하고 Create Segment를 클릭하세요.

테스트 사용자 세그먼트를 성공적으로 생성했습니다. 이제 이 개별 기기 및 테스트 사용자 그룹에 메시지 전송을 테스트할 수 있습니다.

API를 통해 테스트 푸시 전송

1

App API Key 및 App ID를 가져오세요.

OneSignal 대시보드에서 **Settings > Keys & IDs**로 이동하세요.
2

제공된 코드를 업데이트하세요.

아래 코드에서 YOUR_APP_API_KEYYOUR_APP_ID를 실제 키로 바꾸세요. 이 코드는 이전에 생성한 Test Users 세그먼트를 사용합니다.
curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "ios_attachments": {
    "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  },
  "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
3

Run the code.

터미널에서 코드를 실행하세요.
4

이미지 및 확인된 전달 확인.

모든 설정 단계가 성공적으로 완료되면 테스트 구독이 이미지가 포함된 알림을 받아야 합니다:
축소된 알림 보기에서는 이미지가 작게 표시됩니다. 알림을 확장하여 전체 이미지를 확인하세요.
5

확인된 전달 확인.

대시보드에서 Delivery > Sent Messages로 이동한 다음 메시지를 클릭하여 통계를 확인하세요.confirmed 통계가 표시되어야 하며, 이는 기기가 푸시를 받았음을 의미합니다.
Professional 플랜 이상을 사용하는 경우 Audience Activity로 스크롤하여 구독 수준 확인을 확인하세요:
API를 통해 세그먼트에 알림을 성공적으로 전송했습니다.
  • 이미지를 받지 못했나요? Notification Service Extension이 누락되었을 수 있습니다.
  • 확인된 전달이 없나요? 여기에서 문제 해결 가이드를 검토하세요.
  • 문제가 있나요? api 요청과 앱 실행 시작부터 끝까지의 로그를 .txt 파일에 복사하여 붙여넣으세요. 그런 다음 둘 다 support@onesignal.com에 공유하세요.

인앱 메시지 전송

인앱 메시지를 사용하면 사용자가 앱을 사용하는 동안 사용자와 소통할 수 있습니다.
1

기기에서 앱을 닫거나 백그라운드로 전환하세요.

사용자가 새 세션이 시작되기 전에 인앱 대상 조건을 충족해야 하기 때문입니다. OneSignal에서 새 세션은 사용자가 백그라운드에 있거나 최소 30초 동안 닫혀 있던 후 앱을 열 때 시작됩니다. 자세한 내용은 인앱 메시지 표시 방법 가이드를 참조하세요.
2

인앱 메시지 생성.

  • OneSignal 대시보드에서 Messages > In-App > New In-App으로 이동하세요.
  • Welcome 메시지를 찾아 선택하세요.
  • 대상을 이전에 사용한 Test Users 세그먼트로 설정하세요.
3

원하는 경우 메시지 콘텐츠를 사용자 정의하세요.

4

트리거를 'On app open'으로 설정.

5

빈도 예약.

Schedule > How often do you want to show this message? 아래에서 Every time trigger conditions are satisfied를 선택하세요.
6

메시지를 라이브로 만들기.

Make Message Live를 클릭하여 사용자가 앱을 열 때마다 테스트 사용자가 사용할 수 있도록 하세요.
7

앱을 열고 메시지를 확인하세요.

인앱 메시지가 라이브 상태가 되면 앱을 여세요. 다음과 같이 표시되어야 합니다:
메시지가 표시되지 않나요?
  • 새 세션 시작
    • 다시 열기 전에 최소 30초 동안 앱을 닫거나 백그라운드로 전환해야 합니다. 이렇게 하면 새 세션이 시작됩니다.
    • 자세한 내용은 인앱 메시지 표시 방법을 참조하세요.
  • 여전히 Test Users 세그먼트에 있나요?
    • 다시 설치하거나 기기를 전환한 경우 기기를 Test Subscriptions에 다시 추가하고 Test Users 세그먼트의 일부인지 확인하세요.
  • 문제가 있나요?
    • 위 단계를 재현하는 동안 디버그 로그 가져오기를 따르세요. 이렇게 하면 추가 로깅이 생성되며 support@onesignal.com과 공유하면 무슨 일이 일어나고 있는지 조사하는 데 도움을 드립니다.
OneSignal SDK를 성공적으로 설정하고 다음과 같은 중요한 개념을 배웠습니다:이 가이드를 계속 진행하여 앱에서 사용자를 식별하고 추가 기능을 설정하세요.

사용자 식별

이전에는 모바일 구독을 생성하는 방법을 시연했습니다. 이제 OneSignal SDK를 사용하여 모든 구독(푸시, 이메일 및 SMS 포함)에서 사용자를 식별하는 것으로 확장하겠습니다. 플랫폼 전반에 걸쳐 사용자를 통합하고 참여시키는 데 도움이 되는 External ID, 태그, 다중 채널 구독, 개인 정보 보호 및 이벤트 추적을 다룹니다.

External ID 할당

External ID를 사용하여 백엔드의 사용자 식별자를 사용하여 기기, 이메일 주소 및 전화번호 전반에 걸쳐 사용자를 일관되게 식별하세요. 이렇게 하면 채널 및 타사 시스템 전반에 걸쳐 메시징이 통합된 상태로 유지됩니다(통합에 특히 중요). 앱에서 식별될 때마다 SDK의 login 메서드로 External ID를 설정하세요.
OneSignal은 구독(Subscription ID) 및 사용자(OneSignal ID)에 대한 고유한 읽기 전용 ID를 생성합니다.사용자가 다른 기기에 앱을 다운로드하거나, 웹사이트를 구독하거나, 앱 외부에서 이메일 주소 및 전화번호를 제공하면 새 구독이 생성됩니다.SDK를 통해 External ID를 설정하는 것은 생성 방법에 관계없이 모든 구독에서 사용자를 식별하는 데 매우 권장됩니다.

데이터 태그 추가

태그는 사용자 속성(username, role 또는 기본 설정 등) 및 이벤트(purchase_date, game_level 또는 사용자 상호 작용 등)를 저장하는 데 사용할 수 있는 문자열 데이터의 키-값 쌍입니다. 태그는 고급 메시지 개인화세그먼테이션을 지원하여 보다 고급 사용 사례를 가능하게 합니다. 앱에서 이벤트가 발생할 때 SDK addTagaddTags 메서드로 태그를 설정하세요. 이 예시에서 사용자는 current_level이라는 태그가 6의 값으로 설정되어 식별 가능한 레벨 6에 도달했습니다.
레벨이 5에서 10 사이인 사용자 세그먼트를 생성하고 이를 사용하여 타겟팅되고 개인화된 메시지를 보낼 수 있습니다:


이메일 및/또는 SMS 구독 추가

이전에 SDK가 푸시 및 인앱 메시지를 보내기 위해 모바일 구독을 생성하는 방법을 살펴보았습니다. 해당 구독을 생성하여 이메일 및 SMS 채널을 통해 사용자에게 도달할 수도 있습니다. 이메일 주소 및/또는 전화번호가 OneSignal 앱에 이미 존재하는 경우 SDK는 이를 기존 사용자에게 추가하며 중복을 생성하지 않습니다. 대시보드에서 Audience > Users를 통해 또는 View user API를 사용하여 통합된 사용자를 볼 수 있습니다.
다중 채널 커뮤니케이션 모범 사례
  • 이메일 또는 SMS 구독을 추가하기 전에 명시적인 동의를 얻으세요.
  • 각 커뮤니케이션 채널의 이점을 사용자에게 설명하세요.
  • 사용자가 선호하는 채널을 선택할 수 있도록 채널 기본 설정을 제공하세요.

개인정보 보호 및 사용자 동의

OneSignal이 사용자 데이터를 수집하는 시기를 제어하려면 SDK의 동의 게이팅 메서드를 사용하세요: 자세한 내용은 개인정보 보호 및 보안 문서를 참조하세요:

푸시 권한 프롬프트

앱을 열 때 즉시 requestPermission()을 호출하는 대신 보다 전략적인 접근 방식을 취하세요. 인앱 메시지를 사용하여 권한을 요청하기 전에 푸시 알림의 가치를 설명하세요. 모범 사례 및 구현 세부 정보는 푸시 권한 프롬프트 가이드를 참조하세요.

푸시, 사용자 및 인앱 이벤트 수신

SDK 리스너를 사용하여 사용자 작업 및 상태 변경에 반응하세요. SDK는 연결할 수 있는 여러 이벤트 리스너를 제공합니다. 자세한 내용은 SDK 참조 가이드를 참조하세요.

푸시 알림 이벤트

전체 사용자 정의는 Mobile Service Extensions를 참조하세요.

사용자 상태 변경

인앱 메시지 이벤트

  • addClickListener(): 인앱 클릭 작업을 처리합니다. 딥 링킹 또는 이벤트 추적에 이상적입니다.
  • addLifecycleListener(): 인앱 메시지의 전체 수명 주기(표시, 클릭, 닫힘 등)를 추적합니다.

고급 설정 및 기능

통합을 향상시키기 위한 더 많은 기능을 살펴보세요:

Mobile SDK 설정 및 참조

Mobile push 설정 가이드를 검토하여 모든 주요 기능을 활성화했는지 확인하세요. 사용 가능한 메서드 및 구성 옵션에 대한 전체 세부 정보는 Mobile SDK 참조를 참조하세요.
축하합니다! Mobile SDK 설정 가이드를 성공적으로 완료했습니다.

需要帮助?与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息:
  • 您遇到的问题详情以及复现步骤(如有)
  • 您的 OneSignal 应用 ID
  • 外部 ID 或订阅 ID(如适用)
  • 您在 OneSignal 控制台中测试的消息 URL(如适用)
  • 任何相关的日志或错误信息
我们很乐意为您提供帮助!