Skip to content
스토브
마지막 업데이트

베트남 게임 규제 대응

개발하기


모바일

이용시간에 따른 건강 경고 콜백(setPlaytimeListener)을 등록하는 흐름이에요. SDK 초기화 이후 리스너를 등록하면, 로그인 완료 직후 1회 콜백을 받고 이후 daily_play_limit_sec 주기마다 콜백이 전달돼요. iOS는 NSNotificationCenter 옵저버 방식으로 동일한 흐름을 처리해요.


사전 준비

  • 파트너스 SDK Config에 daily_play_limit_sec 값이 설정돼 있어야 해요.
  • Auth.initialize 완료 이후 시점에 리스너·옵저버를 등록해요. 초기화 전에 등록하면 콜백이 전달되지 않아요.
  • iOS는 옵저버를 등록한 컴포넌트가 해제될 때 removeObserver로 함께 해제해 누수를 방지하세요.

개발 흐름

  1. 리스너 등록: SDK 초기화 완료 콜백 이후 시점에 Auth.setPlaytimeListener(Android/Unity) 또는 SGSPlaytimeDidUpdateNotification 옵저버(iOS)를 등록해요.
  2. 로그인 완료 대기: 이용자가 로그인을 완료하면 타이머가 활성화되고 1회 콜백이 전달돼요.
  3. 주기 콜백 처리: 이후 콜백마다 건강 경고 메시지·UI를 게임 화면에 노출해요. 게임 진행을 막지 않도록 비차단형 UI(토스트·배너 등)를 권장해요.

트러블슈팅

상황원인해결 방법
콜백이 한 번도 호출되지 않아요SDK 초기화·로그인 완료 이전에 리스너를 등록했거나, 빌드가 STOVE VN 환경이 아니에요.Auth.initialize 성공 콜백 이후에 리스너를 등록하도록 호출 순서를 조정하세요. STOVE VN 전용 기능이므로 다른 지역 빌드에서는 콜백이 발생하지 않아요.
콜백 주기가 예상과 달라요파트너스 daily_play_limit_sec 값이 의도와 다르게 설정돼 있거나, 빌드 시점 Config가 최신이 아니에요.파트너스에서 daily_play_limit_sec 값을 확인하고 필요한 주기로 갱신한 뒤, 클라이언트가 최신 Config를 받아오도록 재로그인 또는 앱 재시작으로 검증하세요.
iOS에서 메모리 누수가 발생해요옵저버를 등록한 컴포넌트가 해제될 때 removeObserver를 호출하지 않았어요.옵저버를 등록한 객체의 dealloc(또는 해당 라이프사이클 종료 시점)에서 [[NSNotificationCenter defaultCenter] removeObserver:self]를 호출하세요.

샘플 코드

csharp
public void SetPlaytimeListener()
{
    Auth.SetPlaytimeListener(playtimeInfo =>
    {
        //파트너스에 설정된 시간마다 콜백
        // daily_play_limit_sec : 1800 설정 시 30분 주기로 처리
    });
}

PC

베트남 연령등급 표시와 과몰입 알림을 PC SDK(Base SDK)로 연동하는 흐름이에요. 두 기능 모두 콜백을 등록하면 SDK가 오버레이 표시 정보를 전달하고, 게임이 그 정보로 오버레이를 직접 렌더링해요.


사전 준비

베트남에 게임을 서비스하려면 연령등급 표시와 과몰입 알림을 화면에 노출해야 해요. STOVE PC SDK의 Base SDK가 이 두 가지 규제 정보를 콜백으로 전달하면, 게임이 전달받은 정보로 오버레이 UI를 직접 그려요. 베트남 서비스에 필수로 적용해야 하는 항목이에요.

베트남 규제 기능을 사용하려면 먼저 게임에 Base SDK를 연동해야 해요. Base SDK 연동 방법은 Base SDK 연동 문서를 참고하세요.

  • Base_Initialize로 Base SDK가 초기화돼 있어야 해요.
  • SDK의 비동기 콜백은 Base_RunCallback()을 호출하는 스레드에서 실행돼요. 게임 루프에서 Base_RunCallback()을 주기적으로 호출해야 콜백이 정상 동작해요.
  • 두 콜백 모두 오버레이 렌더링이 가능한 시점 이후에 API를 호출하거나, 전달받은 정보를 저장해 두었다가 렌더링이 가능해진 시점에 사용하세요.
  • 베트남 규제 기능은 Base_UnInitialize 호출 시 등록된 콜백이 자동으로 해제돼요.

