실제 적용 흐름이 궁금하신가요?

이용 시나리오 / 게임 소식 확인하기

푸시

이해하기

푸시 알림은 게임을 켜지 않은 이용자의 단말기 화면으로 새 소식을 전하는 메시지예요. 스토브는 iOS, Android, Fire OS에서 푸시 발송 기능을 제공해요.
발송 방법은 두 가지예요. 스토브 파트너스(웹 콘솔)에서 직접 보내거나 예약하는 방법, 게임 서버에서 API로 보내는 방법이에요.
대상은 마켓·월드·국가 전체로 보내거나, 회원ID로 묶은 그룹에 골라 보낼 수 있어요.

제공 범위

푸시 서비스는 아래 3가지 메시징 서비스를 지원해요.

푸시 발송 방식

서버에서 직접 푸시를 발송하는 경우 아래 두 가지 방식을 지원해요.

푸시 설정 구조

푸시 서비스는 아래 3단계로 구성돼요.

글로벌 푸시 정책

한국 외 글로벌은 가입 시 광고성·야간 푸시 수신 동의 절차가 없어, 별도 동의 없이 푸시를 발송할 수 있어요.

연동 가이드

연동 준비

기본 연동 구조

푸시 연동은 ① 마켓 인증 키 준비 → ② 파트너스 등록 → ③ SDK 연동 순서로 진행돼요.

• 마켓별 인증 키 마켓별로 발급받아야 할 인증 항목이 달라요.

  마켓	필요 인증 항목	비고
  Android (FCM)	service account key (.json 비공개 키)	Firebase Admin SDK 기반 FCM HTTP v1 사용.
  iOS (APNS)	Private Key(.p8), Key ID, Team ID, Topic(번들 ID)	iOS 13부터 토큰 인증(TOKEN) 방식만 지원.
  Fire OS (ADM)	Amazon Device Messaging 인증 정보	Amazon Appstore로 출시하는 Fire OS 단말 대상.

• 푸시 등록 정책
  • 푸시 등록은 로그인·가입·토큰 갱신·계정 연결 완료 시 SDK 내부에서 자동으로 처리돼요. 별도 API 호출 불필요.
  • 게임에서 여러 월드를 지원한다면, 마지막 접속 월드로만 푸시가 전송돼요.

• 글로벌 이용자 푸시 수신 기본값 글로벌 신규 이용자는 동의 절차 없이 가입되어, 주간·야간 푸시 수신 기본값이 모두 ON이에요.

개발하기

SDK 연동

플랫폼별 초기 설정

푸시 기능을 사용하려면 각 플랫폼별로 빌드·코드 설정을 먼저 마쳐야 해요.