베트남 게임제한 API를 직접 연동할 때 참고할 수 있는 디자인 가이드와 이미지 리소스예요.



개발 흐름

두 가지 규제 기능

기능 API 설명
연령등급 표시 Base_VietnamAgeRatingNotification 게임의 연령등급 정보를 오버레이로 상시 표시해요. SDK가 오버레이 위치·크기·투명도·타입 정보를 콜백으로 전달하면 게임이 오버레이를 직접 렌더링해요.
과몰입 알림 Base_VietnamOverimmersionNotification 게임 플레이 시간에 따른 과몰입 경고를 일정 주기마다 오버레이로 표시해요. 경고 메시지·경과 시간·노출 시간과 함께 오버레이 표시/숨김/확장 상태를 콜백으로 전달해요.



한국 과몰입 방지와의 차이

한국 과몰입 방지는 콜백에서 받은 메시지·경과시간·노출시간을 게임이 표시하기만 하면 돼요. 베트남 규제는 메시지 외에 좌표·투명도·크기·타입 등의 추가 정보까지 콜백으로 전달받아, 게임이 오버레이를 직접 구현해야 해요. 오버레이 표시 상태(SHOW/HIDE/EXPANDED)에 따라 노출 여부도 게임에서 제어해요. 연령등급 표시와 과몰입 알림은 별도 API로 분리돼 있어요.



오버레이 표시 상태 (StoveOverlayState / StoveOverlayMode)

콜백으로 전달되는 오버레이 표시 상태값이에요.

상태 설명
0 SHOW 연령등급: 오버레이를 표시해요. 과몰입: 타이머가 활성화돼요(표시 불필요).
1 HIDE 오버레이를 숨겨요.
2 EXPANDED 오버레이를 확장 표시해요. 과몰입에서만 사용하며, 연령등급에서는 사용하지 않아요.



콜백 구조체 필드 적용 방법

콜백으로 전달되는 구조체의 각 필드를 다음과 같이 적용해요.

필드 적용 방법
overlayMode 오버레이 표시 상태. 연령등급은 SHOW/HIDE만, 과몰입은 SHOW/EXPANDED/HIDE를 사용해요.
overlayType 0 = Black 테마(어두운 배경, 밝은 게임 화면에 적합), 1 = White 테마(밝은 배경, 어두운 게임 화면에 적합). 연령등급은 테마에 맞는 배지 이미지를, 과몰입은 배경색을 이 값에 따라 설정해요.
overlayScale 화면 면적 3% 기준 크기에 대한 배수예요. 1.0이면 정확히 3% 면적, 0.5이면 그 절반이에요. 기준 크기에 이 값을 곱해 최종 오버레이 크기를 결정하세요.
overlayOpacity 0.0(완전 투명) ~ 1.0(완전 불투명) 범위예요. 현재 항상 1.0이 전달되며, 추후 규정 변경에 대비한 예약 필드예요. 항상 불투명하게 표시하세요.
ageRating 게임 이용 등급. 0 = 전체이용가, 12 = 12세, 16 = 16세, 18 = 18세. 등급에 맞는 표시 이미지를 선택하는 데 사용해요.
displayPositionX / displayPositionY 0.0 ~ 1.0 정규화 좌표. 화면 좌상단이 (0.0, 0.0), 우하단이 (1.0, 1.0)이에요. 게임 해상도에 맞게 픽셀 좌표로 변환하세요(예: 실제X = displayPositionX × 화면너비). 좌표는 오버레이의 중심점 기준이며, 화면 밖으로 나가지 않도록 클램핑이 필요해요.
message SDK에서 현재 설정된 언어로 번역된 안내 문구예요. 텍스트 UI에 그대로 표시하세요.
language 현재 적용된 언어 코드(예: "vi", "en", "ko")예요. 필요 시 게임 내 추가 다국어 처리에 활용할 수 있어요.



오버레이 구현 기준

  • 연령등급 이미지는 법률 요구사항에 따라 게임 화면 면적의 3% 이상으로 노출해야 해요. 과몰입 오버레이는 연령등급 이미지와 동일한 높이를 기준으로 해요.
  • 연령등급 오버레이는 상시 노출이 기본이며, 콜백으로 HIDE가 전달되기 전까지 게임에서 임의로 숨기지 마세요. 노출 위치는 왼쪽 상단 고정이며, 콜백으로 전달되는 displayPositionX/Y 값을 그대로 적용하면 돼요.
  • 연령등급별(0/12/16/18) × 테마별(Black/White) = 8개 배지 이미지를 게임에서 직접 준비해야 해요. SDK에는 이미지가 포함돼 있지 않아요. 배지 이미지에는 연령등급과 안내 문구가 포함돼야 하며 별도 텍스트 렌더링은 불필요해요.
  • 과몰입 오버레이 배경색은 Black 테마(overlayType=0)는 #212121, White 테마(overlayType=1)는 #FFFFFF를 사용해요. 텍스트 색상은 Black 테마는 흰색, White 테마는 검정을 사용해요.
  • 과몰입 styledMessage에는 <b>...</b>, <color=#RRGGBBAA>...</color> 같은 마크업 태그가 포함될 수 있어요. 게임 엔진의 리치 텍스트 기능을 활용해 스타일을 적용하고, 리치 텍스트를 지원하지 않으면 message의 일반 텍스트를 사용하세요.

오버레이 텍스트 권장 폰트는 ko(한국어)·ja(일본어)는 Pretendard, en(영어)·vi(베트남어)는 Anton, zh-cn·zh-tw(중국어)·th(태국어) 등은 Noto Sans예요. 상세 UI 가이드는 디자인 가이드 문서를 참고하세요.



샘플 코드

연령등급 표시와 과몰입 알림 두 기능의 연동 흐름과 코드 예제예요.


베트남 연령등급 표시

Base_VietnamAgeRatingNotification API로 연동해요. 연령등급 오버레이의 표시/숨김이 필요할 때마다 콜백이 호출돼요. 콜백 구조체 StovePCVietnamAgeRatingInfo에는 오버레이 상태·타입·크기·투명도·연령등급·안내 메시지·노출 위치·언어 코드가 담겨 있어요.

  • overlayModeSHOW일 때 오버레이를 표시하고, HIDE일 때 숨겨요. (EXPANDED는 연령등급에서 사용하지 않아요.)
  • 연령등급 콜백은 SHOW 시 1회만 호출되니, 렌더링이 가능한 시점 이후에 API를 호출하거나 전달받은 정보를 저장해 두었다가 사용하세요.


cpp
// 1. BaseSDK 헤더를 포함합니다.
#include "BaseSDK.h"

using namespace Stove::PCSDK::Base;

// 2. 콜백은 SHOW/HIDE 시점마다 호출되는 1회성 알림이며, 렌더링이 가능한 시점 이후에 호출해야 합니다.
void Base_VietnamAgeRatingNotification_Example()
{
    Base_VietnamAgeRatingNotification(
        [](CallbackResult callbackResult, StovePCVietnamAgeRatingInfo vietnamAgeRatingInfo)
        {
            if (callbackResult.GetResult().IsSuccessful())
            {
                StoveOverlayState overlayState = vietnamAgeRatingInfo.GetOverlayState();

                if (overlayState == StoveOverlayState::SHOW)
                {
                    // 오버레이 표시
                    int overlayType = vietnamAgeRatingInfo.GetOverlayType();
                    float scale = vietnamAgeRatingInfo.GetOverlayScale();
                    float opacity = vietnamAgeRatingInfo.GetOverlayOpacity();
                    int ageRating = vietnamAgeRatingInfo.GetAgeRating();
                    const wchar_t* message = vietnamAgeRatingInfo.GetAgeRatingMessage();
                    float posX = vietnamAgeRatingInfo.GetDisplayPositionX();
                    float posY = vietnamAgeRatingInfo.GetDisplayPositionY();
                    const wchar_t* language = vietnamAgeRatingInfo.GetLanguage();

                    // 전달받은 정보로 오버레이 UI 렌더링
                }
                else if (overlayState == StoveOverlayState::HIDE)
                {
                    // 오버레이 숨김
                }
            }
            else
            {
                // 실패 시 로직을 구현해 주세요.
            }
        }
    );
}