• Android 설정 Android(Google FCM) 푸시를 사용하기 위한 순차 설정 단계예요.
  • 1. google-services.json
    • 1. Firebase Console에서 프로젝트를 선택해요.
    • 2. 앱 설정에서 google-services.json을 다운로드해요.
    • 3. 앱 상단 디렉토리에 복사해요.
  
  
  
  
  • 2. build.gradle
    groovy

    repositories {
        google()
        jcenter()
        maven {
            // SDK 2.6.1부터 저장소 위치가 변경됐어요.
            url "https://externalnexus.iam0.com/repository/mvp"
            // Android Gradle Plugin 7.0 이상 사용 시 아래 옵션 추가
            allowInsecureProtocol = true
        }
        mavenCentral()
    }
    
    dependencies {
        implementation 'com.stove:push-firebase:2.5.1'
    }
    
    apply plugin: 'com.google.gms.google-services'
    

    Push 2.4.0부터는 구글 푸시(FCM)를 사용하려면 push 대신 push-firebase를 적용해야 해요.

  
  
  
  
  • 3. AndroidManifest.xml (채널·아이콘 설정) 아래 4개 값은 선택 사항이지만, Small Icon과 Large Icon은 설정을 권장해요.
  • Channel Name: 설정하지 않으면 'Stove'로 설정돼요.
  • Channel Description: 설정하지 않으면 null로 설정돼요.
  • Small Icon: 설정하지 않으면 application.icon으로 설정돼요.
  • Large Icon: 설정하지 않으면 null로 설정돼요.
    xml

    <?xml version="1.0" encoding="utf-8"?>
    <manifest>
        <application>
            <meta-data
                android:name="com.stove.push.small_icon"
                android:resource="@drawable/{setYourSmallIcon}" />
            <meta-data
                android:name="com.stove.push.large_icon"
                android:resource="@drawable/{setYourLargeIcon}" />
            <meta-data
                android:name="com.stove.push.channel_name"
                android:value="@string/{setYourChannelName}" />
            <meta-data
                android:name="com.stove.push.channel_description"
                android:value="@string/{setYourChannelDescription}" />
        </application>
    </manifest>
    

    
    
    
    
  • 4. 앱 실행 중에 푸시 보이게 하기
    foreground_notification_enabled를 설정하지 않으면 게임 실행 중에는 푸시 메시지가 보이지 않아요.
    xml

    <manifest>
        <application>
            <meta-data
                android:name="com.stove.push.foreground_notification_enabled"
                android:value="true" />
        </application>
    </manifest>
    

  
  
  
  
  • 5. 푸시 권한 요청 수동 제어 (Firebase 2.5.2 / Amazon 2.5.1 / Huawei 2.5.1 이상) 아래 설정을 추가하면 SDK의 자동 권한 요청을 생략하고, 앱에서 원하는 시점에 별도 처리할 수 있어요.
    xml

    <manifest>
        <application>
            <meta-data
                android:name="com.stove.push.request_permission_disabled"
                android:value="true" />
        </application>
    </manifest>
    

  
  
  
  
• Android — 앱 실행 중 푸시 메시지 수신하기 앱 실행 중에 푸시 메시지를 수신하면 앱에 맞는 UI를 보여줄 수 있어요. 수신 데이터는 다음 키로 전달돼요.
  • T: Title
  • M: Message
  • I: ImageUrl
  • L: LinkUrl
  • E: Extra

private void SetMessageDelegate()
{
    Push.SetMessageDelegate((Dictionary<string, string> dictionary) =>
    {

    });
}

• Android — 푸시 메시지 클릭 처리Push 2.3.1부터는 앱에서 수신한 푸시 메시지의 클릭 처리를 위해 Activity의 onCreate와 onNewIntent에서 Push.handleIntent를 호출해야 해요.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ...
    Push.handleIntent(applicationContext, intent)
    // ...
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    // ...
    Push.handleIntent(applicationContext, intent)
    // ...
}