베트남 과몰입 알림

Base_VietnamOverimmersionNotification API로 연동해요. 게임을 시작한 후 법령에 따른 시간 주기마다 콜백이 호출돼요. 콜백 구조체 StovePCVietnamOverimmersionInfo에는 오버레이 상태·타입·크기·투명도·연령등급·과몰입 경고 메시지·스타일 메시지·경과 시간·노출 시간·확장 애니메이션 시간·노출 위치·언어 코드가 담겨 있어요.

  • overlayMode에 따라 처리해요. SHOW는 타이머 활성화(표시 불필요), EXPANDED는 오버레이를 표시(expandAnimationTime 동안 중심점에서 X축 방향으로 확장, 높이는 처음부터 전체 유지), HIDE는 숨김이에요.
  • exposureTime(초)만큼 오버레이를 노출한 뒤 자동으로 숨김 처리하세요.
  • 과몰입 콜백은 게임 시작 직후(0분)에도 1회 호출되니, 렌더링이 가능한 시점 이후에 API를 호출하거나 전달받은 정보를 저장해 두었다가 사용하세요.


cpp
// 1. BaseSDK 헤더를 포함합니다.
#include "BaseSDK.h"

using namespace Stove::PCSDK::Base;

// 2. 콜백은 게임 시작 직후(0분)에도 1회 호출되며, 렌더링이 가능한 시점 이후에 호출해야 합니다.
void Base_VietnamOverimmersionNotification_Example()
{
    Base_VietnamOverimmersionNotification(
        [](CallbackResult callbackResult, StovePCVietnamOverimmersionInfo vietnamOverimmersionInfo)
        {
            if (callbackResult.GetResult().IsSuccessful())
            {
                StoveOverlayState overlayState = vietnamOverimmersionInfo.GetOverlayState();

                if (overlayState == StoveOverlayState::SHOW)
                {
                    // 오버레이 축소 상태로 표시 (타이머 활성화)
                    int overlayType = vietnamOverimmersionInfo.GetOverlayType();
                    float scale = vietnamOverimmersionInfo.GetOverlayScale();
                    float opacity = vietnamOverimmersionInfo.GetOverlayOpacity();
                    const wchar_t* message = vietnamOverimmersionInfo.GetOverimmersionMessage();
                    const wchar_t* styledMessage = vietnamOverimmersionInfo.GetStyledMessage();
                    int32_t elapsedTime = vietnamOverimmersionInfo.GetElapsedTime();
                    int32_t exposureTime = vietnamOverimmersionInfo.GetExposureTime();
                    float posX = vietnamOverimmersionInfo.GetDisplayPositionX();
                    float posY = vietnamOverimmersionInfo.GetDisplayPositionY();
                    const wchar_t* language = vietnamOverimmersionInfo.GetLanguage();

                    // 전달받은 정보로 오버레이 UI 렌더링
                }
                else if (overlayState == StoveOverlayState::EXPANDED)
                {
                    // 오버레이 확장 상태로 표시
                    float expandAnimationTime = vietnamOverimmersionInfo.GetExpandAnimationTime();

                    // expandAnimationTime 동안 확장 애니메이션 처리
                }
                else if (overlayState == StoveOverlayState::HIDE)
                {
                    // 오버레이 숨김
                }
            }
            else
            {
                // 실패 시 로직을 구현해 주세요.
            }
        }
    );
}



트러블슈팅

베트남 규제 기능은 베트남 서비스 필수 적용 항목이에요.
이 기능은 베트남에서만 동작해요. 베트남 이외의 국가에서 호출하면 NOT_SUPPORTED_COUNTRY(31) 에러가 반환돼요.

콜백으로 전달되는 구조체 값(ageRating, message, overlayType 등)은 동작 확인용 로깅 목적이에요. 실제 오버레이 화면에 표시하는 연령등급 이미지는 반드시 사전 준비의 이미지 팩(ZIP)에 포함된 리소스를 사용해야 해요.



직접 문의하고 싶으신가요? stove.developers@smilegate.com