• iOS 설정
  • 1. Xcode Capabilities 추가하기
    • 1. Build Settings → Capabilities 화면에서 추가 버튼 클릭
    • 2. Push Notifications 검색 후 추가
    • 3. Push Notifications가 활성 상태인지 확인
  
  
  
  
  • 2. 확장 푸시 알림 확장 푸시 알림 설정은 확장 푸시 알림 가이드를 참고하세요.
  
  
  
  
  • 3. 등록 토큰 전달하기AppDelegate에서 디바이스 토큰을 SDK에 전달해요.
  objectivec

  - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
  {
      [[SGSPushNotificationCenter currentPushNotificationCenter] application:application didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
  }
  

  
  
  
  
  • 4. 앱 실행 중 푸시 보이게 하기 — SGSPushNotificationCenterDelegate 등록
  objectivec

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  {
      [[SGSPushNotificationCenter currentPushNotificationCenter] setDelegate:self];
  }
  

  
  포그라운드 푸시 알림 표시 옵션이에요. 필요한 옵션을 조합해 completionHandler에 전달하세요.

  옵션	설명	지원 버전
  UNNotificationPresentationOptionBanner	화면 상단 배너로 알림 표시 (일정 시간 후 자동 해제)	iOS 14+
  UNNotificationPresentationOptionList	알림센터에 쌓아 나중에 확인 가능	iOS 14+
  UNNotificationPresentationOptionSound	알림 수신 시 사운드 재생	iOS 10+
  UNNotificationPresentationOptionAlert	Banner + List 통합 (iOS 14+ deprecated, 미만 대응 시만 사용)	iOS 10+

  • 사용 예시 — 배너 + 사운드
  objectivec

  - (void)willPresentNotification:(UNNotification *)notification 
           withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
  {
      if (@available(iOS 14.0, *)) {
          completionHandler(UNNotificationPresentationOptionBanner | UNNotificationPresentationOptionSound);
      } else {
          completionHandler(UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionSound);
      }
  }
  

  
  
  
  
  • 사용 예시 — 배너 + 사운드 + 알림센터
  objectivec

  - (void)willPresentNotification:(UNNotification *)notification 
           withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
  {
      if (@available(iOS 14.0, *)) {
          completionHandler(UNNotificationPresentationOptionBanner | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionList);
      } else {
          completionHandler(UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionSound);
      }
  }
  

• Unity 설정
  • Android 설정 — google-services.json → google_services.xml 변환

1. generate_xml_from_google_services_json.py 다운로드
2. 터미널에서 아래 명령어 실행

generate_xml_from_google_services_json.py -i {google-services.json 경로} -o {출력 파일 경로} -p {yourPackageName}

예시:

/Users/user/Desktop/generate_xml_from_google_services_json.py -i /Users/user/Desktop/google-services.json -o /Users/user/Desktop/google_services.xml -p com.stove.mvp

3. 변환된 파일을 Plugins/Android/res/values 폴더에 복사

iOS 설정 — 앱 실행 중 푸시 옵션 (info.plist)

SDK Plugin 내부에서 포그라운드 푸시 설정을 처리해요. 게임에서는 info.plist에 아래 키를 추가해 동작을 변경할 수 있어요.

두 키 모두 info.plist에 키가 없으면 기본값 YES로 동작해요. 기본 설정을 그대로 쓸 거면 별도 추가가 필요 없어요.

설정 예시:

• 포그라운드 푸시 비활성화: <key>ForegroundPushEnabled</key><false/>
• 알림센터 비활성화: <key>EnablePushListOptions</key><false/>

Unreal 설정

Android 설정 — google-services.json → google_services.xml 변환

1. generate_xml_from_google_services_json.py 다운로드
2. 터미널에서 아래 명령어 실행

generate_xml_from_google_services_json.py -i {google-services.json 경로} -o {출력 파일 경로} -p {yourPackageName}

3. 변환된 파일을 Source/StoveSDK 폴더에 복사

iOS Capabilities 설정

커스텀 엔진 빌드에서만 동작해요.

메뉴 → 편집 → 프로젝트 세팅 → iOS → Enable Remote Notifications Support 기능을 활성화하면 빌드 시 자동으로 Capabilities가 설정돼요.

iOS — 앱 실행 중 푸시 옵션 (info.plist)

Unity와 동일한 ForegroundPushEnabled / EnablePushListOptions 키를 info.plist에 추가해 동작을 변경할 수 있어요.

설정 방법: Unreal Editor → 편집 → 플러그인 → iOS → Extra PList Data → Additional Info plist 하단에 key-value 추가.

설정 예시:

• 포그라운드 푸시 비활성화: <key>ForegroundPushEnabled</key><false/>
• 알림센터 비활성화: <key>EnablePushListOptions</key><false/>

푸시 등록

푸시 등록은 로그인·가입·토큰 갱신·계정 연결 완료 시 자동으로 돼요. 별도 API 호출은 필요 없어요.

• 게임에서 여러 월드를 지원한다면 마지막 접속 월드로만 푸시가 전송돼요.

ErrorCodes

푸시 설정 조회

현재 이용자의 푸시 설정(주간/야간 알림)을 조회해요.

private void FetchPushSettings()
{
    Push.FetchPushSettings((Result result, PushSettings pushSettings) =>
    {
        if (result.IsSuccessful)
        {
            bool EnabledDay = (bool)pushSettings.EnabledDay;
            bool EnabledNight = (bool)pushSettings.EnabledNight;
        }
    });
}

ErrorCodes

푸시 수신 설정

푸시 수신 On/Off, 야간 푸시 On/Off는 모두 **하나의 API Push.updatePushSettings(context, settings, listener)**를 호출하고 PushSettings의 enabledDay / enabledNight 값만 다르게 전달해요. 응답 콜백은 모든 케이스가 동일한 Result와 PushSettings를 반환하므로, 에러 처리는 아래 한 번의 ErrorCodes 표를 공유해요.

푸시 알림 On

PushSettings(enabledDay = true, enabledNight = null)를 전달해 주간 푸시 알림을 활성화해요.

public void UpdatePushSettings()
{
    PushSettings settings = new PushSettings(true, null);
    Push.UpdatePushSettings(settings, (Result result, PushSettings pushSettings) =>
    {
        if(result.IsSuccessful)
        {
            bool EnabledDay = (bool)pushSettings.EnabledDay;
            bool EnabledNight = (bool)pushSettings.EnabledNight;
        }
    });
}

푸시 알림 Off

푸시 알림을 Off하면 야간 푸시도 함께 Off 처리해야 해요.

public void UpdatePushSettings()
{
    PushSettings settings = new PushSettings(false, false);
    Push.UpdatePushSettings(settings, (Result result, PushSettings pushSettings) =>
    {
        if(result.IsSuccessful)
        {
            bool EnabledDay = (bool)pushSettings.EnabledDay;
            bool EnabledNight = (bool)pushSettings.EnabledNight;
        }
    });
}

야간 푸시 On

푸시 알림이 Off 상태이면 야간 푸시를 On할 수 없어요. 먼저 푸시 알림을 On한 뒤 호출하세요.

public void UpdatePushSettings()
{
    PushSettings settings = new PushSettings(null, true);
    Push.UpdatePushSettings(settings, (Result result, PushSettings pushSettings) =>
    {
        if(result.IsSuccessful)
        {
            bool EnabledDay = (bool)pushSettings.EnabledDay;
            bool EnabledNight = (bool)pushSettings.EnabledNight;
        }
    });
}

야간 푸시 Off

주간 푸시 설정은 유지한 채 야간 푸시만 Off해요.

public void UpdatePushSettings()
{
    PushSettings settings = new PushSettings(null, false);
    Push.UpdatePushSettings(settings, (Result result, PushSettings pushSettings) =>
    {
        if(result.IsSuccessful)
        {
            bool EnabledDay = (bool)pushSettings.EnabledDay;
            bool EnabledNight = (bool)pushSettings.EnabledNight;
        }
    });
}

ErrorCodes

확장 푸시 알림 (iOS)

제목·부제목·내용·이미지를 포함한 iOS 확장 푸시(Notification Service Extension) 설정 방법을 안내해요.

Xcode Project 설정

• 1. Notification Service Extension Target 추가
  • Xcode Project에서 + 버튼을 선택한 뒤, Target 추가 화면에서 Notification Service Extension을 선택하고 Next를 눌러요.
  
  
  
  
• 2. Product Name 및 Embed 설정
  • Product Name을 NotificationServiceExtension으로 지정하고, Embed in Application 항목을 현재 게임 Project Target으로 지정한 뒤 Finish를 선택해요.
  
  
  
  
• 3. 스키마 추가
  • 스키마 추가 여부를 묻는 팝업이 표시되면 Activate를 선택해요.
  
  
  
  
• 4. 생성 파일 확인
  • Project 내부에 NotificationServiceExtension 그룹과 NotificationService.h, Notification.m, Info.plist 파일이 생성됐는지, Project Target에 NotificationServiceExtension이 추가됐는지 확인해요.
  
  
  
  
• 5. Deployment Target 변경
  • Project Target에서 NotificationServiceExtension을 선택하고, General → Deployment Info의 Target 버전을 iOS 10.0으로 변경해요. (최소 지원 버전 맞추기)
  
  
  
  
• 6. Architectures 확인
  • Project Target에서 NotificationServiceExtension을 선택하고, Build Settings의 Architectures 항목이 Standard architectures로 설정됐는지 확인해요.
  
  
  
  
• 7. Capability 설정
  • 확장 푸시 지표 확인을 위해 Capability 설정이 필요해요.
  
  
  
  
• 8. App Groups Capability 추가
  • Build Settings → Capabilities 화면에서 추가 버튼을 클릭해요.
  
  • App Groups를 검색해요.
  
  • App Groups가 추가됐는지 확인해요. App Groups는 group. + Bundle Identifier 형식으로 설정해요. (예: group.com.stove.sdk)
  
  
  
  
• 9. NotificationService.m 코드 작성
  • Project 내부 NotificationServiceExtension 그룹(4번 참조)의 NotificationService.m 파일을 열어 아래와 같이 작성해요.

#import "NotificationService.h"
#import <SGSPushExtension/SGSPushExtension.h>

@interface NotificationService ()

@property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    
    [NotificationServiceExtension didReceive:request withContentHandler:contentHandler];
}

- (void)serviceExtensionTimeWillExpire {
    // Called just before the extension will be terminated by the system.
    // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
    self.contentHandler(self.bestAttemptContent);
}

@end

Release용 Provisioning Profile 생성

• 1. Apple Developer Console 접속
  • Certificates, Identifiers & Profiles 항목에 들어가요.
  
  
  
  
• 2. Identifier 등록 시작
  • 왼쪽 메뉴에서 Identifiers를 선택한 뒤, Identifiers + 를 선택해요.
  
  
  
  
• 3. App IDs 선택
  • App IDs를 선택하고 Continue를 눌러요.
  
  
  
  
• 4. Bundle ID 입력
  • Description을 입력하고, Bundle ID에 게임 Bundle ID + .NotificationServiceExtension을 붙여 넣은 뒤 Continue를 선택해요.
  • Bundle ID 예시: com.stove.xxx.NotificationServiceExtension
  
  
  
  
• 5. 등록 완료
  • Register를 선택해 등록을 마무리해요.
  
  
  
  
• 6. Identifier 등록 확인
  • Identifiers 화면으로 돌아가 방금 만든 ID가 등록됐는지 확인해요.
  
  
  
  
• 7. Profile 생성 시작
  • 왼쪽 메뉴에서 Profiles를 선택한 뒤, Profiles + 를 선택해요.
  
  
  
  
• 8. Distribution 유형 선택
  • Distribution 항목에서 Ad Hoc, App Store 등 배포 방식에 맞게 선택한 뒤 Continue를 눌러요. (아래 가이드는 Ad Hoc 기준이에요.)
  
  
  
  
• 9. App ID 선택
  • App ID 항목에서 위에서 만든 ID 값을 선택한 뒤 Continue를 눌러요.
  
  
  
  
• 10. 인증서 선택
  • Provisioning Profile에 맞는 인증서를 선택한 뒤 Continue를 눌러요.
  
  
  
  
• 11. Profile 이름 입력 및 생성
  • Provisioning Profile Name을 입력하고 Generate를 선택해요.
  
  
  
  
• 12. Profile 다운로드
  • Profiles 페이지에서 생성한 Provisioning Profile을 확인한 뒤 Download를 선택해 로컬에 저장해요.
  
  
  
  
• 13. Xcode에 Profile 추가
  • 저장된 Provisioning Profile을 더블 클릭해 Xcode에 추가해요.
  
  
  
  
• 14. Signing 설정 확인
  • Xcode Project에서 NotificationServiceExtension Target을 선택한 뒤, Signing & Capabilities → Signing (Release) 에 Provisioning Profile이 정상 설정됐는지 확인해요.
  

App Groups 생성

• 1. App Group Identifier 등록
  • Apple Developer — App Groups에 접속해요.
  
  
  
  
• 2. Group ID 생성
  • group. + 게임 Bundle Identifier 형식으로 생성해요.
  
  
  
  
• 3. App ID 선택
  • 게임 App ID를 선택해요.
  
  
  
  
• 4. App Groups 연결
  • App Groups Edit 버튼을 선택해 생성된 App Groups를 연결해요.
  

이미지 푸시 전송

파트너스 센터에서 이미지 포함 푸시를 발송할 수 있어요.

• 경로: GM → PUSH알림 → PUSH알림(mo)
• 파트너스: partners.gate8.com

자주 묻는 질문