---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/addressables.md
---
# Addressable 가이드

## 개요

Addressable Asset System은 Unity에서 권장하는 최신 리소스 관리 방식이에요.\
AppsInToss 미니앱에서는 효율적인 로딩과 메모리 관리를 위해 꼭 사용해야 해요.

***

## Addressable 기본 설정

### 1. 프로젝트 설정

```c#
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using System.Collections.Generic;

[CreateAssetMenu(fileName = "AddressableConfig", menuName = "AppsInToss/Addressable Config")]
public class AddressableConfig : ScriptableObject
{
    [Header("기본 설정")]
    public string remoteLoadPath = "https://cdn.appsintos.com/assets";
    public string buildPath = "ServerData/WebGL";
    public bool enableCaching = true;
    public long maxCacheSize = 1024 * 1024 * 100; // 100MB
    
    [Header("로딩 설정")]
    public int maxConcurrentLoads = 5;
    public float timeoutDuration = 30f;
    public bool enableRetry = true;
    public int maxRetryCount = 3;
    
    [Header("그룹 설정")]
    public AddressableGroupConfig[] groupConfigs;
    
    [System.Serializable]
    public class AddressableGroupConfig
    {
        public string groupName;
        public bool isRemote;
        public bool enableCompression;
        public BundledAssetGroupSchema.BundleCompressionMode compressionType;
        public int priority;
    }
}
```

### 2. 초기화 관리자

```c#
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using System.Collections;
using System.Threading.Tasks;

public class AddressableManager : MonoBehaviour
{
    [Header("설정")]
    public AddressableConfig config;
    public bool initializeOnStart = true;
    
    private static AddressableManager instance;
    private bool isInitialized = false;
    private Dictionary<string, AsyncOperationHandle> loadedAssets = new Dictionary<string, AsyncOperationHandle>();
    private Queue<LoadRequest> loadQueue = new Queue<LoadRequest>();
    private int currentLoadOperations = 0;
    
    public static AddressableManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = FindObjectOfType<AddressableManager>();
                if (instance == null)
                {
                    GameObject go = new GameObject("AddressableManager");
                    instance = go.AddComponent<AddressableManager>();
                    DontDestroyOnLoad(go);
                }
            }
            return instance;
        }
    }
    
    [System.Serializable]
    private class LoadRequest
    {
        public string address;
        public System.Type type;
        public System.Action<AsyncOperationHandle> onComplete;
        public int priority;
        public float requestTime;
    }
    
    private void Awake()
    {
        if (instance == null)
        {
            instance = this;
            DontDestroyOnLoad(gameObject);
            
            if (initializeOnStart)
            {
                StartCoroutine(InitializeAsync());
            }
        }
        else if (instance != this)
        {
            Destroy(gameObject);
        }
    }
    
    private IEnumerator InitializeAsync()
    {
        DebugLogger.LogInfo("Addressable 시스템 초기화 시작", "Addressable");
        
        // Addressable 초기화
        var initHandle = Addressables.InitializeAsync();
        yield return initHandle;
        
        if (initHandle.Status == AsyncOperationStatus.Succeeded)
        {
            DebugLogger.LogInfo("Addressable 초기화 성공", "Addressable");
            
            // 카탈로그 업데이트 확인
            yield return StartCoroutine(CheckForCatalogUpdates());
            
            // 캐시 설정
            SetupCaching();
            
            isInitialized = true;
            
            // 로드 큐 처리 시작
            StartCoroutine(ProcessLoadQueue());
            
            // AppsInToss에 초기화 완료 알림
            NotifyAppsInTossInitialization(true);
        }
        else
        {
            DebugLogger.LogError($"Addressable 초기화 실패: {initHandle.OperationException}", "Addressable");
            NotifyAppsInTossInitialization(false);
        }
    }
    
    private IEnumerator CheckForCatalogUpdates()
    {
        DebugLogger.LogInfo("카탈로그 업데이트 확인 중...", "Addressable");
        
        var checkHandle = Addressables.CheckForCatalogUpdates(false);
        yield return checkHandle;
        
        if (checkHandle.Status == AsyncOperationStatus.Succeeded)
        {
            if (checkHandle.Result.Count > 0)
            {
                DebugLogger.LogInfo($"{checkHandle.Result.Count}개의 카탈로그 업데이트 발견", "Addressable");
                
                var updateHandle = Addressables.UpdateCatalogs(checkHandle.Result, false);
                yield return updateHandle;
                
                if (updateHandle.Status == AsyncOperationStatus.Succeeded)
                {
                    DebugLogger.LogInfo("카탈로그 업데이트 완료", "Addressable");
                }
            }
            else
            {
                DebugLogger.LogInfo("카탈로그 업데이트 없음", "Addressable");
            }
        }
        
        Addressables.Release(checkHandle);
    }
    
    private void SetupCaching()
    {
        if (config.enableCaching)
        {
            // 캐시 크기 설정
            Caching.maximumAvailableDiskSpace = config.maxCacheSize;
            DebugLogger.LogInfo($"캐시 최대 크기 설정: {config.maxCacheSize / 1024 / 1024}MB", "Addressable");
        }
    }
    
    private void NotifyAppsInTossInitialization(bool success)
    {
        string initData = JsonUtility.ToJson(new {
            success = success,
            timestamp = System.DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"),
            cacheEnabled = config.enableCaching,
            maxCacheSize = config.maxCacheSize
        });
        
        Application.ExternalCall("OnAddressableInitialized", initData);
    }
}
```

***

## 에셋 로딩 시스템

### 1. 스마트 로딩 관리

```c#
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using System.Collections;
using System.Collections.Generic;
using System.Linq;

public class SmartAssetLoader : MonoBehaviour
{
    [Header("로딩 설정")]
    public int maxConcurrentLoads = 3;
    public float loadTimeoutSeconds = 30f;
    public bool enablePredictiveLoading = true;
    
    private Dictionary<string, AsyncOperationHandle> activeHandles = new Dictionary<string, AsyncOperationHandle>();
    private Dictionary<string, object> cachedAssets = new Dictionary<string, object>();
    private Queue<LoadOperation> loadQueue = new Queue<LoadOperation>();
    private HashSet<string> predictiveLoadRequests = new HashSet<string>();
    
    private class LoadOperation
    {
        public string address;
        public System.Type assetType;
        public System.Action<object> onSuccess;
        public System.Action<string> onFailure;
        public int priority;
        public float requestTime;
        public int retryCount;
    }
    
    private void Start()
    {
        StartCoroutine(ProcessLoadQueue());
        
        if (enablePredictiveLoading)
        {
            StartCoroutine(PredictiveLoadingRoutine());
        }
    }
    
    public void LoadAssetAsync<T>(string address, System.Action<T> onComplete, System.Action<string> onError = null, int priority = 0)
    {
        // 이미 캐시된 에셋 확인
        if (cachedAssets.TryGetValue(address, out object cachedAsset) && cachedAsset is T)
        {
            onComplete?.Invoke((T)cachedAsset);
            return;
        }
        
        // 로딩 큐에 추가
        LoadOperation operation = new LoadOperation
        {
            address = address,
            assetType = typeof(T),
            onSuccess = (asset) => onComplete?.Invoke((T)asset),
            onFailure = onError,
            priority = priority,
            requestTime = Time.time,
            retryCount = 0
        };
        
        // 우선순위에 따라 정렬된 위치에 삽입
        var tempList = loadQueue.ToList();
        tempList.Add(operation);
        tempList.Sort((a, b) => b.priority.CompareTo(a.priority));
        
        loadQueue.Clear();
        foreach (var op in tempList)
        {
            loadQueue.Enqueue(op);
        }
        
        DebugLogger.LogDebug($"에셋 로딩 요청: {address} (우선순위: {priority})", "AssetLoader");
    }
    
    private IEnumerator ProcessLoadQueue()
    {
        while (true)
        {
            while (loadQueue.Count > 0 && activeHandles.Count < maxConcurrentLoads)
            {
                LoadOperation operation = loadQueue.Dequeue();
                StartCoroutine(LoadAssetCoroutine(operation));
            }
            
            yield return new WaitForSeconds(0.1f);
        }
    }
    
    private IEnumerator LoadAssetCoroutine(LoadOperation operation)
    {
        string address = operation.address;
        
        // 중복 로딩 방지
        if (activeHandles.ContainsKey(address))
        {
            yield return new WaitUntil(() => !activeHandles.ContainsKey(address));
            
            if (cachedAssets.TryGetValue(address, out object asset))
            {
                operation.onSuccess?.Invoke(asset);
                yield break;
            }
        }
        
        DebugLogger.LogInfo($"에셋 로딩 시작: {address}", "AssetLoader");
        
        var handle = Addressables.LoadAssetAsync(address, operation.assetType);
        activeHandles[address] = handle;
        
        float startTime = Time.time;
        bool timedOut = false;
        
        // 타임아웃 처리
        while (!handle.IsDone)
        {
            if (Time.time - startTime > loadTimeoutSeconds)
            {
                timedOut = true;
                break;
            }
            yield return null;
        }
        
        activeHandles.Remove(address);
        
        if (timedOut)
        {
            DebugLogger.LogError($"에셋 로딩 타임아웃: {address}", "AssetLoader");
            Addressables.Release(handle);
            
            // 재시도
            if (operation.retryCount < 3)
            {
                operation.retryCount++;
                DebugLogger.LogInfo($"에셋 로딩 재시도 ({operation.retryCount}/3): {address}", "AssetLoader");
                yield return new WaitForSeconds(1f);
                StartCoroutine(LoadAssetCoroutine(operation));
            }
            else
            {
                operation.onFailure?.Invoke($"로딩 타임아웃: {address}");
            }
        }
        else if (handle.Status == AsyncOperationStatus.Succeeded)
        {
            DebugLogger.LogInfo($"에셋 로딩 완료: {address}", "AssetLoader");
            
            object loadedAsset = handle.Result;
            cachedAssets[address] = loadedAsset;
            operation.onSuccess?.Invoke(loadedAsset);
            
            // 성공적으로 로드된 에셋은 예측 로딩 목록에서 제거
            predictiveLoadRequests.Remove(address);
        }
        else
        {
            DebugLogger.LogError($"에셋 로딩 실패: {address} - {handle.OperationException}", "AssetLoader");
            Addressables.Release(handle);
            
            // 재시도
            if (operation.retryCount < 3)
            {
                operation.retryCount++;
                yield return new WaitForSeconds(2f);
                StartCoroutine(LoadAssetCoroutine(operation));
            }
            else
            {
                operation.onFailure?.Invoke(handle.OperationException?.Message ?? "로딩 실패");
            }
        }
    }
    
    private IEnumerator PredictiveLoadingRoutine()
    {
        while (true)
        {
            yield return new WaitForSeconds(5f);
            
            // 예측 로딩 로직 (게임 상태에 따라)
            string currentScene = UnityEngine.SceneManagement.SceneManager.GetActiveScene().name;
            PredictAssetsForScene(currentScene);
        }
    }
    
    private void PredictAssetsForScene(string sceneName)
    {
        // 씬별 예측 로딩 로직
        List<string> predictedAssets = new List<string>();
        
        switch (sceneName)
        {
            case "MainMenu":
                predictedAssets.AddRange(new[] { "UI/GameModeSelect", "Audio/MenuMusic" });
                break;
            case "GamePlay":
                predictedAssets.AddRange(new[] { "Effects/ExplosionEffect", "Audio/GameplayMusic" });
                break;
        }
        
        foreach (string asset in predictedAssets)
        {
            if (!cachedAssets.ContainsKey(asset) && !predictiveLoadRequests.Contains(asset))
            {
                predictiveLoadRequests.Add(asset);
                LoadAssetAsync<Object>(asset, 
                    (loadedAsset) => DebugLogger.LogDebug($"예측 로딩 완료: {asset}", "PredictiveLoader"),
                    (error) => DebugLogger.LogWarning($"예측 로딩 실패: {asset} - {error}", "PredictiveLoader"),
                    -1 // 낮은 우선순위
                );
            }
        }
    }
    
    public void UnloadAsset(string address)
    {
        if (cachedAssets.Remove(address, out object asset))
        {
            if (activeHandles.TryGetValue(address, out AsyncOperationHandle handle))
            {
                Addressables.Release(handle);
                activeHandles.Remove(address);
            }
            
            DebugLogger.LogInfo($"에셋 언로드: {address}", "AssetLoader");
        }
    }
    
    public void ClearCache()
    {
        foreach (var handle in activeHandles.Values)
        {
            Addressables.Release(handle);
        }
        
        activeHandles.Clear();
        cachedAssets.Clear();
        predictiveLoadRequests.Clear();
        
        DebugLogger.LogInfo("에셋 캐시 클리어 완료", "AssetLoader");
    }
}
```

### 2. 씬별 에셋 관리

```c#
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using System.Collections.Generic;
using System.Collections;

[CreateAssetMenu(fileName = "SceneAssetConfig", menuName = "AppsInToss/Scene Asset Config")]
public class SceneAssetConfig : ScriptableObject
{
    [System.Serializable]
    public class SceneAssetGroup
    {
        public string sceneName;
        public AssetReferenceT<Object>[] preloadAssets;
        public AssetReferenceT<Object>[] lazyLoadAssets;
        public string[] addressesToPreload;
        public string[] addressesToLazyLoad;
    }
    
    [Header("씬별 에셋 설정")]
    public SceneAssetGroup[] sceneAssets;
}

public class SceneAssetManager : MonoBehaviour
{
    [Header("설정")]
    public SceneAssetConfig config;
    
    private Dictionary<string, List<AsyncOperationHandle>> sceneHandles = new Dictionary<string, List<AsyncOperationHandle>>();
    private Dictionary<string, List<object>> sceneAssets = new Dictionary<string, List<object>>();
    private string currentScene = "";
    
    private void Start()
    {
        UnityEngine.SceneManagement.SceneManager.sceneLoaded += OnSceneLoaded;
        UnityEngine.SceneManagement.SceneManager.sceneUnloaded += OnSceneUnloaded;
    }
    
    private void OnDestroy()
    {
        UnityEngine.SceneManagement.SceneManager.sceneLoaded -= OnSceneLoaded;
        UnityEngine.SceneManagement.SceneManager.sceneUnloaded -= OnSceneUnloaded;
    }
    
    private void OnSceneLoaded(UnityEngine.SceneManagement.Scene scene, UnityEngine.SceneManagement.LoadSceneMode mode)
    {
        currentScene = scene.name;
        StartCoroutine(LoadSceneAssets(scene.name));
    }
    
    private void OnSceneUnloaded(UnityEngine.SceneManagement.Scene scene)
    {
        UnloadSceneAssets(scene.name);
    }
    
    private IEnumerator LoadSceneAssets(string sceneName)
    {
        DebugLogger.LogInfo($"씬 에셋 로딩 시작: {sceneName}", "SceneAssetManager");
        
        var sceneConfig = GetSceneConfig(sceneName);
        if (sceneConfig == null)
        {
            DebugLogger.LogWarning($"씬 설정을 찾을 수 없음: {sceneName}", "SceneAssetManager");
            yield break;
        }
        
        List<AsyncOperationHandle> handles = new List<AsyncOperationHandle>();
        List<object> assets = new List<object>();
        
        // 프리로드 에셋들 로딩
        yield return StartCoroutine(LoadAssetGroup(sceneConfig.preloadAssets, sceneConfig.addressesToPreload, handles, assets, "preload"));
        
        sceneHandles[sceneName] = handles;
        sceneAssets[sceneName] = assets;
        
        DebugLogger.LogInfo($"씬 프리로드 완료: {sceneName} ({handles.Count}개 에셋)", "SceneAssetManager");
        
        // 지연 로딩 에셋들은 백그라운드에서 로딩
        StartCoroutine(LoadLazyAssets(sceneName, sceneConfig));
    }
    
    private IEnumerator LoadLazyAssets(string sceneName, SceneAssetConfig.SceneAssetGroup sceneConfig)
    {
        yield return new WaitForSeconds(1f); // 잠시 대기 후 시작
        
        if (currentScene != sceneName) yield break; // 씬이 바뀌었으면 중단
        
        if (!sceneHandles.TryGetValue(sceneName, out List<AsyncOperationHandle> handles))
        {
            handles = new List<AsyncOperationHandle>();
            sceneHandles[sceneName] = handles;
        }
        
        if (!sceneAssets.TryGetValue(sceneName, out List<object> assets))
        {
            assets = new List<object>();
            sceneAssets[sceneName] = assets;
        }
        
        yield return StartCoroutine(LoadAssetGroup(sceneConfig.lazyLoadAssets, sceneConfig.addressesToLazyLoad, handles, assets, "lazy"));
        
        DebugLogger.LogInfo($"씬 지연 로딩 완료: {sceneName}", "SceneAssetManager");
    }
    
    private IEnumerator LoadAssetGroup(AssetReferenceT<Object>[] assetRefs, string[] addresses, 
        List<AsyncOperationHandle> handles, List<object> assets, string groupType)
    {
        // AssetReference 로딩
        if (assetRefs != null)
        {
            foreach (var assetRef in assetRefs)
            {
                if (assetRef == null || !assetRef.RuntimeKeyIsValid()) continue;
                
                var handle = assetRef.LoadAssetAsync();
                yield return handle;
                
                if (handle.Status == AsyncOperationStatus.Succeeded)
                {
                    handles.Add(handle);
                    assets.Add(handle.Result);
                    DebugLogger.LogDebug($"에셋 로딩 성공 ({groupType}): {assetRef.AssetGUID}", "SceneAssetManager");
                }
                else
                {
                    DebugLogger.LogError($"에셋 로딩 실패 ({groupType}): {assetRef.AssetGUID}", "SceneAssetManager");
                    Addressables.Release(handle);
                }
            }
        }
        
        // 주소 기반 로딩
        if (addresses != null)
        {
            foreach (string address in addresses)
            {
                if (string.IsNullOrEmpty(address)) continue;
                
                var handle = Addressables.LoadAssetAsync<Object>(address);
                yield return handle;
                
                if (handle.Status == AsyncOperationStatus.Succeeded)
                {
                    handles.Add(handle);
                    assets.Add(handle.Result);
                    DebugLogger.LogDebug($"에셋 로딩 성공 ({groupType}): {address}", "SceneAssetManager");
                }
                else
                {
                    DebugLogger.LogError($"에셋 로딩 실패 ({groupType}): {address}", "SceneAssetManager");
                    Addressables.Release(handle);
                }
            }
        }
    }
    
    private void UnloadSceneAssets(string sceneName)
    {
        if (sceneHandles.TryGetValue(sceneName, out List<AsyncOperationHandle> handles))
        {
            foreach (var handle in handles)
            {
                if (handle.IsValid())
                {
                    Addressables.Release(handle);
                }
            }
            sceneHandles.Remove(sceneName);
        }
        
        sceneAssets.Remove(sceneName);
        
        DebugLogger.LogInfo($"씬 에셋 언로드 완료: {sceneName}", "SceneAssetManager");
    }
    
    private SceneAssetConfig.SceneAssetGroup GetSceneConfig(string sceneName)
    {
        if (config == null || config.sceneAssets == null) return null;
        
        foreach (var sceneAsset in config.sceneAssets)
        {
            if (sceneAsset.sceneName == sceneName)
                return sceneAsset;
        }
        
        return null;
    }
    
    public T GetSceneAsset<T>(string sceneName, string assetName) where T : Object
    {
        if (sceneAssets.TryGetValue(sceneName, out List<object> assets))
        {
            foreach (object asset in assets)
            {
                if (asset is T typedAsset && typedAsset.name == assetName)
                {
                    return typedAsset;
                }
            }
        }
        
        return null;
    }
}
```

***

## 앱인토스 플랫폼 브릿지

### 1. CDN 에셋 관리

```tsx

interface CDNAssetInfo {
    address: string;
    url: string;
    size: number;
    hash: string;
    version: string;
    compressionType: string;
}

interface LoadProgress {
    address: string;
    bytesLoaded: number;
    totalBytes: number;
    progress: number;
    speed: number;
}

class CDNAssetManager {
    private static instance: CDNAssetManager;
    private baseUrl: string = '';
    private assetManifest: Map<string, CDNAssetInfo> = new Map();
    private downloadQueue: CDNAssetInfo[] = [];
    private maxConcurrentDownloads = 3;
    private currentDownloads = 0;
    private downloadProgressCallbacks: Map<string, (progress: LoadProgress) => void> = new Map();
    
    public static getInstance(): CDNAssetManager {
        if (!CDNAssetManager.instance) {
            CDNAssetManager.instance = new CDNAssetManager();
        }
        return CDNAssetManager.instance;
    }
    
    public async initialize(baseUrl: string): Promise<void> {
        this.baseUrl = baseUrl;
        
        try {
            // 매니페스트 다운로드
            const manifestUrl = `${baseUrl}/catalog.json`;
            const response = await fetch(manifestUrl);
            const manifest = await response.json();
            
            this.parseManifest(manifest);
            
            // Unity에 매니페스트 정보 전송
            const unityInstance = (window as any).unityInstance;
            if (unityInstance) {
                unityInstance.SendMessage('AddressableManager', 'OnManifestLoaded', JSON.stringify({
                    assetCount: this.assetManifest.size,
                    totalSize: this.getTotalSize()
                }));
            }
            
            console.log(`CDN 매니페스트 로드 완료: ${this.assetManifest.size}개 에셋`);
            
        } catch (error) {
            console.error('CDN 매니페스트 로드 실패:', error);
            throw error;
        }
    }
    
    private parseManifest(manifest: any): void {
        if (manifest.assets) {
            for (const asset of manifest.assets) {
                const assetInfo: CDNAssetInfo = {
                    address: asset.address,
                    url: `${this.baseUrl}/${asset.path}`,
                    size: asset.size || 0,
                    hash: asset.hash || '',
                    version: asset.version || '1.0',
                    compressionType: asset.compression || 'none'
                };
                
                this.assetManifest.set(asset.address, assetInfo);
            }
        }
    }
    
    private getTotalSize(): number {
        let totalSize = 0;
        for (const assetInfo of this.assetManifest.values()) {
            totalSize += assetInfo.size;
        }
        return totalSize;
    }
    
    public getAssetInfo(address: string): CDNAssetInfo | null {
        return this.assetManifest.get(address) || null;
    }
    
    public setDownloadProgressCallback(address: string, callback: (progress: LoadProgress) => void): void {
        this.downloadProgressCallbacks.set(address, callback);
    }
    
    public async downloadAsset(address: string): Promise<ArrayBuffer> {
        const assetInfo = this.assetManifest.get(address);
        if (!assetInfo) {
            throw new Error(`에셋을 찾을 수 없음: ${address}`);
        }
        
        return new Promise((resolve, reject) => {
            const xhr = new XMLHttpRequest();
            xhr.open('GET', assetInfo.url, true);
            xhr.responseType = 'arraybuffer';
            
            const startTime = performance.now();
            let lastProgressTime = startTime;
            let lastLoadedBytes = 0;
            
            xhr.onprogress = (event) => {
                if (event.lengthComputable) {
                    const currentTime = performance.now();
                    const timeDiff = (currentTime - lastProgressTime) / 1000;
                    const bytesDiff = event.loaded - lastLoadedBytes;
                    const speed = timeDiff > 0 ? bytesDiff / timeDiff : 0;
                    
                    const progress: LoadProgress = {
                        address: address,
                        bytesLoaded: event.loaded,
                        totalBytes: event.total,
                        progress: event.loaded / event.total,
                        speed: speed
                    };
                    
                    const callback = this.downloadProgressCallbacks.get(address);
                    if (callback) {
                        callback(progress);
                    }
                    
                    // Unity에 진행 상황 전송
                    const unityInstance = (window as any).unityInstance;
                    if (unityInstance) {
                        unityInstance.SendMessage('AddressableManager', 'OnDownloadProgress', JSON.stringify(progress));
                    }
                    
                    lastProgressTime = currentTime;
                    lastLoadedBytes = event.loaded;
                }
            };
            
            xhr.onload = () => {
                if (xhr.status === 200) {
                    const totalTime = (performance.now() - startTime) / 1000;
                    console.log(`에셋 다운로드 완료: ${address} (${(assetInfo.size / 1024 / 1024).toFixed(2)}MB, ${totalTime.toFixed(2)}초)`);
                    resolve(xhr.response);
                } else {
                    reject(new Error(`다운로드 실패: ${xhr.status}`));
                }
            };
            
            xhr.onerror = () => {
                reject(new Error('네트워크 오류'));
            };
            
            xhr.send();
        });
    }
    
}

// Unity에서 호출할 함수들
(window as any).InitializeCDNAssets = async (baseUrl: string) => {
    try {
        await CDNAssetManager.getInstance().initialize(baseUrl);
        return true;
    } catch (error) {
        console.error('CDN 초기화 실패:', error);
        return false;
    }
};

(window as any).GetAssetInfo = (address: string) => {
    const assetInfo = CDNAssetManager.getInstance().getAssetInfo(address);
    return assetInfo ? JSON.stringify(assetInfo) : null;
};
```

### 2. 오프라인 캐싱 시스템

```c#
using UnityEngine;
using UnityEngine.AddressableAssets;
using System.Collections.Generic;
using System.Collections;
using System.IO;

public class OfflineCacheManager : MonoBehaviour
{
    [Header("캐시 설정")]
    public long maxCacheSize = 200 * 1024 * 1024; // 200MB
    public float cacheCleanupInterval = 300f; // 5분
    public bool enableOfflineMode = true;
    
    [Header("우선순위 설정")]
    public string[] highPriorityAssets;
    public string[] lowPriorityAssets;
    
    private Dictionary<string, CacheEntry> cacheEntries = new Dictionary<string, CacheEntry>();
    private long currentCacheSize = 0;
    private string cacheDirectory;
    
    [System.Serializable]
    public class CacheEntry
    {
        public string address;
        public string filePath;
        public long fileSize;
        public System.DateTime lastAccessed;
        public System.DateTime cachedTime;
        public int priority;
        public string hash;
    }
    
    private void Start()
    {
        InitializeCache();
        
        if (enableOfflineMode)
        {
            InvokeRepeating(nameof(CleanupCache), cacheCleanupInterval, cacheCleanupInterval);
        }
    }
    
    private void InitializeCache()
    {
        cacheDirectory = Path.Combine(Application.persistentDataPath, "AddressableCache");
        
        if (!Directory.Exists(cacheDirectory))
        {
            Directory.CreateDirectory(cacheDirectory);
        }
        
        LoadCacheIndex();
        CalculateCacheSize();
        
        DebugLogger.LogInfo($"오프라인 캐시 초기화 완료: {currentCacheSize / 1024 / 1024}MB / {maxCacheSize / 1024 / 1024}MB", "OfflineCache");
    }
    
    private void LoadCacheIndex()
    {
        string indexPath = Path.Combine(cacheDirectory, "cache_index.json");
        
        if (File.Exists(indexPath))
        {
            try
            {
                string json = File.ReadAllText(indexPath);
                var cacheData = JsonUtility.FromJson<CacheIndexData>(json);
                
                foreach (var entry in cacheData.entries)
                {
                    if (File.Exists(entry.filePath))
                    {
                        cacheEntries[entry.address] = entry;
                    }
                }
                
                DebugLogger.LogInfo($"캐시 인덱스 로드됨: {cacheEntries.Count}개 항목", "OfflineCache");
            }
            catch (System.Exception e)
            {
                DebugLogger.LogError($"캐시 인덱스 로드 실패: {e.Message}", "OfflineCache");
            }
        }
    }
    
    private void SaveCacheIndex()
    {
        string indexPath = Path.Combine(cacheDirectory, "cache_index.json");
        
        try
        {
            var cacheData = new CacheIndexData { entries = new List<CacheEntry>(cacheEntries.Values) };
            string json = JsonUtility.ToJson(cacheData, true);
            File.WriteAllText(indexPath, json);
        }
        catch (System.Exception e)
        {
            DebugLogger.LogError($"캐시 인덱스 저장 실패: {e.Message}", "OfflineCache");
        }
    }
    
    [System.Serializable]
    private class CacheIndexData
    {
        public List<CacheEntry> entries = new List<CacheEntry>();
    }
    
    private void CalculateCacheSize()
    {
        currentCacheSize = 0;
        
        foreach (var entry in cacheEntries.Values)
        {
            if (File.Exists(entry.filePath))
            {
                entry.fileSize = new FileInfo(entry.filePath).Length;
                currentCacheSize += entry.fileSize;
            }
        }
    }
    
    public bool IsAssetCached(string address)
    {
        if (!cacheEntries.TryGetValue(address, out CacheEntry entry))
            return false;
        
        return File.Exists(entry.filePath);
    }
    
    public void CacheAsset(string address, byte[] data, string hash = "")
    {
        if (currentCacheSize + data.Length > maxCacheSize)
        {
            FreeUpSpace(data.Length);
        }
        
        string fileName = GetCacheFileName(address);
        string filePath = Path.Combine(cacheDirectory, fileName);
        
        try
        {
            File.WriteAllBytes(filePath, data);
            
            var entry = new CacheEntry
            {
                address = address,
                filePath = filePath,
                fileSize = data.Length,
                lastAccessed = System.DateTime.Now,
                cachedTime = System.DateTime.Now,
                priority = GetAssetPriority(address),
                hash = hash
            };
            
            // 기존 항목 제거 (있는 경우)
            if (cacheEntries.TryGetValue(address, out CacheEntry oldEntry))
            {
                currentCacheSize -= oldEntry.fileSize;
                if (File.Exists(oldEntry.filePath))
                {
                    File.Delete(oldEntry.filePath);
                }
            }
            
            cacheEntries[address] = entry;
            currentCacheSize += data.Length;
            
            SaveCacheIndex();
            
            DebugLogger.LogDebug($"에셋 캐시됨: {address} ({data.Length / 1024}KB)", "OfflineCache");
        }
        catch (System.Exception e)
        {
            DebugLogger.LogError($"에셋 캐시 실패: {address} - {e.Message}", "OfflineCache");
        }
    }
    
    public byte[] GetCachedAsset(string address)
    {
        if (!cacheEntries.TryGetValue(address, out CacheEntry entry))
            return null;
        
        if (!File.Exists(entry.filePath))
            return null;
        
        try
        {
            entry.lastAccessed = System.DateTime.Now;
            byte[] data = File.ReadAllBytes(entry.filePath);
            
            DebugLogger.LogDebug($"캐시된 에셋 로드: {address}", "OfflineCache");
            return data;
        }
        catch (System.Exception e)
        {
            DebugLogger.LogError($"캐시된 에셋 로드 실패: {address} - {e.Message}", "OfflineCache");
            return null;
        }
    }
    
    private void FreeUpSpace(long requiredSpace)
    {
        long spaceToFree = requiredSpace + (maxCacheSize * 0.1f); // 10% 여유 공간
        var entriesToRemove = new List<string>();
        
        // 우선순위와 마지막 접근 시간 기준으로 정렬
        var sortedEntries = new List<CacheEntry>(cacheEntries.Values);
        sortedEntries.Sort((a, b) => {
            if (a.priority != b.priority)
                return a.priority.CompareTo(b.priority); // 낮은 우선순위 먼저
            return a.lastAccessed.CompareTo(b.lastAccessed); // 오래된 것 먼저
        });
        
        long freedSpace = 0;
        foreach (var entry in sortedEntries)
        {
            if (freedSpace >= spaceToFree)
                break;
            
            entriesToRemove.Add(entry.address);
            freedSpace += entry.fileSize;
        }
        
        // 선택된 항목들 삭제
        foreach (string address in entriesToRemove)
        {
            RemoveCachedAsset(address);
        }
        
        DebugLogger.LogInfo($"캐시 정리 완료: {freedSpace / 1024 / 1024}MB 확보", "OfflineCache");
    }
    
    private void RemoveCachedAsset(string address)
    {
        if (cacheEntries.TryGetValue(address, out CacheEntry entry))
        {
            if (File.Exists(entry.filePath))
            {
                try
                {
                    File.Delete(entry.filePath);
                    currentCacheSize -= entry.fileSize;
                }
                catch (System.Exception e)
                {
                    DebugLogger.LogError($"캐시 파일 삭제 실패: {entry.filePath} - {e.Message}", "OfflineCache");
                }
            }
            
            cacheEntries.Remove(address);
        }
    }
    
    private int GetAssetPriority(string address)
    {
        if (System.Array.IndexOf(highPriorityAssets, address) >= 0)
            return 10; // 높은 우선순위
        if (System.Array.IndexOf(lowPriorityAssets, address) >= 0)
            return 1; // 낮은 우선순위
        return 5; // 보통 우선순위
    }
    
    private string GetCacheFileName(string address)
    {
        // 주소를 파일명으로 변환 (특수문자 제거)
        string fileName = address.Replace("/", "_").Replace("\\", "_").Replace(":", "_");
        return $"{fileName}.cache";
    }
    
    private void CleanupCache()
    {
        var expiredEntries = new List<string>();
        var expireTime = System.TimeSpan.FromDays(7); // 7일 후 만료
        
        foreach (var kvp in cacheEntries)
        {
            if (System.DateTime.Now - kvp.Value.cachedTime > expireTime)
            {
                expiredEntries.Add(kvp.Key);
            }
        }
        
        foreach (string address in expiredEntries)
        {
            RemoveCachedAsset(address);
        }
        
        if (expiredEntries.Count > 0)
        {
            SaveCacheIndex();
            DebugLogger.LogInfo($"만료된 캐시 정리: {expiredEntries.Count}개 항목", "OfflineCache");
        }
    }
    
    public void ClearAllCache()
    {
        foreach (var entry in cacheEntries.Values)
        {
            if (File.Exists(entry.filePath))
            {
                File.Delete(entry.filePath);
            }
        }
        
        cacheEntries.Clear();
        currentCacheSize = 0;
        SaveCacheIndex();
        
        DebugLogger.LogInfo("모든 캐시 삭제 완료", "OfflineCache");
    }
    
    public string GetCacheStatus()
    {
        return JsonUtility.ToJson(new {
            cachedAssets = cacheEntries.Count,
            totalSize = currentCacheSize,
            maxSize = maxCacheSize,
            usagePercentage = (float)currentCacheSize / maxCacheSize * 100
        });
    }
}
```

***

## 메모리 최적화 및 성능

### 1. 메모리 효율적인 로딩

```c#
using UnityEngine;
using UnityEngine.AddressableAssets;
using System.Collections.Generic;

public class MemoryEfficientLoader : MonoBehaviour
{
    [Header("메모리 관리")]
    public long memoryBudget = 50 * 1024 * 1024; // 50MB
    public float memoryCheckInterval = 5f;
    public bool enableAdaptiveUnloading = true;
    
    private Dictionary<string, LoadedAssetInfo> loadedAssets = new Dictionary<string, LoadedAssetInfo>();
    private Queue<string> unloadQueue = new Queue<string>();
    
    [System.Serializable]
    public class LoadedAssetInfo
    {
        public object asset;
        public AsyncOperationHandle handle;
        public long memorySize;
        public System.DateTime loadTime;
        public System.DateTime lastUsed;
        public int useCount;
        public bool isPermanent;
    }
    
    private void Start()
    {
        if (enableAdaptiveUnloading)
        {
            InvokeRepeating(nameof(CheckMemoryUsage), memoryCheckInterval, memoryCheckInterval);
        }
    }
    
    private void CheckMemoryUsage()
    {
        long totalMemory = System.GC.GetTotalMemory(false);
        long assetMemory = CalculateAssetMemoryUsage();
        
        if (totalMemory > memoryBudget || assetMemory > memoryBudget * 0.8f)
        {
            UnloadUnusedAssets();
        }
    }
    
    private long CalculateAssetMemoryUsage()
    {
        long total = 0;
        foreach (var info in loadedAssets.Values)
        {
            total += info.memorySize;
        }
        return total;
    }
    
    private void UnloadUnusedAssets()
    {
        var assetsToUnload = new List<string>();
        var now = System.DateTime.Now;
        
        // 사용되지 않은 에셋들을 찾아서 언로드 큐에 추가
        foreach (var kvp in loadedAssets)
        {
            var info = kvp.Value;
            
            if (info.isPermanent) continue;
            
            // 마지막 사용 후 5분 이상 지난 에셋
            if ((now - info.lastUsed).TotalMinutes > 5 && info.useCount == 0)
            {
                assetsToUnload.Add(kvp.Key);
            }
        }
        
        // 사용 빈도와 메모리 크기를 고려하여 정렬
        assetsToUnload.Sort((a, b) => {
            var infoA = loadedAssets[a];
            var infoB = loadedAssets[b];
            
            // 사용 빈도가 낮고 메모리를 많이 차지하는 것 우선
            float scoreA = infoA.memorySize / (float)(infoA.useCount + 1);
            float scoreB = infoB.memorySize / (float)(infoB.useCount + 1);
            
            return scoreB.CompareTo(scoreA);
        });
        
        // 메모리 사용량이 임계값 이하가 될 때까지 언로드
        long currentMemory = CalculateAssetMemoryUsage();
        long targetMemory = memoryBudget / 2; // 절반까지 줄이기
        
        foreach (string address in assetsToUnload)
        {
            if (currentMemory <= targetMemory) break;
            
            var info = loadedAssets[address];
            currentMemory -= info.memorySize;
            
            UnloadAsset(address);
        }
        
        if (assetsToUnload.Count > 0)
        {
            DebugLogger.LogInfo($"메모리 정리: {assetsToUnload.Count}개 에셋 언로드", "MemoryManager");
        }
    }
    
    private void UnloadAsset(string address)
    {
        if (loadedAssets.TryGetValue(address, out LoadedAssetInfo info))
        {
            if (info.handle.IsValid())
            {
                Addressables.Release(info.handle);
            }
            
            loadedAssets.Remove(address);
            DebugLogger.LogDebug($"에셋 언로드: {address} ({info.memorySize / 1024}KB 해제)", "MemoryManager");
        }
    }
    
    public void MarkAssetAsUsed(string address)
    {
        if (loadedAssets.TryGetValue(address, out LoadedAssetInfo info))
        {
            info.lastUsed = System.DateTime.Now;
            info.useCount++;
        }
    }
    
    public void MarkAssetAsPermanent(string address, bool permanent = true)
    {
        if (loadedAssets.TryGetValue(address, out LoadedAssetInfo info))
        {
            info.isPermanent = permanent;
            DebugLogger.LogInfo($"에셋 {address}을(를) {(permanent ? "영구" : "임시")}로 설정", "MemoryManager");
        }
    }
    
    private long EstimateAssetMemorySize(object asset)
    {
        // 에셋 타입별 메모리 사용량 추정
        if (asset is Texture2D texture)
        {
            return UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(texture);
        }
        else if (asset is AudioClip audioClip)
        {
            return UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(audioClip);
        }
        else if (asset is Mesh mesh)
        {
            return UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(mesh);
        }
        else
        {
            // 기본 추정값
            return 1024; // 1KB
        }
    }
}
```

***

## 베스트 프랙티스

* **점진적 로딩**: 필요한 에셋만 적시에 로딩
* **스마트 캐싱**: 사용 패턴을 고려한 캐시 관리
* **메모리 모니터링**: 지속적인 메모리 사용량 모니터링
* **오프라인 대응**: 네트워크 상태에 따른 적절한 대체 방안
* **AppsInToss 통합**: 플랫폼 기능을 활용한 최적화

이 가이드를 통해 Unity WebGL에서 Addressable 시스템을 효과적으로 활용하여 성능과 사용자 경험을 크게 향상시킬 수 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/android-profiling.md
---
# Android 프로파일링

앱인토스 Unity 게임을 Android 환경에서 효과적으로 프로파일링하여 성능 최적화 포인트를 찾는 방법을 제공합니다.

***

## 1. Android 프로파일링 도구

### Unity Profiler with Android

```c#
public class AndroidProfilerManager : MonoBehaviour
{
    [Header("Android 프로파일링 설정")]
    public bool enableDeepProfiling = true;
    public bool enableGPUProfiling = true;
    public ProfilerArea[] activeAreas = {
        ProfilerArea.CPU,
        ProfilerArea.GPU,
        ProfilerArea.Rendering,
        ProfilerArea.Memory,
        ProfilerArea.Audio,
        ProfilerArea.NetworkOperations
    };
    
    void Start()
    {
        #if UNITY_ANDROID && !UNITY_EDITOR
        SetupAndroidProfiling();
        #endif
    }
    
    void SetupAndroidProfiling()
    {
        // Android 전용 프로파일링 설정
        Profiler.enableBinaryLog = true;
        Profiler.logFile = Application.persistentDataPath + "/profiler.raw";
        
        if (enableDeepProfiling)
        {
            Profiler.deepProfiling = true;
        }
        
        StartCoroutine(MonitorAndroidPerformance());
    }
    
    IEnumerator MonitorAndroidPerformance()
    {
        while (true)
        {
            // Android 특화 성능 데이터 수집
            var perfData = CollectAndroidPerformanceData();
            
            // 앱인토스 분석 시스템에 전송
            AppsInToss.SendPerformanceData(perfData);
            
            yield return new WaitForSeconds(1f);
        }
    }
    
    AndroidPerformanceData CollectAndroidPerformanceData()
    {
        return new AndroidPerformanceData
        {
            cpuUsage = Profiler.GetTotalAllocatedMemory(false),
            gpuUsage = SystemInfo.graphicsMemorySize,
            thermalState = GetAndroidThermalState(),
            batteryLevel = SystemInfo.batteryLevel,
            networkType = Application.internetReachability.ToString()
        };
    }
    
    string GetAndroidThermalState()
    {
        // Android 열 상태 확인
        return AppsInToss.GetAndroidThermalState();
    }
}

[System.Serializable]
public class AndroidPerformanceData
{
    public long cpuUsage;
    public int gpuUsage;
    public string thermalState;
    public float batteryLevel;
    public string networkType;
}
```

***

## 2. 메모리 프로파일링

### Android 메모리 분석

```c#
public class AndroidMemoryProfiler : MonoBehaviour
{
    [Header("메모리 프로파일링")]
    public bool enableMemoryProfiling = true;
    public float profilingInterval = 5f;
    
    private Dictionary<string, long> memorySnapshots = new Dictionary<string, long>();
    
    void Start()
    {
        if (enableMemoryProfiling)
        {
            InvokeRepeating(nameof(TakeMemorySnapshot), profilingInterval, profilingInterval);
        }
    }
    
    void TakeMemorySnapshot()
    {
        var snapshot = new AndroidMemorySnapshot
        {
            timestamp = System.DateTime.Now,
            totalAllocated = Profiler.GetTotalAllocatedMemory(false),
            totalReserved = Profiler.GetTotalReservedMemory(false),
            totalUnused = Profiler.GetTotalUnusedReservedMemory(false),
            monoUsed = Profiler.GetMonoUsedSize(),
            monoHeap = Profiler.GetMonoHeapSize(),
            tempAllocator = Profiler.GetTempAllocatorSize(),
            gfxDriver = Profiler.GetAllocatedMemoryForGraphicsDriver(),
            nativeMemory = GetNativeMemoryUsage()
        };
        
        AnalyzeMemorySnapshot(snapshot);
        LogMemorySnapshot(snapshot);
    }
    
    long GetNativeMemoryUsage()
    {
        // Android 네이티브 메모리 사용량 확인
        return Profiler.GetTotalAllocatedMemory(false) - Profiler.GetMonoUsedSize();
    }
    
    void AnalyzeMemorySnapshot(AndroidMemorySnapshot snapshot)
    {
        // 메모리 누수 감지
        if (memorySnapshots.ContainsKey("previous"))
        {
            long previousTotal = memorySnapshots["previous"];
            long currentTotal = snapshot.totalAllocated;
            long growth = currentTotal - previousTotal;
            
            if (growth > 10 * 1024 * 1024) // 10MB 이상 증가
            {
                Debug.LogWarning($"Android 메모리 급증 감지: +{growth / (1024*1024)}MB");
                AppsInToss.ReportMemoryLeak(growth);
            }
        }
        
        memorySnapshots["previous"] = snapshot.totalAllocated;
    }
}

[System.Serializable]
public class AndroidMemorySnapshot
{
    public System.DateTime timestamp;
    public long totalAllocated;
    public long totalReserved;
    public long totalUnused;
    public long monoUsed;
    public long monoHeap;
    public long tempAllocator;
    public long gfxDriver;
    public long nativeMemory;
}
```

Android 환경에서의 정확한 프로파일링을 통해 앱인토스 게임의 성능 병목점을 식별하고 최적화하세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/development/client/android.md'
description: >-
  React Native 앱인토스 개발을 위한 Android 환경 설정 가이드입니다. Android Studio, SDK
  Command-line Tools 설치 및 환경 변수 설정 방법을 확인하세요.
---

# Android 환경설정

React Native 개발을 위해 **Android 개발 환경 설정 방법**을 안내해요.

## 1. Android Studio 설치

React Native를 Android 환경에서 실행하려면 **Android SDK**와 [`adb`(Android Debug Bridge)](https://developer.android.com/tools/adb?hl=ko#howadbworks)가 필요해요.\
먼저, 아래 링크를 통해 Android Studio를 설치하세요.

* [Android Studio 설치 링크](https://developer.android.com/studio?hl=ko)

## 2. Android SDK Command-line Tools 설치

Android SDK Command-line Tools를 설치하려면 다음 단계를 따라 진행하세요.

1. Android Studio를 열고 상단 메뉴에서 **\[Android Studio] > \[Settings]** 를 클릭하세요.
2. 왼쪽 메뉴에서 **\[Languages & Frameworks] > \[Android SDK]** 를 선택하세요.
3. **\[SDK Tools]** 탭에서 "Android SDK Command-line Tools"를 체크하고 "OK" 버튼을 눌러 설치하세요.
   ![이미지](/assets/setup-android-adb.COp4Yig6.png)

## 3. 환경 변수 설정

`adb`를 사용하려면 환경 변수를 설정해야 해요.

### macOS

사용 중인 셸의 초기화 스크립트(`.zshrc` 또는 `.bashrc`)에 다음 내용을 추가하세요.

```bash
export ANDROID_HOME=~/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools
```

### Windows

#### 1. 실행 프롬프트 열기

`Windows` + `R` 키를 눌러 실행 창을 열고 `SystemPropertiesAdvanced`를 입력한 뒤 **Enter** 키를 눌러주세요.

![실행 프롬프트](/assets/setup-android-windows-1.DOFYC1J8.jpg)

#### 2. 환경 변수 메뉴로 진입하기

\[시스템 속성] 창에서 \[고급] 탭을 선택하고, 하단의 \[환경 변수] 버튼을 눌러주세요.

![환경 변수](/assets/setup-android-windows-2.BQ_BCp0c.png)

#### 3. 사용자 변수에서 `Path` 편집

사용자 변수 섹션에서 `Path` 변수를 선택한 뒤 \[편집] 버튼을 눌러주세요.

:::info
만약 `Path` 변수가 없다면, \[새로 만들기] 버튼을 눌러 새 변수를 생성하고 이름을 `Path`로 설정하면 돼요.
:::

![Path 환경 변수](/assets/setup-android-windows-3.DxEAc_wY.png)

#### 4. Android SDK 경로 추가하기

편집 창에서 \[새로 만들기] 버튼을 눌러 다음 경로를 추가하세요.

`C:\Users\{사용자명}\AppData\Local\Android\sdk\platform-tools`

여기서 `{사용자명}`은 현재 Windows 사용자 계정 이름으로 바꿔 입력해야 해요.

![환경 변수 추가](/assets/setup-android-windows-4.n8Ve7E9m.png)

***

### 설정 확인

환경 변수가 정상적으로 등록되었는지 아래 명령어로 확인하세요.

```shell
adb version
# Android Debug Bridge version 1.0.41
# Version 33.0.2-8557947
# Installed as /Users/heecheol.kim/Library/Android/sdk/platform-tools/adb
```

정상적으로 버전이 출력되면 `adb` 설정이 완료되었어요.\
자세한 내용은 [Android 공식 문서 - 환경 변수](https://developer.android.com/tools/variables?hl=ko#android_home)를 참고하세요.

## 4. 기기 연결

PC와 Android 기기를 연결하는 방법을 안내해요. 이 문서를 따라 [adb(Android Debug Bridge)](https://developer.android.com/tools/adb?hl=ko#howadbworks)를 사용해서 기기와 통신할 수 있어요.

### 개발자 옵션 활성화

::: tip

기기 제조사에 따라 개발자 옵션을 활성화하는 방법이 다를 수 있어요. 사용 중인 기기의 제조사별 가이드는 인터넷 검색으로 확인하세요.

:::

**갤럭시 기기 기준**

1. \[설정] 앱 열기
2. \[휴대전화 정보] > \[소프트웨어 정보] 메뉴로 이동
3. \[빌드 번호] 항목을 빠르게 여러번 탭하기

자세한 방법은 [삼성 지원 홈페이지](https://www.samsung.com/uk/support/mobile-devices/how-do-i-turn-on-the-developer-options-menu-on-my-samsung-galaxy-device)에서 확인할 수 있어요.

### USB 디버깅 활성화

개발자 옵션이 활성화되었다면, 이제 USB 디버깅 옵션을 활성화해 주세요.

1. \[설정] 앱을 열어주세요.
2. \[개발자 옵션] 메뉴로 이동해주세요.
3. \[USB 디버깅] 항목을 활성화 해주세요.

### PC와 기기 연결하기

USB 케이블로 PC와 기기를 연결한 뒤, 다음 명령어를 실행해 기기가 정상적으로 연결되었는지 확인해 주세요.

```shell
adb devices
# * daemon not running; starting now at tcp:5037
# * daemon started successfully
# List of devices attached
# R3CTA0BMCPK	device
```

제대로 연결되었다면 **"List of devices attached"** 아래에 기기의 디바이스 아이디가 표시돼요. 다음 예시에서는 `R3CTA0BMCPK`가 디바이스 아이디예요.

::: details 디바이스 아이디가 표시되지 않는다면?
다음 사항들을 확인해주세요.

* **USB 디버깅 활성화하기**: Android 기기에서 \[설정] > \[개발자 옵션] > \[USB 디버깅]이 활성화 되어있는지 확인해요.
* **ADB 서버 재시작하기**: `adb kill-server` 명령어를 실행한 후 다시 `adb devices` 명령어로 연결 상태를 확인해요.

:::

## 5. 에뮬레이터 설정

Android 에뮬레이터는 실제 기기처럼 동작하며, React Native 화면을 테스트할 수 있는 유용한 도구예요.

> ⚠️ 디버깅과 QA는 가능한 **실제 기기**에서 진행하는 것을 권장합니다.

### 1. Android Studio에서 에뮬레이터 추가 설정 화면 열기

Android Studio를 실행한 후 오른쪽 메뉴에서 \[Virtual Device Manager] > \[+ 버튼]을 순서대로 클릭해 주세요.

![안드로이드 스튜디오로 에뮬레이터 설정 화면 열기](/assets/setup-android-6.DIpNjcDJ.png)

### 2. 에뮬레이터 추가하기

테스트 환경은 실제 사용자 환경과 비슷하게 설정하는 게 좋아요. 아래는 "갤럭시 S23"과 비슷한 에뮬레이터를 만드는 방법이에요.

:::tip 갤럭시 S23 사양

* 디스플레이: 6.1인치
* 운영체제: API 33부터 지원 (예시에서는 API 35 사용)

:::

![안드로이드 스튜디오로 에뮬레이터 설정](/assets/setup-android-7.DHo2POTo.gif)

위 영상처럼 \[Pixel 8a] > \[VanilaIceCream (API 35)] > \[AVD Name 설정] 순으로 진행하면 에뮬레이터 설정을 완료할 수 있어요.

## 6. 에뮬레이터 실행

추가한 에뮬레이터 목록을 확인할 수 있고, 원하는 에뮬레이터를 바로 실행할 수 있어요.

### 1. Android Studio에서 에뮬레이터 목록 확인하기

Android Studio를 실행한 후 오른쪽 메뉴에서 \[Virtual Device Manager]를 클릭해 주세요.

### 2. 에뮬레이터 실행하기

실행하고자 하는 에뮬레이터를 확인한 뒤, 재생 버튼을 눌러 실행할 수 있어요.

![에뮬레이터 실행하기](/assets/setup-android-exec-emulator.BbVjs52o.png)

## 7. 앱인토스 샌드박스 앱 설치

실제 기기와 에뮬레이터에서 같은 APK 파일을 사용해요.

* [앱인토스 샌드박스 앱 다운로드](/development/test/sandbox)

### 1. Android Studio에서 설치

Android Stuido를 활용해서 실기기에 앱인토스 샌드박스 앱을 설치할 수 있어요.

1. Android Studio에서 오른쪽 메뉴의 \[Device Manager]에 연결된 기기가 표시되는지 확인해요.

![안드로이드 실행가능한 기기 목록 보여주기](/assets/setup-android-2.DXcNnBuo.png)

2. 연결된 기기의 오른쪽에 있는 \[Start Mirroring] 버튼을 클릭하면 기기 화면을 Android Studio에 표시할 수 있어요.

![안드로이드 실행가능한 기기 목록 보여주기](/assets/setup-android-3.5PFEsGIn.gif)

3. 다운로드한 앱인토스 샌드박스 앱 APK 파일을 끌고 와서 기기에 설치할 수 있어요.

![안드로이드 스튜디오로 앱 설치](/assets/setup-android-4.WhqxGp5g.gif)

### 2. `adb` 명령어로 설치

1. 터미널에서 APK 파일이 있는 폴더로 이동해요.
2. 아래 명령어로 APK 파일을 설치해요.

```shell
adb install -r -t {파일이름}
```

예를 들어, 파일 이름이 `apssintoss-debug.apk`라면 아래 명령어를 사용해요.

```shell
adb install -r -t apssintoss-debug.apk
```

![adb로 앱인토스 샌드박스 앱 다운로드](/assets/setup-android-5.DrtXEOR5.gif)

---

---
url: 'https://developers-apps-in-toss.toss.im/development/integration-process.md'
description: >-
  앱인토스 API 사용을 위한 mTLS 기반 서버 간 통신 설정 가이드입니다. 인증서 발급, 통신 구조, 언어별 API 요청 예제를
  확인하세요.
---

# API 사용하기

앱인토스 API를 사용하려면 **mTLS 기반의 서버 간(Server-to-Server) 통신 설정이 반드시 필요해요.**\
mTLS 인증서는 파트너사 서버와 앱인토스 서버 간 통신을 **암호화**하고 **쌍방 신원을 상호 검증**하는 데 사용됩니다.

::: tip 아래 기능은 반드시 mTLS 인증서를 통한 통신이 필요해요

* [토스 로그인](/login/intro.md)
* [토스 페이](/tosspay/intro.md)
* [인앱 결제](/iap/intro.md)
* [기능성 푸시, 알림](/push/intro.md)
* [프로모션(토스 포인트)](/promotion/intro.md)
  :::

## 통신 구조

앱인토스 API는 파트너사 서버에서 앱인토스 서버로 요청을 전송하고,\
앱인토스 서버가 토스 서버에 연동 요청을 전달하는 구조로 동작해요.

![](/assets/appintoss_process_2.DkmHrB4Z.png)

![](../resources/prepare/appintoss_process.png)

## mTLS 인증서 발급 방법

서버용 mTLS 인증서는 **콘솔에서 직접 발급**할 수 있어요.

### 1. 앱 선택하기

앱인토스 콘솔에 접속해 인증서를 발급받을 앱을 선택하세요.\
왼쪽 메뉴에서 **mTLS 인증서** 탭을 클릭한 뒤, **+ 발급받기** 버튼을 눌러 발급을 진행해요.

![](/assets/mtls.C_guSa2X.png)

### 2. 인증서 다운로드 및 보관

mTLS 인증서가 발급되면 **인증서 파일과 키 파일**을 다운로드할 수 있어요.

::: tip 보관 시 주의하세요

* 인증서와 키 파일은 유출되지 않도록 **안전한 위치에 보관**하세요.
* 인증서가 **만료되기 전에 반드시 재발급**해 주세요.

:::

![](/assets/mtls-2._GxAfDcf.png)

콘솔에서 발급된 인증서는 아래와 같이 확인할 수 있어요.

![](/assets/mtls-3.CkETJCHm.png)

인증서는 일반적으로 하나만 사용하지만, **무중단 교체**를 위해 **두 개 이상 등록해 둘 수도 있어요.**\
콘솔에서는 이를 위해 **다중 인증서 관리 기능을** 제공해요.

## API 요청 시 인증서 설정

앱인토스 서버에 요청하려면, 발급받은 **인증서/키 파일**을 서버 애플리케이션에 등록해야 해요.

아래는 주요 언어별 mTLS 요청 예제예요.\
환경에 맞게 경로, 알고리즘, TLS 버전 등을 조정하세요.

::: details Kotlin 예제

```kotlin
import java.security.KeyStore
import java.security.cert.X509Certificate
import java.security.KeyFactory
import java.security.spec.PKCS8EncodedKeySpec
import java.io.FileReader
import java.io.ByteArrayInputStream
import java.util.Base64
import javax.net.ssl.*

class TLSClient {
    fun createSSLContext(certPath: String, keyPath: String): SSLContext {
        val cert = loadCertificate(certPath)
        val key = loadPrivateKey(keyPath)

        val keyStore = KeyStore.getInstance(KeyStore.getDefaultType())
        keyStore.load(null, null)
        keyStore.setCertificateEntry("client-cert", cert)
        keyStore.setKeyEntry("client-key", key, "".toCharArray(), arrayOf(cert))

        val kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm())
        kmf.init(keyStore, "".toCharArray())

        return SSLContext.getInstance("TLS").apply {
            init(kmf.keyManagers, null, null)
        }
    }

    private fun loadCertificate(path: String): X509Certificate {
        val content = FileReader(path).readText()
            .replace("-----BEGIN CERTIFICATE-----", "")
            .replace("-----END CERTIFICATE-----", "")
            .replace("\\s".toRegex(), "")
        val bytes = Base64.getDecoder().decode(content)
        return CertificateFactory.getInstance("X.509")
            .generateCertificate(ByteArrayInputStream(bytes)) as X509Certificate
    }

    private fun loadPrivateKey(path: String): java.security.PrivateKey {
        val content = FileReader(path).readText()
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replace("\\s".toRegex(), "")
        val bytes = Base64.getDecoder().decode(content)
        val spec = PKCS8EncodedKeySpec(bytes)
        return KeyFactory.getInstance("RSA").generatePrivate(spec)
    }

    fun makeRequest(url: String, context: SSLContext): String {
        val connection = (URL(url).openConnection() as HttpsURLConnection).apply {
            sslSocketFactory = context.socketFactory
            requestMethod = "GET"
            connectTimeout = 5000
            readTimeout = 5000
        }

        return connection.inputStream.bufferedReader().use { it.readText() }.also {
            connection.disconnect()
        }
    }
}

fun main() {
    val client = TLSClient()
    val context = client.createSSLContext("/path/to/client-cert.pem", "/path/to/client-key.pem")
    val response = client.makeRequest("https://apps-in-toss-api.toss.im/endpoint", context)
    println(response)
}
```

:::

::: details Python 예제

```python
import requests

class TLSClient:
    def __init__(self, cert_path, key_path):
        self.cert_path = cert_path
        self.key_path = key_path

    def make_request(self, url):
        response = requests.get(
            url,
            cert=(self.cert_path, self.key_path),
            headers={'Content-Type': 'application/json'}
        )
        return response.text

if __name__ == '__main__':
    client = TLSClient(
        cert_path='/path/to/client-cert.pem',
        key_path='/path/to/client-key.pem'
    )
    result = client.make_request('https://apps-in-toss-api.toss.im/endpoint')
    print(result)
```

:::

::: details JavaScript(Node.js) 예제

```js
const https = require('https');
const fs = require('fs');

const options = {
  cert: fs.readFileSync('/path/to/client-cert.pem'),
  key: fs.readFileSync('/path/to/client-key.pem'),
  rejectUnauthorized: true,
};

const req = https.request(
  'https://apps-in-toss-api.toss.im/endpoint',
  { method: 'GET', ...options },
  (res) => {
    let data = '';
    res.on('data', (chunk) => (data += chunk));
    res.on('end', () => {
      console.log('Response:', data);
    });
  }
);

req.on('error', (e) => console.error(e));
req.end();
```

:::

::: details C# 예제

```c#
using System;
using System.Net.Http;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        var handler = new HttpClientHandler();
        handler.ClientCertificates.Add(
            new X509Certificate2("/path/to/client-cert.pem")
        );

        using var client = new HttpClient(handler);
        var response = await client.GetAsync("https://apps-in-toss-api.toss.im/endpoint");
        string body = await response.Content.ReadAsStringAsync();
        Console.WriteLine(body);
    }
}
```

:::

::: details C++ 예제(libcurl 사용)

```cpp
#include <curl/curl.h>
#include <iostream>
#include <string>

size_t WriteCallback(void* contents, size_t size, size_t nmemb, std::string* userp) {
    userp->append((char*)contents, size * nmemb);
    return size * nmemb;
}

int main() {
    CURL* curl = curl_easy_init();
    if (curl) {
        std::string response;
        curl_easy_setopt(curl, CURLOPT_URL, "https://apps-in-toss-api.toss.im/endpoint");
        curl_easy_setopt(curl, CURLOPT_SSLCERT, "/path/to/client-cert.pem");
        curl_easy_setopt(curl, CURLOPT_SSLKEY, "/path/to/client-key.pem");
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);

        CURLcode res = curl_easy_perform(curl);
        if (res == CURLE_OK) {
            std::cout << "Response: " << response << std::endl;
        } else {
            std::cerr << "Error: " << curl_easy_strerror(res) << std::endl;
        }

        curl_easy_cleanup(curl);
    }

    return 0;
}
```

:::

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: "`ERR_NETWORK` 에러가 발생해요.",
a: \`mTLS 미적용 상태에서 API를 호출하면 발생해요.

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/common_asset.md'
description: '토스 디자인 시스템(TDS)의 Asset 컴포넌트 가이드입니다. 아이콘, 이미지, 비디오 등 미디어 에셋 표시 방법을 확인하세요.'
---

# {{ $frontmatter.title }}

`Asset` 컴포넌트는 아이콘, 이미지, 비디오, Lottie 애니메이션 등 다양한 미디어 에셋을 일관된 방식으로 표시할 수 있게 해주는 컴포넌트예요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/Asset/check-first/)

![common-asset](/assets/Thumbnail-Asset.DOBg_PK6.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/assetbundle.md
---
# AssetBundle 가이드

앱인토스 Unity 게임에서 AssetBundle을 효율적으로 사용하여 앱 크기를 최소화하고 동적 콘텐츠 로딩을 구현하는 방법을 제공해요.

## 1. 앱인토스 AssetBundle 전략

### AssetBundle 구성 전략

```
📦 앱인토스 AssetBundle 구조
├── Core Bundle (필수 번들) - 10MB 이내
│   ├── 게임 엔진 핵심 에셋
│   ├── 앱인토스 SDK 리소스
│   ├── 기본 UI 시스템
│   └── 토스 브랜딩 에셋
├── Feature Bundles (기능별 번들) - 각 5MB 이내
│   ├── 게임플레이 번들
│   ├── 사운드 번들
│   ├── 이펙트 번들
│   └── 토스페이 연동 번들
├── Level Bundles (레벨별 번들) - 각 3MB 이내
│   ├── 스테이지 1-10
│   ├── 스테이지 11-20
│   └── 보스 레벨
└── Seasonal Bundles (시즌 컨텐츠) - 각 2MB 이내
    ├── 이벤트 에셋
    ├── 한정 스킨
    └── 특별 아이템
```

### AssetBundle 관리자 구현

```c#
using UnityEngine;
using System.Collections;
using System.Collections.Generic;
using System.IO;

public class AppsInTossAssetBundleManager : MonoBehaviour
{
    public static AppsInTossAssetBundleManager Instance { get; private set; }
    
    [System.Serializable]
    public class BundleConfig
    {
        public string bundleName;
        public BundlePriority priority;
        public string cdnUrl;
        public long bundleSize;
        public string version;
        public bool persistent = true;
        public List<string> dependencies = new List<string>();
    }
    
    public enum BundlePriority
    {
        Critical = 0,    // 앱 시작 전 필수 로딩
        High = 1,        // 게임 시작 시 로딩
        Medium = 2,      // 백그라운드 로딩
        Low = 3,         // 필요시 로딩
        Toss = 4         // 앱인토스 특화 번들
    }
    
    [Header("번들 설정")]
    public BundleConfig[] bundleConfigs;
    
    [Header("앱인토스 CDN 설정")]
    public string tossCdnBaseUrl = "https://cdn.appintoss.com/bundles/";
    public bool enableTossCaching = true;
    public long maxCacheSizeMB = 100;
    
    // 내부 관리
    private Dictionary<string, AssetBundle> loadedBundles = new Dictionary<string, AssetBundle>();
    private Dictionary<string, BundleConfig> bundleConfigMap = new Dictionary<string, BundleConfig>();
    private HashSet<string> downloadingBundles = new HashSet<string>();
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeBundleManager();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeBundleManager()
    {
        // 번들 설정 맵 생성
        foreach (var config in bundleConfigs)
        {
            bundleConfigMap[config.bundleName] = config;
        }
        
        // 로컬 캐시 정리
        StartCoroutine(CleanupOldBundles());
        
        // Critical 우선순위 번들 자동 로딩
        StartCoroutine(LoadCriticalBundles());
    }
    
    IEnumerator LoadCriticalBundles()
    {
        var criticalBundles = System.Array.FindAll(bundleConfigs, 
            b => b.priority == BundlePriority.Critical || b.priority == BundlePriority.Toss);
        
        foreach (var bundle in criticalBundles)
        {
            yield return StartCoroutine(LoadBundleCoroutine(bundle.bundleName));
        }
        
        Debug.Log("Critical AssetBundle 로딩 완료");
    }
    
    public void LoadBundleAsync(string bundleName, System.Action<bool> onComplete = null)
    {
        StartCoroutine(LoadBundleAsyncCoroutine(bundleName, onComplete));
    }
    
    IEnumerator LoadBundleAsyncCoroutine(string bundleName, System.Action<bool> onComplete)
    {
        yield return StartCoroutine(LoadBundleCoroutine(bundleName));
        onComplete?.Invoke(IsBundleLoaded(bundleName));
    }
    
    IEnumerator LoadBundleCoroutine(string bundleName)
    {
        if (IsBundleLoaded(bundleName))
        {
            yield break;
        }
        
        if (downloadingBundles.Contains(bundleName))
        {
            yield return new WaitUntil(() => !downloadingBundles.Contains(bundleName));
            yield break;
        }
        
        downloadingBundles.Add(bundleName);
        
        var config = bundleConfigMap[bundleName];
        
        // 의존성 번들 먼저 로딩
        foreach (var dependency in config.dependencies)
        {
            if (!IsBundleLoaded(dependency))
            {
                yield return StartCoroutine(LoadBundleCoroutine(dependency));
            }
        }
        
        // 번들 다운로드 또는 로컬 로딩
        string bundlePath = GetBundlePath(bundleName);
        AssetBundle bundle = null;
        
        if (File.Exists(bundlePath))
        {
            // 로컬에서 로딩
            var bundleLoadRequest = AssetBundle.LoadFromFileAsync(bundlePath);
            yield return bundleLoadRequest;
            bundle = bundleLoadRequest.assetBundle;
        }
        else
        {
            // CDN에서 다운로드
            yield return StartCoroutine(DownloadBundle(config));
            
            if (File.Exists(bundlePath))
            {
                var bundleLoadRequest = AssetBundle.LoadFromFileAsync(bundlePath);
                yield return bundleLoadRequest;
                bundle = bundleLoadRequest.assetBundle;
            }
        }
        
        if (bundle != null)
        {
            loadedBundles[bundleName] = bundle;
            Debug.Log($"AssetBundle 로딩 성공: {bundleName}");
            
            // 앱인토스 분석에 번들 로딩 성공 전송
            SendBundleAnalytics(bundleName, true, 0);
        }
        else
        {
            Debug.LogError($"AssetBundle 로딩 실패: {bundleName}");
            SendBundleAnalytics(bundleName, false, 0);
        }
        
        downloadingBundles.Remove(bundleName);
    }
    
    IEnumerator DownloadBundle(BundleConfig config)
    {
        string downloadUrl = tossCdnBaseUrl + config.bundleName;
        string savePath = GetBundlePath(config.bundleName);
        
        Debug.Log($"AssetBundle 다운로드 시작: {config.bundleName}");
        float startTime = Time.realtimeSinceStartup;
        
        using (var www = new WWW(downloadUrl))
        {
            yield return www;
            
            if (string.IsNullOrEmpty(www.error))
            {
                // 파일 저장
                Directory.CreateDirectory(Path.GetDirectoryName(savePath));
                File.WriteAllBytes(savePath, www.bytes);
                
                float downloadTime = Time.realtimeSinceStartup - startTime;
                Debug.Log($"AssetBundle 다운로드 완료: {config.bundleName} ({downloadTime:F2}초)");
                
                SendBundleAnalytics(config.bundleName, true, downloadTime);
            }
            else
            {
                Debug.LogError($"AssetBundle 다운로드 실패: {config.bundleName} - {www.error}");
                SendBundleAnalytics(config.bundleName, false, 0);
            }
        }
    }
    
    string GetBundlePath(string bundleName)
    {
        return Path.Combine(Application.persistentDataPath, "Bundles", bundleName);
    }
    
    // 에셋 로딩 API
    public void LoadAssetFromBundle<T>(string bundleName, string assetName, 
        System.Action<T> onComplete, System.Action<string> onError = null) where T : UnityEngine.Object
    {
        StartCoroutine(LoadAssetFromBundleCoroutine<T>(bundleName, assetName, onComplete, onError));
    }
    
    IEnumerator LoadAssetFromBundleCoroutine<T>(string bundleName, string assetName,
        System.Action<T> onComplete, System.Action<string> onError) where T : UnityEngine.Object
    {
        // 번들이 로딩되어 있지 않으면 먼저 로딩
        if (!IsBundleLoaded(bundleName))
        {
            yield return StartCoroutine(LoadBundleCoroutine(bundleName));
        }
        
        if (!IsBundleLoaded(bundleName))
        {
            onError?.Invoke($"번들 로딩 실패: {bundleName}");
            yield break;
        }
        
        var bundle = loadedBundles[bundleName];
        var assetRequest = bundle.LoadAssetAsync<T>(assetName);
        
        yield return assetRequest;
        
        if (assetRequest.asset != null)
        {
            onComplete?.Invoke(assetRequest.asset as T);
        }
        else
        {
            onError?.Invoke($"에셋을 찾을 수 없습니다: {assetName}");
        }
    }
    
    // 토스 특화 번들 로딩
    public void LoadTossBundles(System.Action onComplete = null)
    {
        StartCoroutine(LoadTossBundlesCoroutine(onComplete));
    }
    
    IEnumerator LoadTossBundlesCoroutine(System.Action onComplete)
    {
        var tossBundles = System.Array.FindAll(bundleConfigs, 
            b => b.priority == BundlePriority.Toss);
        
        foreach (var bundle in tossBundles)
        {
            yield return StartCoroutine(LoadBundleCoroutine(bundle.bundleName));
        }
        
        Debug.Log("토스 특화 번들 로딩 완료");
        onComplete?.Invoke();
    }
    
    // 번들 언로딩
    public void UnloadBundle(string bundleName, bool unloadAllLoadedObjects = false)
    {
        if (loadedBundles.ContainsKey(bundleName))
        {
            loadedBundles[bundleName].Unload(unloadAllLoadedObjects);
            loadedBundles.Remove(bundleName);
            
            Debug.Log($"AssetBundle 언로드: {bundleName}");
        }
    }
    
    // 캐시 관리
    IEnumerator CleanupOldBundles()
    {
        string bundleDir = Path.Combine(Application.persistentDataPath, "Bundles");
        
        if (!Directory.Exists(bundleDir))
        {
            yield break;
        }
        
        var files = Directory.GetFiles(bundleDir);
        long totalSize = 0;
        
        foreach (var file in files)
        {
            totalSize += new FileInfo(file).Length;
        }
        
        long maxCacheSize = maxCacheSizeMB * 1024 * 1024;
        
        if (totalSize > maxCacheSize)
        {
            Debug.Log($"번들 캐시 정리 시작: {totalSize / (1024 * 1024)}MB > {maxCacheSizeMB}MB");
            
            // 최근 접근 시간 기준으로 정렬
            var fileInfos = new List<FileInfo>();
            foreach (var file in files)
            {
                fileInfos.Add(new FileInfo(file));
            }
            
            fileInfos.Sort((a, b) => a.LastAccessTime.CompareTo(b.LastAccessTime));
            
            // 오래된 파일부터 삭제
            foreach (var fileInfo in fileInfos)
            {
                if (totalSize <= maxCacheSize) break;
                
                totalSize -= fileInfo.Length;
                File.Delete(fileInfo.FullName);
                
                Debug.Log($"오래된 번들 삭제: {fileInfo.Name}");
            }
        }
    }
    
    void SendBundleAnalytics(string bundleName, bool success, float downloadTime)
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"bundle_name", bundleName},
            {"success", success},
            {"download_time", downloadTime},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("assetbundle_loading", analyticsData);
    }
    
    // 공개 API
    public bool IsBundleLoaded(string bundleName)
    {
        return loadedBundles.ContainsKey(bundleName);
    }
    
    public string[] GetLoadedBundleNames()
    {
        var names = new string[loadedBundles.Count];
        loadedBundles.Keys.CopyTo(names, 0);
        return names;
    }
    
    public long GetTotalCacheSize()
    {
        string bundleDir = Path.Combine(Application.persistentDataPath, "Bundles");
        
        if (!Directory.Exists(bundleDir))
        {
            return 0;
        }
        
        long totalSize = 0;
        var files = Directory.GetFiles(bundleDir);
        
        foreach (var file in files)
        {
            totalSize += new FileInfo(file).Length;
        }
        
        return totalSize;
    }
}
```

***

## 2. 번들 빌드 최적화

### 자동화된 번들 빌드 시스템

```c#
#if UNITY_EDITOR
using UnityEditor;
using UnityEngine;
using System.IO;
using System.Collections.Generic;

public class AppsInTossBundleBuilder
{
    [MenuItem("AppsInToss/Build All Bundles")]
    public static void BuildAllBundles()
    {
        BuildBundlesForTarget(BuildTarget.Android);
        BuildBundlesForTarget(BuildTarget.iOS);
        
        Debug.Log("앱인토스 번들 빌드 완료");
    }
    
    static void BuildBundlesForTarget(BuildTarget target)
    {
        string outputPath = Path.Combine("AssetBundles", target.ToString());
        
        if (!Directory.Exists(outputPath))
        {
            Directory.CreateDirectory(outputPath);
        }
        
        // 앱인토스 최적화 설정
        var buildOptions = BuildAssetBundleOptions.ChunkBasedCompression | 
                          BuildAssetBundleOptions.StrictMode |
                          BuildAssetBundleOptions.DeterministicAssetBundle;
        
        // 번들 빌드 실행
        var manifest = BuildPipeline.BuildAssetBundles(
            outputPath, 
            buildOptions, 
            target
        );
        
        if (manifest != null)
        {
            OptimizeBundlesForAppsInToss(outputPath, manifest);
            GenerateBundleConfig(outputPath, manifest);
        }
    }
    
    static void OptimizeBundlesForAppsInToss(string outputPath, AssetBundleManifest manifest)
    {
        var allBundles = manifest.GetAllAssetBundles();
        
        foreach (var bundleName in allBundles)
        {
            string bundlePath = Path.Combine(outputPath, bundleName);
            var fileInfo = new FileInfo(bundlePath);
            
            // 번들 크기 체크 (앱인토스 권장 크기)
            long sizeMB = fileInfo.Length / (1024 * 1024);
            
            if (sizeMB > 10) // 10MB 초과
            {
                Debug.LogWarning($"번들 크기가 권장 크기를 초과합니다: {bundleName} ({sizeMB}MB)");
            }
            
            // 압축률 정보 출력
            Debug.Log($"번들 정보: {bundleName} - {sizeMB}MB");
        }
    }
    
    static void GenerateBundleConfig(string outputPath, AssetBundleManifest manifest)
    {
        var config = new AppsInTossBundleConfig();
        var allBundles = manifest.GetAllAssetBundles();
        
        foreach (var bundleName in allBundles)
        {
            string bundlePath = Path.Combine(outputPath, bundleName);
            var fileInfo = new FileInfo(bundlePath);
            
            var bundleInfo = new AppsInTossBundleConfig.BundleInfo
            {
                name = bundleName,
                size = fileInfo.Length,
                hash = manifest.GetAssetBundleHash(bundleName).ToString(),
                dependencies = manifest.GetAllDependencies(bundleName)
            };
            
            config.bundles.Add(bundleInfo);
        }
        
        // JSON으로 설정 파일 저장
        string configPath = Path.Combine(outputPath, "bundle_config.json");
        string json = JsonUtility.ToJson(config, true);
        File.WriteAllText(configPath, json);
        
        Debug.Log($"번들 설정 파일 생성: {configPath}");
    }
}

[System.Serializable]
public class AppsInTossBundleConfig
{
    [System.Serializable]
    public class BundleInfo
    {
        public string name;
        public long size;
        public string hash;
        public string[] dependencies;
    }
    
    public List<BundleInfo> bundles = new List<BundleInfo>();
    public string version = "1.0.0";
    public string buildTime;
    
    public AppsInTossBundleConfig()
    {
        buildTime = System.DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss");
    }
}
#endif
```

AssetBundle을 사용해 앱 크기를 줄이고, 필요한 콘텐츠만 동적으로 업데이트하세요.
앱인토스 환경에서는 번들 크기와 다운로드 속도에 특히 주의해야 해요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/autostreaming.md
---
# AutoStreaming 가이드

## 1. AutoStreaming 개요

### AutoStreaming이란?

```
🚀 AutoStreaming 개념
├── 즉시 시작 (Instant Play) - 0-5초 내 게임 시작
├── 백그라운드 로딩 - 플레이 중 추가 콘텐츠 다운로드
├── 우선순위 기반 로딩 - 중요한 에셋 우선 로딩
└── 적응형 품질 - 네트워크 상태에 따른 품질 조절
```

### AutoStreaming 아키텍처

```c#
using UnityEngine;
using System.Collections;
using System.Collections.Generic;
using System.IO;

public class AppsInTossAutoStreaming : MonoBehaviour
{
    public static AppsInTossAutoStreaming Instance { get; private set; }
    
    [System.Serializable]
    public class StreamingConfig
    {
        public string assetName;
        public StreamingPriority priority;
        public float sizeMB;
        public string[] dependencies;
        public bool essential = false; // 게임 진행에 필수 여부
        public int loadOrder = 0;
        public float timeoutSeconds = 30f;
    }
    
    public enum StreamingPriority
    {
        Immediate = 0,     // 즉시 로딩 (게임 시작 전 필수)
        High = 1,          // 게임 시작 후 바로 로딩
        Medium = 2,        // 사용자가 해당 영역에 접근하기 전 로딩
        Low = 3,           // 필요할 때만 로딩
        Preload = 4        // 여유가 있을 때 미리 로딩
    }
    
    [Header("스트리밍 설정")]
    public StreamingConfig[] streamingAssets;
    public float initialLoadThresholdMB = 2f; // 즉시 시작을 위한 초기 로딩 임계값
    public bool enableAdaptiveQuality = true;
    public bool enablePreloadInIdle = true;
    
    [Header("네트워크 설정")]
    public string baseUrl = "https://cdn.appintoss.com/streaming/";
    public int maxConcurrentDownloads = 3;
    public float networkTimeoutSeconds = 15f;
    
    // 내부 상태
    private Dictionary<string, StreamingConfig> configMap = new Dictionary<string, StreamingConfig>();
    private HashSet<string> loadedAssets = new HashSet<string>();
    private HashSet<string> downloadingAssets = new HashSet<string>();
    private Queue<StreamingConfig> downloadQueue = new Queue<StreamingConfig>();
    private bool isInitialLoadComplete = false;
    private int activeDownloads = 0;
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeAutoStreaming();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeAutoStreaming()
    {
        // 설정 맵 생성
        foreach (var config in streamingAssets)
        {
            configMap[config.assetName] = config;
        }
        
        // 네트워크 상태 모니터링 시작
        StartCoroutine(MonitorNetworkStatus());
        
        // 즉시 로딩 가능한 최소한의 에셋 로딩
        StartCoroutine(LoadImmediateAssets());
    }
    
    IEnumerator LoadImmediateAssets()
    {
        Debug.Log("AutoStreaming 즉시 로딩 시작");
        float startTime = Time.realtimeSinceStartup;
        
        // Immediate 우선순위 에셋들을 크기 기준으로 정렬
        var immediateAssets = System.Array.FindAll(streamingAssets, 
            a => a.priority == StreamingPriority.Immediate);
        System.Array.Sort(immediateAssets, (a, b) => a.sizeMB.CompareTo(b.sizeMB));
        
        float loadedSizeMB = 0f;
        
        foreach (var asset in immediateAssets)
        {
            if (loadedSizeMB >= initialLoadThresholdMB && !asset.essential)
            {
                // 임계값 도달, 필수 에셋이 아니면 나중에 로딩
                QueueAssetForDownload(asset);
                continue;
            }
            
            yield return StartCoroutine(LoadAssetCoroutine(asset));
            loadedSizeMB += asset.sizeMB;
        }
        
        float loadTime = Time.realtimeSinceStartup - startTime;
        Debug.Log($"즉시 로딩 완료: {loadTime:F2}초, {loadedSizeMB:F1}MB 로딩됨");
        
        isInitialLoadComplete = true;
        
        // 게임 시작 가능 신호 전송
        SendGameReadySignal(loadTime, loadedSizeMB);
        
        // 백그라운드에서 나머지 에셋 로딩 시작
        StartCoroutine(BackgroundStreamingProcess());
    }
    
    IEnumerator LoadAssetCoroutine(StreamingConfig config)
    {
        if (loadedAssets.Contains(config.assetName))
        {
            yield break;
        }
        
        downloadingAssets.Add(config.assetName);
        
        // 의존성 에셋 먼저 로딩
        foreach (var dependency in config.dependencies)
        {
            if (!loadedAssets.Contains(dependency))
            {
                var dependencyConfig = configMap[dependency];
                yield return StartCoroutine(LoadAssetCoroutine(dependencyConfig));
            }
        }
        
        // 에셋 다운로드
        yield return StartCoroutine(DownloadAsset(config));
        
        downloadingAssets.Remove(config.assetName);
        loadedAssets.Add(config.assetName);
    }
    
    IEnumerator DownloadAsset(StreamingConfig config)
    {
        string assetUrl = baseUrl + config.assetName;
        string cachePath = GetAssetCachePath(config.assetName);
        
        Debug.Log($"에셋 스트리밍 시작: {config.assetName} ({config.sizeMB:F1}MB)");
        float startTime = Time.realtimeSinceStartup;
        
        // 로컬 캐시 확인
        if (File.Exists(cachePath))
        {
            yield return StartCoroutine(LoadFromCache(config, cachePath));
            yield break;
        }
        
        // 네트워크 다운로드
        using (var www = new WWW(assetUrl))
        {
            float timeoutTime = Time.realtimeSinceStartup + config.timeoutSeconds;
            
            while (!www.isDone && Time.realtimeSinceStartup < timeoutTime)
            {
                // 진행률 업데이트
                UpdateDownloadProgress(config.assetName, www.progress);
                yield return null;
            }
            
            if (www.isDone && string.IsNullOrEmpty(www.error))
            {
                // 캐시에 저장
                Directory.CreateDirectory(Path.GetDirectoryName(cachePath));
                File.WriteAllBytes(cachePath, www.bytes);
                
                float downloadTime = Time.realtimeSinceStartup - startTime;
                Debug.Log($"스트리밍 완료: {config.assetName} ({downloadTime:F2}초)");
                
                SendStreamingAnalytics(config.assetName, true, downloadTime, config.sizeMB);
            }
            else
            {
                Debug.LogError($"스트리밍 실패: {config.assetName} - {www.error}");
                SendStreamingAnalytics(config.assetName, false, 0, config.sizeMB);
            }
        }
    }
    
    IEnumerator LoadFromCache(StreamingConfig config, string cachePath)
    {
        Debug.Log($"캐시에서 로딩: {config.assetName}");
        
        // 캐시 파일 검증
        var fileInfo = new FileInfo(cachePath);
        float expectedSizeMB = config.sizeMB;
        float actualSizeMB = fileInfo.Length / (1024f * 1024f);
        
        if (Mathf.Abs(actualSizeMB - expectedSizeMB) > 0.1f)
        {
            Debug.LogWarning($"캐시 파일 크기 불일치: {config.assetName} (예상: {expectedSizeMB:F1}MB, 실제: {actualSizeMB:F1}MB)");
            File.Delete(cachePath);
            
            // 다시 다운로드
            yield return StartCoroutine(DownloadAsset(config));
            yield break;
        }
        
        yield return null; // 1프레임 대기
        Debug.Log($"캐시 로딩 완료: {config.assetName}");
    }
    
    IEnumerator BackgroundStreamingProcess()
    {
        while (true)
        {
            // 큐에서 다음 에셋 처리
            if (downloadQueue.Count > 0 && activeDownloads < maxConcurrentDownloads)
            {
                var nextAsset = downloadQueue.Dequeue();
                StartCoroutine(BackgroundDownload(nextAsset));
            }
            
            // Idle 상태에서 preload 에셋 로딩
            if (enablePreloadInIdle && IsPlayerIdle() && activeDownloads == 0)
            {
                var preloadAssets = System.Array.FindAll(streamingAssets,
                    a => a.priority == StreamingPriority.Preload && !loadedAssets.Contains(a.assetName));
                
                if (preloadAssets.Length > 0)
                {
                    var nextPreload = preloadAssets[0];
                    QueueAssetForDownload(nextPreload);
                }
            }
            
            yield return new WaitForSeconds(1f);
        }
    }
    
    IEnumerator BackgroundDownload(StreamingConfig config)
    {
        activeDownloads++;
        yield return StartCoroutine(LoadAssetCoroutine(config));
        activeDownloads--;
    }
    
    void QueueAssetForDownload(StreamingConfig config)
    {
        if (!downloadingAssets.Contains(config.assetName) && 
            !loadedAssets.Contains(config.assetName))
        {
            downloadQueue.Enqueue(config);
        }
    }
    
    IEnumerator MonitorNetworkStatus()
    {
        while (true)
        {
            // 네트워크 상태 확인
            var networkReachability = Application.internetReachability;
            
            if (enableAdaptiveQuality)
            {
                AdaptQualityBasedOnNetwork(networkReachability);
            }
            
            yield return new WaitForSeconds(5f);
        }
    }
    
    void AdaptQualityBasedOnNetwork(NetworkReachability reachability)
    {
        switch (reachability)
        {
            case NetworkReachability.ReachableViaCarrierDataNetwork:
                // 모바일 데이터: 압축률 높이고 다운로드 제한
                maxConcurrentDownloads = 1;
                networkTimeoutSeconds = 30f;
                break;
                
            case NetworkReachability.ReachableViaLocalAreaNetwork:
                // WiFi: 최적 성능
                maxConcurrentDownloads = 3;
                networkTimeoutSeconds = 15f;
                break;
                
            case NetworkReachability.NotReachable:
                // 오프라인: 캐시된 에셋만 사용
                maxConcurrentDownloads = 0;
                break;
        }
    }
    
    string GetAssetCachePath(string assetName)
    {
        return Path.Combine(Application.persistentDataPath, "StreamingCache", assetName);
    }
    
    bool IsPlayerIdle()
    {
        // 플레이어가 유휴 상태인지 확인하는 로직
        // 예: 일정 시간 동안 입력이 없었는지, 메뉴 화면에 있는지 등
        return Time.realtimeSinceStartup - Time.time > 10f;
    }
    
    void UpdateDownloadProgress(string assetName, float progress)
    {
        // UI에 다운로드 진행률 업데이트
        var progressData = new Dictionary<string, object>
        {
            {"asset_name", assetName},
            {"progress", progress}
        };
        
        // 이벤트 시스템으로 UI에 알림
        AppsInToss.SendEvent("streaming_progress", progressData);
    }
    
    void SendGameReadySignal(float loadTime, float loadedSizeMB)
    {
        var readyData = new Dictionary<string, object>
        {
            {"load_time", loadTime},
            {"loaded_size_mb", loadedSizeMB},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendEvent("game_ready", readyData);
        Debug.Log($"게임 시작 준비 완료! 로딩 시간: {loadTime:F2}초");
    }
    
    void SendStreamingAnalytics(string assetName, bool success, float downloadTime, float sizeMB)
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"asset_name", assetName},
            {"success", success},
            {"download_time", downloadTime},
            {"size_mb", sizeMB},
            {"network_type", Application.internetReachability.ToString()},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("streaming_performance", analyticsData);
    }
    
    // 공개 API
    public bool IsAssetLoaded(string assetName)
    {
        return loadedAssets.Contains(assetName);
    }
    
    public bool IsInitialLoadComplete()
    {
        return isInitialLoadComplete;
    }
    
    public void RequestAssetLoad(string assetName, StreamingPriority priority = StreamingPriority.High)
    {
        if (configMap.ContainsKey(assetName) && !IsAssetLoaded(assetName))
        {
            var config = configMap[assetName];
            config.priority = priority; // 우선순위 업데이트
            
            QueueAssetForDownload(config);
        }
    }
    
    public float GetLoadingProgress()
    {
        if (streamingAssets.Length == 0) return 1f;
        
        float totalAssets = streamingAssets.Length;
        float loadedCount = loadedAssets.Count;
        
        return loadedCount / totalAssets;
    }
    
    public string[] GetLoadedAssets()
    {
        var result = new string[loadedAssets.Count];
        loadedAssets.CopyTo(result);
        return result;
    }
    
    public long GetCacheSize()
    {
        string cacheDir = Path.Combine(Application.persistentDataPath, "StreamingCache");
        
        if (!Directory.Exists(cacheDir))
        {
            return 0;
        }
        
        long totalSize = 0;
        var files = Directory.GetFiles(cacheDir, "*", SearchOption.AllDirectories);
        
        foreach (var file in files)
        {
            totalSize += new FileInfo(file).Length;
        }
        
        return totalSize;
    }
    
    public void ClearCache()
    {
        string cacheDir = Path.Combine(Application.persistentDataPath, "StreamingCache");
        
        if (Directory.Exists(cacheDir))
        {
            Directory.Delete(cacheDir, true);
            Debug.Log("스트리밍 캐시 정리 완료");
        }
        
        loadedAssets.Clear();
    }
}
```

***

## 2. 최적화 전략

### 에셋 우선순위 설정

```c#
[System.Serializable]
public class AssetPriorityManager
{
    [Header("게임 시작 필수 에셋")]
    public string[] immediateAssets = {
        "core_ui",           // 핵심 UI 시스템
        "player_controller", // 플레이어 조작
        "first_level_mesh",  // 첫 번째 레벨 메시
        "essential_sounds"   // 핵심 사운드
    };
    
    [Header("조기 로딩 권장 에셋")]
    public string[] highPriorityAssets = {
        "level_backgrounds", // 레벨 배경
        "enemy_sprites",     // 적 스프라이트
        "effect_particles",  // 이펙트 파티클
        "ui_animations"      // UI 애니메이션
    };
    
    [Header("지연 로딩 가능 에셋")]
    public string[] lowPriorityAssets = {
        "cutscene_videos",   // 컷신 비디오
        "boss_models",       // 보스 모델
        "extra_music",       // 추가 음악
        "optional_effects"   // 선택적 이펙트
    };
    
    public StreamingPriority GetAssetPriority(string assetName)
    {
        if (System.Array.Exists(immediateAssets, a => a == assetName))
            return StreamingPriority.Immediate;
        else if (System.Array.Exists(highPriorityAssets, a => a == assetName))
            return StreamingPriority.High;
        else if (System.Array.Exists(lowPriorityAssets, a => a == assetName))
            return StreamingPriority.Low;
        else
            return StreamingPriority.Medium;
    }
}
```

### 스트리밍 UI 시스템

```c#
using UnityEngine;
using UnityEngine.UI;

public class StreamingProgressUI : MonoBehaviour
{
    [Header("UI 컴포넌트")]
    public Slider progressBar;
    public Text progressText;
    public Text statusText;
    public Button playButton;
    public GameObject loadingPanel;
    
    [Header("설정")]
    public float minimumDisplayTime = 2f; // 최소 로딩 화면 표시 시간
    public bool hideProgressAfterReady = true;
    
    private float displayStartTime;
    private bool isGameReady = false;
    
    void Start()
    {
        displayStartTime = Time.realtimeSinceStartup;
        
        // 이벤트 리스너 등록
        AppsInToss.OnEvent += HandleAppsInTossEvent;
        
        // 초기 UI 설정
        playButton.interactable = false;
        loadingPanel.SetActive(true);
        
        UpdateProgressDisplay();
    }
    
    void Update()
    {
        UpdateProgressDisplay();
        
        // 최소 표시 시간 후 게임 시작 가능
        if (isGameReady && 
            Time.realtimeSinceStartup - displayStartTime >= minimumDisplayTime)
        {
            if (hideProgressAfterReady)
            {
                loadingPanel.SetActive(false);
            }
            
            playButton.interactable = true;
        }
    }
    
    void UpdateProgressDisplay()
    {
        if (AppsInTossAutoStreaming.Instance == null) return;
        
        float progress = AppsInTossAutoStreaming.Instance.GetLoadingProgress();
        bool initialComplete = AppsInTossAutoStreaming.Instance.IsInitialLoadComplete();
        
        // 진행률 업데이트
        progressBar.value = progress;
        progressText.text = $"{progress * 100f:F0}%";
        
        // 상태 텍스트 업데이트
        if (initialComplete)
        {
            statusText.text = "게임 시작 준비 완료!";
            statusText.color = Color.green;
        }
        else
        {
            statusText.text = "에셋 로딩 중...";
            statusText.color = Color.white;
        }
    }
    
    void HandleAppsInTossEvent(string eventName, Dictionary<string, object> data)
    {
        switch (eventName)
        {
            case "game_ready":
                isGameReady = true;
                break;
                
            case "streaming_progress":
                string assetName = data["asset_name"] as string;
                float assetProgress = (float)data["progress"];
                
                // 개별 에셋 진행률 표시
                statusText.text = $"로딩 중: {assetName} ({assetProgress * 100f:F0}%)";
                break;
        }
    }
    
    public void OnPlayButtonClicked()
    {
        if (isGameReady)
        {
            // 게임 씬 로드
            UnityEngine.SceneManagement.SceneManager.LoadScene("GameScene");
        }
    }
    
    void OnDestroy()
    {
        AppsInToss.OnEvent -= HandleAppsInTossEvent;
    }
}
```

***

## 3. 성능 모니터링

### 스트리밍 성능 추적

```c#
public class StreamingPerformanceMonitor : MonoBehaviour
{
    [System.Serializable]
    public class PerformanceMetrics
    {
        public float initialLoadTime;
        public float totalDownloadSize;
        public int failedDownloads;
        public float averageDownloadSpeed;
        public string networkType;
        public Dictionary<string, float> assetLoadTimes;
        
        public PerformanceMetrics()
        {
            assetLoadTimes = new Dictionary<string, float>();
        }
    }
    
    public PerformanceMetrics metrics = new PerformanceMetrics();
    
    void Start()
    {
        AppsInToss.OnAnalytics += HandleAnalyticsEvent;
    }
    
    void HandleAnalyticsEvent(string eventName, Dictionary<string, object> data)
    {
        if (eventName == "streaming_performance")
        {
            string assetName = data["asset_name"] as string;
            bool success = (bool)data["success"];
            float downloadTime = (float)data["download_time"];
            float sizeMB = (float)data["size_mb"];
            
            if (success)
            {
                metrics.assetLoadTimes[assetName] = downloadTime;
                metrics.totalDownloadSize += sizeMB;
                
                if (downloadTime > 0)
                {
                    float speedMBps = sizeMB / downloadTime;
                    UpdateAverageSpeed(speedMBps);
                }
            }
            else
            {
                metrics.failedDownloads++;
            }
            
            // 성능 보고서 생성
            if (metrics.assetLoadTimes.Count % 10 == 0)
            {
                GeneratePerformanceReport();
            }
        }
    }
    
    void UpdateAverageSpeed(float newSpeed)
    {
        if (metrics.averageDownloadSpeed == 0)
        {
            metrics.averageDownloadSpeed = newSpeed;
        }
        else
        {
            metrics.averageDownloadSpeed = (metrics.averageDownloadSpeed + newSpeed) / 2f;
        }
    }
    
    void GeneratePerformanceReport()
    {
        var report = new Dictionary<string, object>
        {
            {"total_assets_loaded", metrics.assetLoadTimes.Count},
            {"total_download_size_mb", metrics.totalDownloadSize},
            {"failed_downloads", metrics.failedDownloads},
            {"average_download_speed_mbps", metrics.averageDownloadSpeed},
            {"network_type", Application.internetReachability.ToString()},
            {"device_model", SystemInfo.deviceModel},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("streaming_report", report);
        Debug.Log($"스트리밍 성능 보고서 전송: {metrics.assetLoadTimes.Count}개 에셋 로딩 완료");
    }
    
    void OnDestroy()
    {
        AppsInToss.OnAnalytics -= HandleAnalyticsEvent;
    }
}
```

***

## 4. 에디터 도구

### AutoStreaming 설정 도구

```c#
#if UNITY_EDITOR
using UnityEngine;
using UnityEditor;
using System.IO;
using System.Collections.Generic;

public class AutoStreamingConfigWindow : EditorWindow
{
    private AppsInTossAutoStreaming streamingComponent;
    private Vector2 scrollPosition;
    private bool showAnalytics = true;
    
    [MenuItem("AppsInToss/AutoStreaming 설정")]
    public static void ShowWindow()
    {
        GetWindow<AutoStreamingConfigWindow>("AutoStreaming 설정");
    }
    
    void OnGUI()
    {
        GUILayout.Label("AutoStreaming 설정", EditorStyles.boldLabel);
        
        // 컴포넌트 참조
        streamingComponent = EditorGUILayout.ObjectField(
            "AutoStreaming 컴포넌트", 
            streamingComponent, 
            typeof(AppsInTossAutoStreaming), 
            true
        ) as AppsInTossAutoStreaming;
        
        if (streamingComponent == null)
        {
            EditorGUILayout.HelpBox("AutoStreaming 컴포넌트를 선택해주세요.", MessageType.Warning);
            return;
        }
        
        EditorGUILayout.Space();
        
        // 에셋 분석 결과 표시
        if (GUILayout.Button("프로젝트 에셋 분석"))
        {
            AnalyzeProjectAssets();
        }
        
        EditorGUILayout.Space();
        
        // 스트리밍 설정 표시
        scrollPosition = EditorGUILayout.BeginScrollView(scrollPosition);
        
        SerializedObject so = new SerializedObject(streamingComponent);
        SerializedProperty streamingAssets = so.FindProperty("streamingAssets");
        
        EditorGUILayout.PropertyField(streamingAssets, true);
        
        so.ApplyModifiedProperties();
        
        EditorGUILayout.EndScrollView();
        
        EditorGUILayout.Space();
        
        // 유틸리티 버튼들
        EditorGUILayout.BeginHorizontal();
        
        if (GUILayout.Button("설정 검증"))
        {
            ValidateStreamingConfig();
        }
        
        if (GUILayout.Button("최적화 제안"))
        {
            SuggestOptimizations();
        }
        
        if (GUILayout.Button("테스트 빌드"))
        {
            BuildStreamingTest();
        }
        
        EditorGUILayout.EndHorizontal();
    }
    
    void AnalyzeProjectAssets()
    {
        var assetGuids = AssetDatabase.FindAssets("t:Object");
        var assetSizes = new Dictionary<string, float>();
        
        foreach (var guid in assetGuids)
        {
            string assetPath = AssetDatabase.GUIDToAssetPath(guid);
            var fileInfo = new FileInfo(assetPath);
            
            if (fileInfo.Exists)
            {
                float sizeMB = fileInfo.Length / (1024f * 1024f);
                assetSizes[Path.GetFileName(assetPath)] = sizeMB;
            }
        }
        
        // 크기별 정렬
        var sortedAssets = new List<KeyValuePair<string, float>>(assetSizes);
        sortedAssets.Sort((a, b) => b.Value.CompareTo(a.Value));
        
        Debug.Log("=== 프로젝트 에셋 크기 분석 ===");
        for (int i = 0; i < Mathf.Min(10, sortedAssets.Count); i++)
        {
            var asset = sortedAssets[i];
            Debug.Log($"{i + 1}. {asset.Key}: {asset.Value:F2}MB");
        }
        
        float totalSizeMB = 0f;
        foreach (var size in assetSizes.Values)
        {
            totalSizeMB += size;
        }
        
        Debug.Log($"총 에셋 크기: {totalSizeMB:F2}MB");
        Debug.Log($"권장 즉시 로딩 크기: {streamingComponent.initialLoadThresholdMB}MB");
    }
    
    void ValidateStreamingConfig()
    {
        var issues = new List<string>();
        
        // 설정 검증
        if (streamingComponent.streamingAssets.Length == 0)
        {
            issues.Add("스트리밍 에셋이 설정되지 않았습니다.");
        }
        
        // 즉시 로딩 에셋 크기 체크
        float immediateSizeMB = 0f;
        foreach (var asset in streamingComponent.streamingAssets)
        {
            if (asset.priority == AppsInTossAutoStreaming.StreamingPriority.Immediate)
            {
                immediateSizeMB += asset.sizeMB;
            }
        }
        
        if (immediateSizeMB > streamingComponent.initialLoadThresholdMB)
        {
            issues.Add($"즉시 로딩 에셋 크기가 임계값을 초과합니다: {immediateSizeMB:F1}MB > {streamingComponent.initialLoadThresholdMB}MB");
        }
        
        // 결과 표시
        if (issues.Count == 0)
        {
            EditorUtility.DisplayDialog("검증 완료", "AutoStreaming 설정이 올바릅니다.", "확인");
        }
        else
        {
            string message = "다음 문제들을 해결해주세요:\n\n" + string.Join("\n", issues);
            EditorUtility.DisplayDialog("검증 실패", message, "확인");
        }
    }
    
    void SuggestOptimizations()
    {
        var suggestions = new List<string>();
        
        // 큰 에셋 우선순위 확인
        foreach (var asset in streamingComponent.streamingAssets)
        {
            if (asset.sizeMB > 5f && asset.priority == AppsInTossAutoStreaming.StreamingPriority.Immediate)
            {
                suggestions.Add($"큰 에셋 '{asset.assetName}' ({asset.sizeMB:F1}MB)의 우선순위를 낮추는 것을 고려해보세요.");
            }
        }
        
        // 의존성 체크
        var dependencyCount = new Dictionary<string, int>();
        foreach (var asset in streamingComponent.streamingAssets)
        {
            foreach (var dep in asset.dependencies)
            {
                dependencyCount[dep] = dependencyCount.ContainsKey(dep) ? dependencyCount[dep] + 1 : 1;
            }
        }
        
        foreach (var kvp in dependencyCount)
        {
            if (kvp.Value > 3)
            {
                suggestions.Add($"에셋 '{kvp.Key}'이 {kvp.Value}개의 다른 에셋에서 참조됩니다. 공통 번들로 분리를 고려해보세요.");
            }
        }
        
        // 결과 표시
        if (suggestions.Count == 0)
        {
            EditorUtility.DisplayDialog("최적화 분석", "현재 설정이 최적화되어 있습니다.", "확인");
        }
        else
        {
            string message = "다음 최적화를 고려해보세요:\n\n" + string.Join("\n\n", suggestions);
            EditorUtility.DisplayDialog("최적화 제안", message, "확인");
        }
    }
    
    void BuildStreamingTest()
    {
        if (EditorUtility.DisplayDialog("테스트 빌드", "AutoStreaming 테스트 빌드를 시작하시겠습니까?", "시작", "취소"))
        {
            // 테스트용 빌드 설정
            BuildPlayerOptions buildOptions = new BuildPlayerOptions();
            buildOptions.scenes = new[] { EditorBuildSettings.scenes[0].path };
            buildOptions.locationPathName = "Builds/StreamingTest/StreamingTest";
            buildOptions.target = BuildTarget.WebGL;
            buildOptions.options = BuildOptions.Development;
            
            BuildPipeline.BuildPlayer(buildOptions);
            
            Debug.Log("AutoStreaming 테스트 빌드 완료");
        }
    }
}
#endif
```

AutoStreaming을 통해 사용자가 즉시 게임을 시작할 수 있도록 하되, 백그라운드에서 추가 콘텐츠를 스마트하게 로딩하여 끊김 없는 게임 경험을 제공하세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/badge.md'
description: 토스 디자인 시스템(TDS)의 Badge 컴포넌트 가이드입니다. 항목의 상태를 강조하는 배지 컴포넌트 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

`Badge` 컴포넌트는 항목의 상태를 빠르게 인식할 수 있도록 강조하는 데 사용돼요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/badge/)

![Badge](/assets/Thumbnail-Badge.Bwxw5iGR.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/BlurView.md
---

# BlurView

`BlurView` 컴포넌트는 **iOS에서만 지원되는 블러(Blur) 효과**를 제공해요.\
배경을 흐리게 처리하거나, [Vibrancy 효과](https://developer.apple.com/documentation/uikit/uivibrancyeffect?language=objc)를 적용해 콘텐츠를 더 생동감 있게 표현할 수 있어요.\
Android에서는 블러 효과가 적용되지 않고 기본 [`View`](https://reactnative.dev/docs/0.72/view)가 렌더링돼요.

## 시그니처

```typescript
function BlurView({ blurType, blurAmount, reducedTransparencyFallbackColor, vibrancyEffect, ...viewProps }: BlurViewProps): import("react/jsx-runtime").JSX.Element;
```

### 파라미터

### 반환 값

::: tip 유의할 점
`BlurView`는 iOS 5.126.0 이상에서만 블러 효과를 지원해요.\
Android에서는 기본 `View`가 렌더링되며, 블러 효과가 적용되지 않아요.
:::

## 예제

### BlurView로 텍스트 블러 처리하기

아래 예시는 텍스트 위에 `BlurView`를 겹쳐 배경을 흐리게 처리하는 방법을 보여줘요.

```tsx
import { View, Text, StyleSheet } from 'react-native';
import { BlurView } from '@granite-js/react-native';

function BlurViewExample() {
 return (
   <View style={styles.container}>
     <Text style={styles.absolute}>Blurred Text</Text>
     <BlurView style={styles.absolute} blurType="light" blurAmount={1} />
     <Text>Non Blurred Text</Text>
   </View>
 );
}

const styles = StyleSheet.create({
 container: {
   justifyContent: 'center',
   alignItems: 'center',
   width: '100%',
   height: 300,
 },
 absolute: {
   position: 'absolute',
   top: 0,
   left: 0,
   bottom: 0,
   right: 0,
 },
});
```

## 참고

* [iOS Vibrancy Effect Documentation](https://developer.apple.com/documentation/uikit/uivibrancyeffect)
* [Zeddios Blog 설명](https://zeddios.tistory.com/1140)

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/border.md'
description: 토스 디자인 시스템(TDS)의 Border 가이드입니다. 테두리 스타일 및 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

`Border` 컴포넌트는 요소 주위에 선을 그려서 요소 간의 구분을 명확히 하고 싶을 때 사용해요. UI 요소 간의 명확한 구분과 계층 구조를 표현할 수 있어요.
주로 리스트나 섹션을 구분하는 데 사용돼요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/border/)

![Border](/assets/Thumbnail-Border.BVe6_eEm.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/bottomcta.md'
description: 토스 디자인 시스템(TDS)의 BottomCTA 컴포넌트 가이드입니다. 화면 하단 고정 CTA 버튼 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

`BottomCTA` 컴포넌트는 사용자 인터페이스(UI)에 표시되는 호출 버튼(Call-to-Action)이에요.\
주로 사용자가 특정 작업을 완료할 수 있도록 도와줄 때 사용하죠. 보통 페이지 하단에 항상 고정되어 있어서, 긴 스크롤이나 키보드 입력 시에도 손쉽게 접근할 수 있어요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/BottomCTA/check-first/)

![Bottom CTA](/assets/Thumbnail-BottomCTA.gzD9Z0yf.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/button.md'
description: 토스 디자인 시스템(TDS)의 Button 컴포넌트 가이드입니다. 사용자 액션을 트리거하는 버튼 컴포넌트 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

`Button` 컴포넌트는 사용자가 어떤 액션을 트리거하거나 이벤트를 실행할 때 사용해요. 버튼은 기본적인 UI 요소로, 폼 제출, 다이얼로그 열기, 작업 취소, 삭제와 같은 다양한 액션을 처리하는 데 사용해요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/button/)

![button](/assets/Thumbnail-Button_1.CiJvgV68.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/ColorPreference.md
---

# ColorPreference

현재 기기의 색상 모드를 나타내는 타입이에요. 라이트모드, 다크모드를 나타내는 문자열이에요

## 시그니처

```typescript
type ColorPreference = 'light' | 'dark';
```

### 타입 정의

#### `ColorPreference`

*`'light' | 'dark'`*

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/코어/ColorPreference.md
description: Bedrock 프레임워크 레퍼런스 문서입니다.
---

# ColorPreference

현재 기기의 색상 모드를 나타내는 타입이에요. 라이트모드, 다크모드를 나타내는 문자열이에요

## 시그니처

```typescript
type ColorPreference = 'light' | 'dark';
```

### 타입 정의

#### `ColorPreference`

*`'light' | 'dark'`*

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/emscripten-glx.md
---
# EmscriptenGLX 렌더링 모드 가이드

앱인토스 Unity 게임에서 EmscriptenGLX를 활용한 고성능 렌더링 최적화 방법을 다뤄요.

***

## 1. EmscriptenGLX 개요

### WebGL 렌더링 최적화

EmscriptenGLX는 Unity WebGL 빌드에서 더 효율적인 그래픽 렌더링을 제공하는 고급 렌더링 모드입니다.

```
🎮 EmscriptenGLX 렌더링 파이프라인
├── GPU 직접 접근 최적화
├── 배치 렌더링 향상
├── 셰이더 컴파일 최적화
├── 텍스처 스트리밍 개선
└── 메모리 관리 효율화
```

### EmscriptenGLX 매니저

```c#
using UnityEngine;
using UnityEngine.Rendering;

public class EmscriptenGLXManager : MonoBehaviour
{
    public static EmscriptenGLXManager Instance { get; private set; }
    
    [Header("GLX 렌더링 설정")]
    public bool enableGLXOptimizations = true;
    public RenderQuality renderQuality = RenderQuality.Balanced;
    public bool enableBatchedRendering = true;
    public bool enableShaderOptimization = true;
    
    [Header("성능 설정")]
    public int targetFrameRate = 60;
    public bool adaptiveQuality = true;
    public float performanceThreshold = 0.9f;
    
    public enum RenderQuality
    {
        Performance,  // 성능 우선
        Balanced,     // 균형
        Quality       // 품질 우선
    }
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeGLX();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeGLX()
    {
#if UNITY_WEBGL && !UNITY_EDITOR
        // WebGL 전용 GLX 초기화
        EnableGLXOptimizations();
        ConfigureRenderingSettings();
        StartCoroutine(MonitorPerformance());
#endif
        
        Debug.Log("EmscriptenGLX 초기화 완료");
    }
    
    void EnableGLXOptimizations()
    {
        if (!enableGLXOptimizations) return;
        
        // GLX 최적화 활성화
        GL.Clear(true, true, Color.black);
        
        // 배치 렌더링 설정
        if (enableBatchedRendering)
        {
            ConfigureBatchedRendering();
        }
        
        // 셰이더 최적화
        if (enableShaderOptimization)
        {
            OptimizeShaders();
        }
    }
    
    void ConfigureBatchedRendering()
    {
        // Unity WebGL 배치 렌더링 설정
        QualitySettings.maxQueuedFrames = 2;
        
        // 렌더링 배치 크기 최적화
        Application.targetFrameRate = targetFrameRate;
    }
    
    void OptimizeShaders()
    {
        // 셰이더 컴파일 최적화
        Shader.WarmupAllShaders();
        
        // 사용되지 않는 셰이더 제거
        CleanupUnusedShaders();
    }
    
    void CleanupUnusedShaders()
    {
        var allShaders = Resources.FindObjectsOfTypeAll<Shader>();
        foreach (var shader in allShaders)
        {
            if (!IsShaderInUse(shader))
            {
                // 사용되지 않는 셰이더는 메모리에서 해제
                Resources.UnloadAsset(shader);
            }
        }
    }
    
    bool IsShaderInUse(Shader shader)
    {
        var materials = Resources.FindObjectsOfTypeAll<Material>();
        foreach (var material in materials)
        {
            if (material.shader == shader)
            {
                return true;
            }
        }
        return false;
    }
}
```

EmscriptenGLX를 통해 WebGL 환경에서 더 나은 그래픽 성능을 얻을 수 있어요.\
특히 복잡한 3D 렌더링이나 많은 오브젝트를 다룰 때 성능 향상이 두드러져요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/사진/FetchAlbumPhotosPermissionError.md
---

# FetchAlbumPhotosPermissionError

사진첩 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof FetchAlbumPhotosPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class FetchAlbumPhotosPermissionError extends PermissionError {
    constructor();
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/연락처/FetchContactsPermissionError.md
---

# FetchContactsPermissionError

연락처 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof FetchContactsPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class FetchContactsPermissionError extends PermissionError {
    constructor();
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/firebase/intro.md'
---
# Firebase 연동하기

앱인토스(미니앱) Webview 환경에서 Firebase를 연동하는 방법을 안내해요.\
이 문서는 **Vite(React + TypeScript)** 기반 프로젝트를 기준으로 작성되었어요.

***

## 개요

Firebase는 인증, 데이터베이스, 파일 저장 등 다양한 기능을 제공하는 서비스예요.\
앱인토스 WebView 환경에서도 동일하게 사용할 수 있지만, **보안 설정과 환경 변수 관리**가 중요해요.

***

## 1. 준비하기

* Firebase 콘솔 계정 ([console.firebase.google.com](https://console.firebase.google.com))
* Vite(React + TypeScript)로 만든 프로젝트
* Node.js, npm (또는 yarn, pnpm)

## 2. Firebase 프로젝트 만들기

1. Firebase 콘솔에서 **프로젝트 생성**을 눌러 새 프로젝트를 만들어요.
2. 프로젝트 설정 → **앱 추가** → **웹(\</>)** 을 선택해요.
3. 앱 닉네임을 입력하고 등록하면, 아래처럼 구성 정보(firebaseConfig)가 표시돼요.

```js
const firebaseConfig = {
  apiKey: '...',
  authDomain: '...',
  databaseURL: '...',
  projectId: '...',
  storageBucket: '...',
  messagingSenderId: '...',
  appId: '...',
  measurementId: '...'
}
```

## 3. 환경 변수 설정하기

Firebase 구성 정보는 보안을 위해 Vite 환경 변수로 관리하는 걸 권장해요.

프로젝트 루트에 `.env` 파일을 만들고 아래처럼 작성하세요.

```bash
VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
```

코드에서는 `import.meta.env.VITE_FIREBASE_API_KEY`처럼 불러와요.

## 4. Firebase 설치 및 초기화

최신 Firebase 모듈식 SDK(v12+) 기준으로 작성했어요.

```bash
npm install firebase
# 또는
yarn add firebase
```

`src/firebase/init.ts`

```ts
import { initializeApp, getApps } from 'firebase/app'
import { getAuth } from 'firebase/auth'
import { getFirestore } from 'firebase/firestore'
import { getStorage } from 'firebase/storage'

const firebaseConfig = {
  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
  appId: import.meta.env.VITE_FIREBASE_APP_ID,
}

const app = getApps().length ? getApps()[0] : initializeApp(firebaseConfig)

export const auth = getAuth(app)
export const db = getFirestore(app)
export const storage = getStorage(app)
```

> **참고:**
>
> * `databaseURL`은 **Realtime Database**를 사용할 때만 필요해요.
>   Firestore를 사용한다면 생략해도 괜찮아요.
> * `measurementId`는 **Firebase Analytics**(Google Analytics)를 쓸 때 필요해요.

## 5. Firestore 사용 예제

Firestore를 초기화했다면, React 컴포넌트 안에서 데이터를 읽거나 쓸 수 있어요.\
아래는 `App.tsx`에서 단일 문서를 읽고 저장하는 가장 간단한 예시예요.

```tsx
import { useState, useEffect } from 'react'
import { db } from './firebase/init'
import { doc, getDoc, setDoc } from 'firebase/firestore'

function App() {
  const [name, setName] = useState('')
  const [savedName, setSavedName] = useState('')

  // Firestore에서 데이터 읽기
  useEffect(() => {
    const fetchData = async () => {
      const ref = doc(db, 'users', 'exampleUser')
      const snap = await getDoc(ref)
      if (snap.exists()) {
        setSavedName(snap.data().name)
      }
    }
    fetchData()
  }, [])

  // Firestore에 데이터 쓰기
  const handleSave = async () => {
    const ref = doc(db, 'users', 'exampleUser')
    await setDoc(ref, { name })
    setSavedName(name)
    setName('')
  }

  return (
    <div style={{ padding: 24 }}>
      <h1>Firestore 간단 예제</h1>
      <input
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="이름 입력"
      />
      <button onClick={handleSave}>저장</button>
      <p>저장된 이름: {savedName || '(없음)'}</p>
    </div>
  )
}

export default App

```

### 동작 방식

* 데이터 읽기 (`getDoc`)
  * Firestore의 users/exampleUser 문서를 한 번만 불러와요.
  * 문서가 존재하면 snap.data()의 값을 화면에 표시해요.

* 데이터 쓰기 (`setDoc`)
  * 입력한 이름을 Firestore에 덮어써 저장해요.
  * 문서가 없으면 자동으로 새로 생성돼요.

![firestore](/assets/firestore-1.DBSmKjYU.png)

> Firestore는 단일 문서 외에도 여러 기능을 지원해요.
>
> * 실시간 구독 : `onSnapshot(doc(...))`을 사용하면 문서가 변경될 때마다 UI가 자동으로 갱신돼요.
> * 컬렉션 다루기 : `collection()`, `addDoc()`을 사용하면 여러 문서를 추가하고 불러올 수 있어요.
> * 파일 저장 : `getStorage()`로 `Storage`를 연결해 이미지나 파일을 업로드할 수 있어요.
> * 인증 연동 : `getAuth()`와 함께 사용하면 사용자별 데이터 저장이 가능해요.

## 6. 보안 체크리스트

* 민감한 정보 환경 변수로 관리하기
  * Firebase API Key, 서비스 계정 키 등은 코드에 직접 작성하지 않고 `.env`로 관리하세요.
* 환경 파일을 Git 등에 업로드하지 않기
  * `.env` 파일은 `.gitignore`에 반드시 추가하세요.
  * 키가 노출되면 Firebase 콘솔에서 즉시 재발급하고, 관련 프로젝트 권한을 점검하세요.
* Firebase 보안 규칙 설정하기
  * Firestore / Storage는 기본적으로 모든 사용자에게 공개되어 있어요.
  * 배포 전에 반드시 인증된 사용자만 접근하도록 규칙을 수정하세요.
* 출처(Origin) 제한 확인하기
  * Firebase 콘솔의 Authentication / Hosting / API Key 설정에서 허용 도메인을 제한해두세요.
  * 미니앱(WebView) 도메인만 허용하면 무단 접근을 예방할 수 있어요.

:::tip 허용 대상 도메인
https://.apps.tossmini.com : 실제 서비스 환경
https://.private-apps.tossmini.com : 콘솔 QR 테스트 환경
:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/style-utils/Flex.md
---

# Flex

`Flex`는 자식 요소를 **Flexbox 레이아웃** 기반으로 배치하는 레이아웃 컴포넌트예요.\
가로와 세로 방향 배치, 정렬, 중앙 정렬을 간편하게 구성할 수 있어요.\
또한, `Flex.Center`, `Flex.CenterVertical`, `Flex.CenterHorizontal` 컴포넌트를 제공해요.

### 시그니처

```typescript
Flex: FlexType
```

### 파라미터

### 예제 : 가로, 세로 방향으로 요소를 배치하기

```tsx
import { Flex } from '@granite-js/react-native';
import { Text } from 'react-native';

function FlexExample() {
  return (
    <>
      <Flex direction="column">
        <Text>세로로 배치해요</Text>
        <Text>1</Text>
        <Text>2</Text>
        <Text>3</Text>
      </Flex>
      <Flex direction="row">
        <Text>가로로 배치해요</Text>
        <Text>1</Text>
        <Text>2</Text>
        <Text>3</Text>
      </Flex>
    </>
  );
}
```

## 가로와 세로 모두 중앙 정렬하기 (`Flex.Center`)

`Flex.Center`는 자식 요소를 **가로와 세로 모두 중앙**에 배치하는 컴포넌트예요.\
내부적으로 `justifyContent: 'center'`, `alignItems: 'center'` 를 설정해요.

### 예제

```tsx
import { Flex } from '@granite-js/react-native';
import { Text } from 'react-native';

function FlexCenterExample() {
  return (
    <Flex.Center style={{ width: '100%', height: 100, borderWidth: 1 }}>
      <Text>정 중앙에 배치해요</Text>
    </Flex.Center>
  );
}
```

## 가로 방향으로 중앙 정렬하기 (`Flex.CenterHorizontal`)

`Flex.CenterHorizontal`은 자식 요소를 가로 방향 중앙에 배치하는 컴포넌트예요.\
`alignItems: 'center'`가 기본으로 적용돼요.

### 예제

```tsx
import { Flex } from '@granite-js/react-native';
import { Text } from 'react-native';

function FlexCenterHorizontalExample() {
  return (
    <Flex.CenterHorizontal style={{ width: '100%', height: 100, borderWidth: 1 }}>
      <Text>가로 중앙에 배치해요</Text>
    </Flex.CenterHorizontal>
  );
}
```

## 세로 방향으로 중앙 정렬하기 (`Flex.CenterVertical`)

`Flex.CenterVertical`은 자식 요소를 세로 방향 중앙에 배치하는 컴포넌트예요.\
`justifyContent: 'center'`가 기본으로 적용돼요.

### 예제

```tsx
import { Flex } from '@granite-js/react-native';
import { Text } from 'react-native';

function FlexCenterVerticalExample() {
  return (
    <Flex.CenterVertical style={{ width: '100%', height: 100, borderWidth: 1 }}>
      <Text>세로 중앙에 배치해요</Text>
    </Flex.CenterVertical>
  );
}
```

## 참고사항

* `Flex` 계열 컴포넌트는 `React Native` 의 `Flexbox` 속성을 간결하게 감싸 제공해요.
* Flex.Center 계열 컴포넌트를 사용하면 반복적인 중앙 정렬 코드를 단순화할 수 있어요.
* `direction`, `align`, `justify` 속성으로 세밀한 레이아웃 조정도 가능해요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/클립보드/GetClipboardTextPermissionError.md
---

# GetClipboardTextPermissionError

클립보드 읽기 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof GetClipboardTextPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class GetClipboardTextPermissionError extends PermissionError {
    constructor();
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/위치
  정보/GetCurrentLocationPermissionError.md
---

# GetCurrentLocationPermissionError

위치 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof GetCurrentLocationPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class GetCurrentLocationPermissionError extends PermissionError {
    constructor();
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/코어/Bedrock.md
---

# Granite

`Granite`는 React Native 기반 프레임워크이며, 앱인토스 SDK의 서비스 런타임을 구성하는 핵심 모듈입니다.

:::info
앱인토스의 React Native 미니앱은 **Granite** 기반에서만 동작합니다.
:::

## 시그니처

```typescript
AppsInToss: {
    registerApp(AppContainer: ComponentType<PropsWithChildren<InitialProps>>, { appName, context, router }: BedrockProps): (initialProps: InitialProps) => JSX.Element;
    readonly appName: string;
}
```

### 프로퍼티

`AppsInToss.registerApp` 함수가 제공하는 기능은 다음과 같아요.

* 라우팅: 파일 경로에 맞게 URL이 자동으로 매핑돼요. Next.js의 파일 기반 라우팅과 비슷한 방식으로 동작해요. 예를 들어 `/my-service/pages/index.ts` 파일은 `intoss://my-service` 주소로 접근할 수 있고, `/my-service/pages/home.ts 파일은 intoss://my-service/home` 주소로 접근할 수 있어요.
* 쿼리 파라미터: URL 스킴으로 전달 받은 쿼리 파라미터를 쉽게 사용할 수 있어요. 예를 들어, `referrer` 파라미터를 받아서 로그를 남길 수 있어요.
* 뒤로 가기 제어: 뒤로 가기 이벤트를 제어할 수 있어요. 예를 들어, 사용자가 화면에서 뒤로 가기를 누르면 다이얼로그를 띄우거나 화면을 닫을 수 있어요.
* 화면 가시성(Visibility): 화면이 사용자에게 보이는지, 가려져 있는지 알 수 있어요. 예를 들어, 사용자가 홈 화면으로 나갔을 때 이 값을 활용해 특정 동작을 처리할 수 있어요.

## 예제

### `AppsInToss` 컴포넌트로 만드는 예제

```tsx
import { AppsInToss } from '@apps-in-toss/framework';
import { PropsWithChildren } from 'react';
import { InitialProps } from '@granite-js/react-native';
import { context } from '../require.context';

function AppContainer({ children }: PropsWithChildren<InitialProps>) {
  return <>{children}</>;
}

export default AppsInToss.registerApp(AppContainer, { context });


```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/코어/InitialProps.md
---

# Granite 프로퍼티

## `InitialProps`

React Native 앱에서 사용자가 특정 화면에 진입할 때,
네이티브 플랫폼(Android/iOS)이 앱으로 전달하는 초기 데이터 타입을 제공해요.
초기 데이터는 화면 초기화에 사용되는 중요한 정보를 포함하고 있고, 네이티브 플랫폼별로 필요한 데이터 타입이 달라요.

Android에서 제공하는 데이터 타입은 `AndroidInitialProps`이고, iOS에서 제공하는 데이터 타입은 `IOSInitialProps` 이에요.

## 시그니처

```typescript
type InitialProps = AndroidInitialProps | IOSInitialProps;
```

### 프로퍼티

## 예제

### `InitialProps`를 사용하는 예제

::: code-group

```tsx [_app.tsx]
import { AppsInToss } from '@apps-in-toss/framework';
import { PropsWithChildren } from 'react';
import { InitialProps } from '@granite-js/react-native';
import { context } from '../require.context';

function AppContainer({ children, ...initialProps }: PropsWithChildren<InitialProps>) {
  console.log({ initialProps });
  return <>{children}</>;
}

export default AppsInToss.registerApp(AppContainer, { context });

:::
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/네트워크/http.md
---

# HTTP 통신하기

Bedrock에서 네트워크 통신을 하는 방법을 소개해요.

## Fetch API 사용하기

Bedrock에서는 React Native처럼 [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)를 사용해서 네트워크 통신을 할 수 있어요. Fetch API는 비동기 네트워크 요청을 간단히 구현할 수 있는 표준 웹 API에요.

다음은 "할 일 목록"을 가져오는 API를 사용해 "할 일"이 완료됐을 때 취소선을 표시하는 예제에요.

::: code-group

```tsx [pages/index.tsx]
import { createRoute } from '@granite-js/react-native';
import { useCallback, useState } from "react";
import { Button, ScrollView } from "react-native";
import { Todo, TodoItem } from "./Todo";

export const Route = createRoute("/", {
  component: Index,
});

function Index() {
  const [todos, setTodos] = useState<TodoItem[]>([]);
  // [!code highlight:10]
  const handlePress = useCallback(async () => {
    /**
     * JSONPlaceholder API에서 할 일 데이터를 가져와요.
     * @link https://jsonplaceholder.typicode.com/
     */
    const result = await fetch("https://jsonplaceholder.typicode.com/todos");
    const json = await result.json(); // 응답 데이터를 JSON으로 변환해요.
    setTodos(json); // 가져온 데이터를 상태로 저장해요.
  }, []);

  return (
    <>
      <Button title="할 일 목록 확인하기" onPress={handlePress} />
      <ScrollView>
        {todos.map((todo) => {
          return (
            <Todo
              key={todo.id}
              id={todo.id}
              title={todo.title}
              completed={todo.completed}
            />
          );
        })}
      </ScrollView>
    </>
  );
}
```

```tsx [Todo.tsx]
import { Flex } from '@granite-js/react-native';
import { Text } from 'react-native';

export interface TodoItem {
  title: string;      // 할 일 제목
  id: number;         // 할 일 ID
  completed: boolean; // 완료 여부
}

export function Todo({ title, id, completed: done }: TodoItem) {
  return (
    <Flex direction="row" key={id}>
      <Flex.CenterVertical
        style={{
          minWidth: 30,
        }}
      >
        <Text style={{ fontSize: 24 }}>{id}.</Text>
      </Flex.CenterVertical>
      <Flex.CenterVertical>
        <Text
          style={{
            fontSize: 16,
            textDecorationColor: 'red', // 취소선 색상
            textDecorationLine: done ? 'line-through' : 'none', // 따라 취소선 표시
          }}
        >
          {title}
        </Text>
      </Flex.CenterVertical>
    </Flex>
  );
}
```

:::

예제 영상을 보면 버튼을 클릭하면 네트워크 요청이 발생하고, 화면에 할 일 목록이 표시돼요. 네트워크 요청이 발생할 때 네트워크 인스펙터에서 요청과 응답을 확인할 수 있어요.

* 네트워크 요청 확인 방법은 [디버깅하기 문서](/learn-more/debugging.html#네트워크-활동-검사)를 참고하면 자세히 알 수 있어요.

## 다른 라이브러리 사용하기

React Native는 [XMLHttpRequest API](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)를 지원해요. 따라서, 이 API를 사용하는 써드파티 네트워크 라이브러리도 사용할 수 있어요.

자세한 내용은 [React Native 공식 문서](https://reactnative.dev/docs/0.72/network#using-other-networking-libraries)를 참고하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/Image.md
---

# Image

`Image` 컴포넌트를 사용하면 비트맵(png, jpg 등)이나 벡터(svg) 이미지를 불러와 화면에 표시할 수 있어요.\
이미지 형식에 따라 자동으로 적절한 방식으로 렌더링돼요.

## 시그니처

```typescript
function Image(props: ImageProps): import("react/jsx-runtime").JSX.Element;
```

### 파라미터

## 예제

### 이미지 로드 및 렌더링

아래 예시는 비트맵 이미지와 벡터 이미지를 불러와 표시하는 방법을 보여줘요.\
`onError` 콜백으로 로드 실패 시 로그를 남길 수 있어요

```tsx
import { View } from 'react-native';
import { Image } from '@granite-js/react-native';

function ImageExample() {
  return (
    <View>
      <Image
        source={{ uri: 'my-image-link' }}
        style={{
          width: 300,
          height: 300,
          borderWidth: 1,
        }}
        onError={() => {
          console.log('이미지 로드 실패');
        }}
      />

      <Image
        source={{ uri: 'my-svg-link' }}
        style={{
          width: 300,
          height: 300,
          borderWidth: 1,
        }}
        onError={() => {
          console.log('이미지 로드 실패');
        }}
      />
    </View>
  );
}
```

### 이미지 로드 실패 처리하기

`Image` 컴포넌트를 사용할 때 이미지 로드에 실패하면 `onError` 콜백이 호출돼요.\
이 콜백을 활용하면 에러 발생 시 다른 UI를 표시하거나 사용자에게 알림을 띄울 수 있어요.

아래 예시는 잘못된 URL을 사용해 에러를 유도하고,
에러 발생 시 빨간 테두리의 대체 뷰를 표시하는 예시예요.

```tsx
import { useState } from "react";
import { View } from "react-native";
import { Image, createRoute } from '@granite-js/react-native';

export const Route = createRoute("/", {
  component: Index,
});

function Index() {
  const [hasError, setHasError] = useState(false); // [!code highlight]

  return (
    <View>
      {hasError === true ? (
        <ErrorView />
      ) : (
        <Image
          style={{
            width: 100,
            height: 100,
          }}
          source={{
            uri: "invalid url", // 잘못된 URL을 사용해서 에러를 발생시켜요. // [!code highlight]
          }}
          onError={() => {
            // [!code highlight:4]
            Alert.alert("이미지 에러");
            setHasError(true);
          }}
        />
      )}
    </View>
  );
}

/** 임의의 에러 뷰 */
function ErrorView() {
  return (
    <View
      style={{
        width: 100,
        height: 100,
        borderColor: "red",
        borderWidth: 1,
      }}
    />
  );
}
```

## 참고사항

* `source.cache` 옵션은 비트맵 이미지에만 적용돼요.
* 로컬 리소스를 사용할 경우, `require()`를 통해 이미지 파일을 직접 지정할 수도 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/setIosSwipeGestureEnabled.md
---

# iOS 스와이프 설정하기

## `setIosSwipeGestureEnabled`

`setIosSwipeGestureEnabled` 함수는 iOS에서 화면을 스와이프하여 뒤로가기 기능을 활성화하거나 비활성화할 수 있어요.

## 시그니처

```typescript
function setIosSwipeGestureEnabled(options: {
    isEnabled: boolean;
}): Promise<void>;
```

### 파라미터

### 반환 값

## 예제

### iOS에서 화면 스와이프로 뒤로가기 기능을 활성화하거나 비활성화하기

**스와이프 끄기** 버튼을 눌러 화면 스와이프로 뒤로가기 기능을 비활성화하거나, **스와이프 켜기** 버튼을 눌러 화면 스와이프로 뒤로가기 기능을 활성화할 수 있어요.

```tsx
import { setIosSwipeGestureEnabled } from '@apps-in-toss/framework';
import { Button } from 'react-native';

function Page() {
 return (
   <>
    <Button title="스와이프 끄기" onPress={() => setIosSwipeGestureEnabled({ isEnabled: false })} />
    <Button title="스와이프 켜기" onPress={() => setIosSwipeGestureEnabled({ isEnabled: true })} />
   </>
 );
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/ios-power.md
---
# iOS 전력 최적화

iOS 전력 및 성능 관리는 앱인토스 미니앱에서 Unity 게임이 배터리를 효율적으로 사용하고, 발열을 줄이면서 안정적인 성능을 유지하도록 돕는 핵심 시스템이에요.\
iOS의 엄격한 전력 관리 정책과 앱인토스의 WebGL 환경을 함께 고려해, 지속적이고 부드러운 게임 경험을 제공합니다.

***

## 앱인토스 플랫폼 특화 iOS 최적화

### 1. iOS 배터리 상태 모니터링

```c#
// Unity C# - iOS 배터리 및 성능 모니터
using UnityEngine;
using System.Collections;
using System.Runtime.InteropServices;

public class AITiOSPowerManager : MonoBehaviour
{
    private static AITiOSPowerManager instance;
    public static AITiOSPowerManager Instance => instance;
    
    #if UNITY_IOS && !UNITY_EDITOR
    [DllImport("__Internal")]
    private static extern float GetBatteryLevel();
    
    [DllImport("__Internal")]
    private static extern int GetBatteryState(); // 0: Unknown, 1: Unplugged, 2: Charging, 3: Full
    
    [DllImport("__Internal")]
    private static extern bool IsLowPowerModeEnabled();
    
    [DllImport("__Internal")]
    private static extern float GetThermalState(); // 0: Nominal, 1: Fair, 2: Serious, 3: Critical
    
    [DllImport("__Internal")]
    private static extern void SetPreferredFrameRate(int frameRate);
    
    [DllImport("__Internal")]
    private static extern void EnableMetalPerformanceShaders(bool enabled);
    
    [DllImport("__Internal")]
    private static extern float GetProcessorUsage();
    
    [DllImport("__Internal")]
    private static extern float GetGPUUsage();
    #endif
    
    [System.Serializable]
    public class iOSPowerState
    {
        public float batteryLevel;          // 0.0 ~ 1.0
        public BatteryState batteryState;
        public bool isLowPowerMode;
        public ThermalState thermalState;
        public float cpuUsage;              // 0.0 ~ 1.0
        public float gpuUsage;              // 0.0 ~ 1.0
        public int currentFrameRate;
        public float powerConsumption;      // 추정 전력 소모량 (mW)
        public bool isBackgrounded;
    }
    
    public enum BatteryState
    {
        Unknown = 0,
        Unplugged = 1,
        Charging = 2,
        Full = 3
    }
    
    public enum ThermalState
    {
        Nominal = 0,    // 정상
        Fair = 1,       // 양호
        Serious = 2,    // 심각
        Critical = 3    // 위험
    }
    
    public enum PowerMode
    {
        HighPerformance,    // 고성능 모드
        Balanced,           // 균형 모드
        PowerSaving,        // 절전 모드
        UltraPowerSaving   // 극한 절전 모드
    }
    
    [Header("전력 관리 설정")]
    public PowerMode currentPowerMode = PowerMode.Balanced;
    public bool enableAdaptivePowerManagement = true;
    public bool enableThermalManagement = true;
    public bool enableLowPowerModeDetection = true;
    public float powerMonitoringInterval = 2f;
    
    [Header("성능 임계값")]
    public float batteryLowThreshold = 0.2f;        // 20% 이하 저배터리
    public float batteryCriticalThreshold = 0.1f;   // 10% 이하 위험
    public float thermalThrottleThreshold = 2f;     // 열 제한 임계값
    public float cpuUsageThreshold = 0.8f;          // CPU 사용률 임계값
    public float gpuUsageThreshold = 0.85f;         // GPU 사용률 임계값
    
    private iOSPowerState currentPowerState;
    private PowerMode previousPowerMode;
    private Coroutine powerMonitoringCoroutine;
    
    // 성능 설정 백업
    private struct PerformanceBackup
    {
        public int originalTargetFrameRate;
        public bool originalVSyncEnabled;
        public int originalQualityLevel;
        public float originalTimeScale;
    }
    private PerformanceBackup performanceBackup;
    
    // 이벤트
    public static event System.Action<iOSPowerState> OnPowerStateChanged;
    public static event System.Action<PowerMode> OnPowerModeChanged;
    public static event System.Action<ThermalState> OnThermalStateChanged;
    public static event System.Action OnLowPowerModeEnabled;
    public static event System.Action OnLowPowerModeDisabled;
    
    private void Awake()
    {
        if (instance == null)
        {
            instance = this;
            DontDestroyOnLoad(gameObject);
            InitializePowerManagement();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    private void InitializePowerManagement()
    {
        // iOS에서만 실행
        #if !UNITY_IOS || UNITY_EDITOR
        Debug.LogWarning("[AIT iOS Power] iOS가 아닌 플랫폼에서는 시뮬레이션 모드로 실행");
        #endif
        
        currentPowerState = new iOSPowerState();
        previousPowerMode = currentPowerMode;
        
        // 초기 성능 설정 백업
        BackupPerformanceSettings();
        
        // 전력 모니터링 시작
        if (powerMonitoringCoroutine == null)
        {
            powerMonitoringCoroutine = StartCoroutine(PowerMonitoringLoop());
        }
        
        // 앱 생명주기 이벤트 등록
        RegisterApplicationEvents();
        
        Debug.Log("[AIT iOS Power] iOS 전력 관리 초기화 완료");
    }
    
    private void BackupPerformanceSettings()
    {
        performanceBackup.originalTargetFrameRate = Application.targetFrameRate;
        performanceBackup.originalVSyncEnabled = QualitySettings.vSyncCount > 0;
        performanceBackup.originalQualityLevel = QualitySettings.GetQualityLevel();
        performanceBackup.originalTimeScale = Time.timeScale;
    }
    
    private void RegisterApplicationEvents()
    {
        // 앱 포커스 변경 감지
        Application.focusChanged += OnApplicationFocusChanged;
        
        // iOS 시스템 알림 등록 (네이티브 코드에서 호출)
        #if UNITY_IOS && !UNITY_EDITOR
        RegisterForPowerNotifications();
        #endif
    }
    
    private IEnumerator PowerMonitoringLoop()
    {
        while (true)
        {
            UpdatePowerState();
            
            if (enableAdaptivePowerManagement)
            {
                UpdateAdaptivePowerMode();
            }
            
            if (enableThermalManagement)
            {
                HandleThermalManagement();
            }
            
            yield return new WaitForSeconds(powerMonitoringInterval);
        }
    }
    
    private void UpdatePowerState()
    {
        var previousState = currentPowerState;
        
        #if UNITY_IOS && !UNITY_EDITOR
        currentPowerState.batteryLevel = GetBatteryLevel();
        currentPowerState.batteryState = (BatteryState)GetBatteryState();
        currentPowerState.isLowPowerMode = IsLowPowerModeEnabled();
        currentPowerState.thermalState = (ThermalState)GetThermalState();
        currentPowerState.cpuUsage = GetProcessorUsage();
        currentPowerState.gpuUsage = GetGPUUsage();
        #else
        // 에디터나 다른 플랫폼에서는 시뮬레이션
        currentPowerState.batteryLevel = Mathf.Clamp01(SystemInfo.batteryLevel);
        currentPowerState.batteryState = SystemInfo.batteryStatus == BatteryStatus.Charging ? BatteryState.Charging : BatteryState.Unplugged;
        currentPowerState.isLowPowerMode = false;
        currentPowerState.thermalState = ThermalState.Nominal;
        currentPowerState.cpuUsage = UnityEngine.Random.Range(0.3f, 0.7f);
        currentPowerState.gpuUsage = UnityEngine.Random.Range(0.4f, 0.8f);
        #endif
        
        currentPowerState.currentFrameRate = Mathf.RoundToInt(1f / Time.deltaTime);
        currentPowerState.powerConsumption = EstimatePowerConsumption();
        currentPowerState.isBackgrounded = !Application.isFocused;
        
        // 상태 변경 감지 및 이벤트 발생
        DetectStateChanges(previousState, currentPowerState);
        
        OnPowerStateChanged?.Invoke(currentPowerState);
    }
    
    private float EstimatePowerConsumption()
    {
        // 전력 소모량 추정 (단위: mW)
        float basePower = 500f; // 기본 소모량
        
        // CPU 사용률에 따른 추가 소모
        basePower += currentPowerState.cpuUsage * 1000f;
        
        // GPU 사용률에 따른 추가 소모
        basePower += currentPowerState.gpuUsage * 1500f;
        
        // 프레임레이트에 따른 추가 소모
        float frameRateMultiplier = currentPowerState.currentFrameRate / 30f;
        basePower *= frameRateMultiplier;
        
        // 열 상태에 따른 보정
        switch (currentPowerState.thermalState)
        {
            case ThermalState.Fair:
                basePower *= 1.1f;
                break;
            case ThermalState.Serious:
                basePower *= 1.3f;
                break;
            case ThermalState.Critical:
                basePower *= 1.5f;
                break;
        }
        
        return basePower;
    }
    
    private void DetectStateChanges(iOSPowerState previous, iOSPowerState current)
    {
        // 저전력 모드 변경 감지
        if (enableLowPowerModeDetection && previous.isLowPowerMode != current.isLowPowerMode)
        {
            if (current.isLowPowerMode)
            {
                OnLowPowerModeEnabled?.Invoke();
                Debug.Log("[AIT iOS Power] 저전력 모드 활성화 감지");
            }
            else
            {
                OnLowPowerModeDisabled?.Invoke();
                Debug.Log("[AIT iOS Power] 저전력 모드 비활성화 감지");
            }
        }
        
        // 열 상태 변경 감지
        if (previous.thermalState != current.thermalState)
        {
            OnThermalStateChanged?.Invoke(current.thermalState);
            Debug.Log($"[AIT iOS Power] 열 상태 변경: {previous.thermalState} -> {current.thermalState}");
        }
        
        // 배터리 위험 수준 감지
        if (current.batteryLevel <= batteryCriticalThreshold && previous.batteryLevel > batteryCriticalThreshold)
        {
            Debug.LogWarning("[AIT iOS Power] 배터리 위험 수준 도달!");
            SetPowerMode(PowerMode.UltraPowerSaving);
        }
        else if (current.batteryLevel <= batteryLowThreshold && previous.batteryLevel > batteryLowThreshold)
        {
            Debug.LogWarning("[AIT iOS Power] 배터리 부족 감지");
            if (currentPowerMode == PowerMode.HighPerformance)
            {
                SetPowerMode(PowerMode.PowerSaving);
            }
        }
    }
    
    private void UpdateAdaptivePowerMode()
    {
        PowerMode recommendedMode = currentPowerMode;
        
        // 저전력 모드가 활성화되어 있으면 절전 모드
        if (currentPowerState.isLowPowerMode)
        {
            recommendedMode = PowerMode.PowerSaving;
        }
        // 배터리 위험 수준
        else if (currentPowerState.batteryLevel <= batteryCriticalThreshold)
        {
            recommendedMode = PowerMode.UltraPowerSaving;
        }
        // 배터리 부족
        else if (currentPowerState.batteryLevel <= batteryLowThreshold)
        {
            recommendedMode = PowerMode.PowerSaving;
        }
        // 열 문제
        else if (currentPowerState.thermalState >= ThermalState.Serious)
        {
            recommendedMode = PowerMode.PowerSaving;
        }
        // 높은 CPU/GPU 사용률
        else if (currentPowerState.cpuUsage > cpuUsageThreshold || currentPowerState.gpuUsage > gpuUsageThreshold)
        {
            recommendedMode = PowerMode.Balanced;
        }
        // 충전 중이고 배터리가 충분하면 고성능 모드 허용
        else if (currentPowerState.batteryState == BatteryState.Charging && currentPowerState.batteryLevel > 0.5f)
        {
            recommendedMode = PowerMode.HighPerformance;
        }
        // 일반적인 상황에서는 균형 모드
        else
        {
            recommendedMode = PowerMode.Balanced;
        }
        
        if (recommendedMode != currentPowerMode)
        {
            SetPowerMode(recommendedMode);
        }
    }
    
    private void HandleThermalManagement()
    {
        switch (currentPowerState.thermalState)
        {
            case ThermalState.Nominal:
                // 정상 상태 - 제한 없음
                break;
                
            case ThermalState.Fair:
                // 양호 - 경미한 최적화
                ApplyThermalOptimization(0.9f);
                break;
                
            case ThermalState.Serious:
                // 심각 - 적극적 최적화
                ApplyThermalOptimization(0.7f);
                Debug.LogWarning("[AIT iOS Power] 심각한 열 상태 - 성능 제한");
                break;
                
            case ThermalState.Critical:
                // 위험 - 극한 최적화
                ApplyThermalOptimization(0.5f);
                Debug.LogError("[AIT iOS Power] 위험한 열 상태 - 극한 성능 제한");
                break;
        }
    }
    
    private void ApplyThermalOptimization(float performanceMultiplier)
    {
        // 프레임레이트 제한
        int maxFrameRate = Mathf.RoundToInt(60f * performanceMultiplier);
        
        #if UNITY_IOS && !UNITY_EDITOR
        SetPreferredFrameRate(maxFrameRate);
        #endif
        
        Application.targetFrameRate = maxFrameRate;
        
        // 렌더링 품질 조정
        if (performanceMultiplier < 0.8f)
        {
            // 그림자 품질 낮춤
            QualitySettings.shadowResolution = ShadowResolution.Low;
            QualitySettings.shadowDistance = QualitySettings.shadowDistance * 0.7f;
            
            // 텍스처 품질 낮춤
            QualitySettings.masterTextureLimit = 1;
        }
        
        if (performanceMultiplier < 0.6f)
        {
            // 파티클 수 제한
            var particleBudgetManager = AITParticleBudgetManager.Instance;
            if (particleBudgetManager != null)
            {
                particleBudgetManager.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Low);
            }
            
            // 안티 앨리어싱 비활성화
            QualitySettings.antiAliasing = 0;
        }
    }
    
    public void SetPowerMode(PowerMode mode)
    {
        if (currentPowerMode == mode) return;
        
        previousPowerMode = currentPowerMode;
        currentPowerMode = mode;
        
        ApplyPowerModeSettings(mode);
        OnPowerModeChanged?.Invoke(mode);
        
        Debug.Log($"[AIT iOS Power] 전력 모드 변경: {previousPowerMode} -> {mode}");
    }
    
    private void ApplyPowerModeSettings(PowerMode mode)
    {
        switch (mode)
        {
            case PowerMode.HighPerformance:
                ApplyHighPerformanceSettings();
                break;
                
            case PowerMode.Balanced:
                ApplyBalancedSettings();
                break;
                
            case PowerMode.PowerSaving:
                ApplyPowerSavingSettings();
                break;
                
            case PowerMode.UltraPowerSaving:
                ApplyUltraPowerSavingSettings();
                break;
        }
    }
    
    private void ApplyHighPerformanceSettings()
    {
        // 최고 성능 설정
        Application.targetFrameRate = 60;
        QualitySettings.vSyncCount = 1;
        QualitySettings.SetQualityLevel(QualitySettings.names.Length - 1); // 최고 품질
        
        #if UNITY_IOS && !UNITY_EDITOR
        SetPreferredFrameRate(60);
        EnableMetalPerformanceShaders(true);
        #endif
        
        // 파티클 고품질
        var particleBudgetManager = AITParticleBudgetManager.Instance;
        particleBudgetManager?.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.High);
        
        Debug.Log("[AIT iOS Power] 고성능 모드 적용");
    }
    
    private void ApplyBalancedSettings()
    {
        // 균형잡힌 설정
        Application.targetFrameRate = 45;
        QualitySettings.vSyncCount = 1;
        QualitySettings.SetQualityLevel(Mathf.RoundToInt(QualitySettings.names.Length * 0.6f));
        
        #if UNITY_IOS && !UNITY_EDITOR
        SetPreferredFrameRate(45);
        EnableMetalPerformanceShaders(true);
        #endif
        
        // 파티클 중품질
        var particleBudgetManager = AITParticleBudgetManager.Instance;
        particleBudgetManager?.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Medium);
        
        Debug.Log("[AIT iOS Power] 균형 모드 적용");
    }
    
    private void ApplyPowerSavingSettings()
    {
        // 절전 설정
        Application.targetFrameRate = 30;
        QualitySettings.vSyncCount = 0;
        QualitySettings.SetQualityLevel(Mathf.RoundToInt(QualitySettings.names.Length * 0.4f));
        
        #if UNITY_IOS && !UNITY_EDITOR
        SetPreferredFrameRate(30);
        EnableMetalPerformanceShaders(false);
        #endif
        
        // 파티클 저품질
        var particleBudgetManager = AITParticleBudgetManager.Instance;
        particleBudgetManager?.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Low);
        
        // 추가 최적화
        QualitySettings.shadowResolution = ShadowResolution.Low;
        QualitySettings.shadowDistance = 20f;
        QualitySettings.masterTextureLimit = 1;
        
        Debug.Log("[AIT iOS Power] 절전 모드 적용");
    }
    
    private void ApplyUltraPowerSavingSettings()
    {
        // 극한 절전 설정
        Application.targetFrameRate = 20;
        QualitySettings.vSyncCount = 0;
        QualitySettings.SetQualityLevel(0); // 최저 품질
        
        #if UNITY_IOS && !UNITY_EDITOR
        SetPreferredFrameRate(20);
        EnableMetalPerformanceShaders(false);
        #endif
        
        // 파티클 비활성화
        var particleBudgetManager = AITParticleBudgetManager.Instance;
        particleBudgetManager?.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Low);
        
        // 극한 최적화
        QualitySettings.shadows = ShadowQuality.Disable;
        QualitySettings.masterTextureLimit = 2;
        QualitySettings.antiAliasing = 0;
        
        // 게임 속도 조정 (선택적)
        Time.timeScale = 0.8f;
        
        Debug.LogWarning("[AIT iOS Power] 극한 절전 모드 적용");
    }
    
    private void OnApplicationFocusChanged(bool hasFocus)
    {
        if (hasFocus)
        {
            // 포그라운드로 전환
            Debug.Log("[AIT iOS Power] 앱 포그라운드 전환");
            
            // 전력 상태 즉시 업데이트
            UpdatePowerState();
            
            // 이전 성능 모드 복원 (필요시)
            if (currentPowerState.batteryLevel > batteryLowThreshold && !currentPowerState.isLowPowerMode)
            {
                if (currentPowerMode == PowerMode.UltraPowerSaving)
                {
                    SetPowerMode(PowerMode.Balanced);
                }
            }
        }
        else
        {
            // 백그라운드로 전환
            Debug.Log("[AIT iOS Power] 앱 백그라운드 전환");
            
            // 백그라운드 절전 모드 적용
            ApplyBackgroundOptimizations();
        }
        
        currentPowerState.isBackgrounded = !hasFocus;
    }
    
    private void ApplyBackgroundOptimizations()
    {
        // 백그라운드에서 성능 최소화
        Application.targetFrameRate = 10; // 극저 프레임레이트
        
        #if UNITY_IOS && !UNITY_EDITOR
        SetPreferredFrameRate(10);
        #endif
        
        // 모든 파티클 일시정지
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        foreach (var ps in particleSystems)
        {
            if (ps.isPlaying)
            {
                ps.Pause();
            }
        }
        
        // 오디오 볼륨 최소화
        AudioListener.volume = 0.1f;
        
        Debug.Log("[AIT iOS Power] 백그라운드 최적화 적용");
    }
    
    // 네이티브 코드에서 호출되는 콜백 메서드들
    private void OnBatteryStateChanged(string state)
    {
        Debug.Log($"[AIT iOS Power] 배터리 상태 변경: {state}");
        UpdatePowerState();
    }
    
    private void OnThermalStateChangedNative(string thermalLevel)
    {
        Debug.Log($"[AIT iOS Power] 열 상태 변경: {thermalLevel}");
        UpdatePowerState();
    }
    
    private void OnLowPowerModeChangedNative(string enabled)
    {
        bool isEnabled = enabled.ToLower() == "true";
        Debug.Log($"[AIT iOS Power] 저전력 모드 변경: {isEnabled}");
        UpdatePowerState();
    }
    
    // 공개 API 메서드들
    public iOSPowerState GetCurrentPowerState()
    {
        return currentPowerState;
    }
    
    public void ForcePowerModeUpdate()
    {
        UpdatePowerState();
        UpdateAdaptivePowerMode();
    }
    
    public float GetEstimatedBatteryLife()
    {
        if (currentPowerState.batteryLevel <= 0 || currentPowerState.powerConsumption <= 0)
            return 0f;
        
        // 대략적인 배터리 용량 (mWh) - 기기별로 다르지만 평균적인 값 사용
        float averageBatteryCapacity = 2915f; // iPhone 평균 배터리 용량
        float remainingCapacity = averageBatteryCapacity * currentPowerState.batteryLevel;
        
        // 예상 사용 시간 (시간 단위)
        return remainingCapacity / currentPowerState.powerConsumption;
    }
    
    public void RestorePerformanceSettings()
    {
        Application.targetFrameRate = performanceBackup.originalTargetFrameRate;
        QualitySettings.vSyncCount = performanceBackup.originalVSyncEnabled ? 1 : 0;
        QualitySettings.SetQualityLevel(performanceBackup.originalQualityLevel);
        Time.timeScale = performanceBackup.originalTimeScale;
        
        Debug.Log("[AIT iOS Power] 성능 설정 복원 완료");
    }
    
    public PowerPerformanceStats GetPerformanceStats()
    {
        return new PowerPerformanceStats
        {
            currentPowerMode = currentPowerMode,
            batteryLevel = currentPowerState.batteryLevel,
            isLowPowerMode = currentPowerState.isLowPowerMode,
            thermalState = currentPowerState.thermalState,
            currentFPS = currentPowerState.currentFrameRate,
            cpuUsage = currentPowerState.cpuUsage,
            gpuUsage = currentPowerState.gpuUsage,
            estimatedPowerConsumption = currentPowerState.powerConsumption,
            estimatedBatteryLife = GetEstimatedBatteryLife()
        };
    }
    
    private void OnDestroy()
    {
        if (powerMonitoringCoroutine != null)
        {
            StopCoroutine(powerMonitoringCoroutine);
        }
        
        Application.focusChanged -= OnApplicationFocusChanged;
    }
    
    #if UNITY_IOS && !UNITY_EDITOR
    [DllImport("__Internal")]
    private static extern void RegisterForPowerNotifications();
    #endif
}

[System.Serializable]
public class PowerPerformanceStats
{
    public AITiOSPowerManager.PowerMode currentPowerMode;
    public float batteryLevel;
    public bool isLowPowerMode;
    public AITiOSPowerManager.ThermalState thermalState;
    public int currentFPS;
    public float cpuUsage;
    public float gpuUsage;
    public float estimatedPowerConsumption; // mW
    public float estimatedBatteryLife;      // hours
    
    public string GetBatteryStatus()
    {
        if (batteryLevel <= 0.1f) return "위험";
        if (batteryLevel <= 0.2f) return "부족";
        if (batteryLevel <= 0.5f) return "보통";
        return "충분";
    }
    
    public string GetThermalStatus()
    {
        return thermalState switch
        {
            AITiOSPowerManager.ThermalState.Nominal => "정상",
            AITiOSPowerManager.ThermalState.Fair => "양호",
            AITiOSPowerManager.ThermalState.Serious => "주의",
            AITiOSPowerManager.ThermalState.Critical => "위험",
            _ => "알 수 없음"
        };
    }
    
    public string GetPerformanceGrade()
    {
        float score = (currentFPS / 60f) * 0.4f + (1f - cpuUsage) * 0.3f + (1f - gpuUsage) * 0.3f;
        
        if (score >= 0.8f) return "A";
        if (score >= 0.6f) return "B";
        if (score >= 0.4f) return "C";
        if (score >= 0.2f) return "D";
        return "F";
    }
}
```

### 2. Metal 성능 최적화 시스템

```c#
// Unity C# - Metal 렌더링 최적화
using UnityEngine;
using UnityEngine.Rendering;
using System.Collections.Generic;
using System.Runtime.InteropServices;

public class AITMetalOptimizer : MonoBehaviour
{
    #if UNITY_IOS && !UNITY_EDITOR
    [DllImport("__Internal")]
    private static extern void EnableMetalFX(bool enabled);
    
    [DllImport("__Internal")]
    private static extern void SetMetalMemoryBudget(int megabytes);
    
    [DllImport("__Internal")]
    private static extern int GetMetalMemoryUsage();
    
    [DllImport("__Internal")]
    private static extern void EnableMetalGPUCapture(bool enabled);
    
    [DllImport("__Internal")]
    private static extern void OptimizeMetalPipelines();
    
    [DllImport("__Internal")]
    private static extern float GetGPUFrameTime();
    
    [DllImport("__Internal")]
    private static extern int GetActiveDrawCalls();
    #endif
    
    [System.Serializable]
    public class MetalPerformanceSettings
    {
        [Header("메모리 관리")]
        public int maxMetalMemoryMB = 512;      // Metal 메모리 예산
        public bool enableMemoryPressureOptimization = true;
        
        [Header("렌더링 최적화")]
        public bool enableMetalFX = true;        // MetalFX 업스케일링
        public bool enablePipelineOptimization = true;
        public bool enableCommandBufferReuse = true;
        
        [Header("드로우콜 최적화")]
        public int maxDrawCallsPerFrame = 300;
        public bool enableInstancing = true;
        public bool enableSRPBatcher = true;
        
        [Header("텍스처 최적화")]
        public bool enableTextureStreaming = true;
        public int maxTextureSize = 1024;
        public bool useCompressedTextures = true;
    }
    
    private AITiOSPowerManager powerManager;
    private MetalPerformanceSettings currentSettings;
    private MetalPerformanceSettings defaultSettings;
    
    [Header("Metal 최적화 설정")]
    public MetalPerformanceSettings metalSettings;
    public bool enableDynamicOptimization = true;
    public float optimizationCheckInterval = 1f;
    
    // 성능 메트릭
    private float currentGPUFrameTime;
    private int currentDrawCalls;
    private int currentMetalMemoryUsage;
    private Queue<float> frameTimeHistory;
    private const int FRAME_TIME_HISTORY_SIZE = 60;
    
    private void Start()
    {
        powerManager = AITiOSPowerManager.Instance;
        currentSettings = metalSettings;
        defaultSettings = JsonUtility.FromJson<MetalPerformanceSettings>(JsonUtility.ToJson(metalSettings));
        
        frameTimeHistory = new Queue<float>();
        
        InitializeMetalOptimization();
        
        if (enableDynamicOptimization)
        {
            InvokeRepeating(nameof(UpdateMetalOptimization), optimizationCheckInterval, optimizationCheckInterval);
        }
        
        // 전력 모드 변경 이벤트 구독
        if (powerManager != null)
        {
            AITiOSPowerManager.OnPowerModeChanged += OnPowerModeChanged;
            AITiOSPowerManager.OnThermalStateChanged += OnThermalStateChanged;
        }
    }
    
    private void InitializeMetalOptimization()
    {
        #if UNITY_IOS && !UNITY_EDITOR
        // Metal 메모리 예산 설정
        SetMetalMemoryBudget(currentSettings.maxMetalMemoryMB);
        
        // MetalFX 설정
        EnableMetalFX(currentSettings.enableMetalFX);
        
        // 파이프라인 최적화
        if (currentSettings.enablePipelineOptimization)
        {
            OptimizeMetalPipelines();
        }
        #endif
        
        // SRP Batcher 설정
        if (currentSettings.enableSRPBatcher)
        {
            GraphicsSettings.useScriptableRenderPipelineBatching = true;
        }
        
        // GPU 인스턴싱 설정
        if (currentSettings.enableInstancing)
        {
            EnableGPUInstancing();
        }
        
        Debug.Log("[AIT Metal] Metal 최적화 초기화 완료");
    }
    
    private void UpdateMetalOptimization()
    {
        // 성능 메트릭 업데이트
        UpdatePerformanceMetrics();
        
        // 동적 최적화 적용
        if (enableDynamicOptimization)
        {
            ApplyDynamicOptimizations();
        }
        
        // 메모리 압박 상황 처리
        if (currentSettings.enableMemoryPressureOptimization)
        {
            HandleMemoryPressure();
        }
    }
    
    private void UpdatePerformanceMetrics()
    {
        #if UNITY_IOS && !UNITY_EDITOR
        currentGPUFrameTime = GetGPUFrameTime();
        currentDrawCalls = GetActiveDrawCalls();
        currentMetalMemoryUsage = GetMetalMemoryUsage();
        #else
        // 시뮬레이션 데이터
        currentGPUFrameTime = Time.deltaTime;
        currentDrawCalls = UnityEngine.Random.Range(100, 400);
        currentMetalMemoryUsage = UnityEngine.Random.Range(200, 600);
        #endif
        
        // 프레임 시간 히스토리 업데이트
        frameTimeHistory.Enqueue(currentGPUFrameTime);
        if (frameTimeHistory.Count > FRAME_TIME_HISTORY_SIZE)
        {
            frameTimeHistory.Dequeue();
        }
    }
    
    private void ApplyDynamicOptimizations()
    {
        float averageFrameTime = GetAverageFrameTime();
        
        // GPU 성능이 부족한 경우
        if (averageFrameTime > 20f) // 50 FPS 이하
        {
            ApplyPerformanceOptimizations();
        }
        // 드로우콜이 많은 경우
        else if (currentDrawCalls > currentSettings.maxDrawCallsPerFrame)
        {
            OptimizeDrawCalls();
        }
        // 메모리 사용량이 높은 경우
        else if (currentMetalMemoryUsage > currentSettings.maxMetalMemoryMB * 0.85f)
        {
            OptimizeMemoryUsage();
        }
    }
    
    private float GetAverageFrameTime()
    {
        if (frameTimeHistory.Count == 0) return 0f;
        
        float total = 0f;
        foreach (float frameTime in frameTimeHistory)
        {
            total += frameTime;
        }
        
        return (total / frameTimeHistory.Count) * 1000f; // ms 단위
    }
    
    private void ApplyPerformanceOptimizations()
    {
        Debug.Log("[AIT Metal] GPU 성능 최적화 적용");
        
        // 텍스처 해상도 감소
        if (currentSettings.maxTextureSize > 512)
        {
            currentSettings.maxTextureSize = Mathf.Max(512, currentSettings.maxTextureSize / 2);
            ApplyTextureOptimizations();
        }
        
        // 렌더링 스케일 감소
        if (UnityEngine.XR.XRSettings.enabled == false) // VR이 아닌 경우에만
        {
            UnityEngine.XR.XRSettings.renderViewportScale = Mathf.Max(0.7f, UnityEngine.XR.XRSettings.renderViewportScale * 0.9f);
        }
        
        // 쉐이더 LOD 감소
        Shader.globalMaximumLOD = 200;
        
        #if UNITY_IOS && !UNITY_EDITOR
        // MetalFX 비활성화로 성능 확보
        EnableMetalFX(false);
        #endif
    }
    
    private void OptimizeDrawCalls()
    {
        Debug.Log("[AIT Metal] 드로우콜 최적화 적용");
        
        // 동적 배칭 강화
        var renderers = FindObjectsOfType<Renderer>();
        foreach (var renderer in renderers)
        {
            if (renderer.gameObject.isStatic == false && renderer.bounds.size.magnitude < 10f)
            {
                renderer.gameObject.isStatic = true; // 정적 배칭 가능하도록
            }
        }
        
        // 파티클 시스템 최적화
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        foreach (var ps in particleSystems)
        {
            var renderer = ps.GetComponent<ParticleSystemRenderer>();
            if (renderer != null && renderer.sortMode == ParticleSystemSortMode.Distance)
            {
                renderer.sortMode = ParticleSystemSortMode.None; // 정렬 비활성화
            }
        }
    }
    
    private void OptimizeMemoryUsage()
    {
        Debug.Log("[AIT Metal] Metal 메모리 최적화 적용");
        
        // 텍스처 메모리 해제
        Resources.UnloadUnusedAssets();
        
        // 메모리 예산 감소
        currentSettings.maxMetalMemoryMB = Mathf.Max(256, currentSettings.maxMetalMemoryMB - 64);
        
        #if UNITY_IOS && !UNITY_EDITOR
        SetMetalMemoryBudget(currentSettings.maxMetalMemoryMB);
        #endif
        
        // 텍스처 품질 감소
        QualitySettings.masterTextureLimit = Mathf.Min(2, QualitySettings.masterTextureLimit + 1);
    }
    
    private void HandleMemoryPressure()
    {
        float memoryUsageRatio = (float)currentMetalMemoryUsage / currentSettings.maxMetalMemoryMB;
        
        if (memoryUsageRatio > 0.9f) // 90% 이상 사용
        {
            Debug.LogWarning("[AIT Metal] Metal 메모리 압박 - 긴급 최적화");
            
            // 긴급 메모리 해제
            System.GC.Collect();
            Resources.UnloadUnusedAssets();
            
            // 텍스처 스트리밍 강화
            if (currentSettings.enableTextureStreaming)
            {
                QualitySettings.streamingMipmapsActive = true;
                QualitySettings.streamingMipmapsMemoryBudget = currentSettings.maxMetalMemoryMB / 4;
            }
            
            // 렌더 텍스처 해상도 감소
            var renderTextures = FindObjectsOfType<Camera>();
            foreach (var camera in renderTextures)
            {
                if (camera.targetTexture != null)
                {
                    var rt = camera.targetTexture;
                    camera.targetTexture = null;
                    
                    var newRT = new RenderTexture(rt.width / 2, rt.height / 2, rt.depth, rt.format);
                    camera.targetTexture = newRT;
                    
                    DestroyImmediate(rt);
                }
            }
        }
    }
    
    private void ApplyTextureOptimizations()
    {
        // 런타임에서 텍스처 최적화 적용
        var textures = Resources.FindObjectsOfTypeAll<Texture2D>();
        
        foreach (var texture in textures)
        {
            if (texture.width > currentSettings.maxTextureSize || texture.height > currentSettings.maxTextureSize)
            {
                // 텍스처 다운스케일 (런타임에서는 제한적)
                Debug.Log($"[AIT Metal] 큰 텍스처 감지: {texture.name} ({texture.width}x{texture.height})");
            }
        }
    }
    
    private void EnableGPUInstancing()
    {
        // GPU 인스턴싱 활성화
        var renderers = FindObjectsOfType<MeshRenderer>();
        
        foreach (var renderer in renderers)
        {
            var material = renderer.sharedMaterial;
            if (material != null && material.enableInstancing == false)
            {
                // 인스턴싱 가능한 쉐이더인지 확인
                if (material.shader.name.Contains("Standard") || material.shader.name.Contains("URP"))
                {
                    var newMaterial = new Material(material);
                    newMaterial.enableInstancing = true;
                    renderer.material = newMaterial;
                }
            }
        }
    }
    
    private void OnPowerModeChanged(AITiOSPowerManager.PowerMode newMode)
    {
        switch (newMode)
        {
            case AITiOSPowerManager.PowerMode.HighPerformance:
                RestoreDefaultSettings();
                break;
                
            case AITiOSPowerManager.PowerMode.Balanced:
                ApplyBalancedMetalSettings();
                break;
                
            case AITiOSPowerManager.PowerMode.PowerSaving:
                ApplyPowerSavingMetalSettings();
                break;
                
            case AITiOSPowerManager.PowerMode.UltraPowerSaving:
                ApplyUltraPowerSavingMetalSettings();
                break;
        }
    }
    
    private void OnThermalStateChanged(AITiOSPowerManager.ThermalState thermalState)
    {
        switch (thermalState)
        {
            case AITiOSPowerManager.ThermalState.Serious:
            case AITiOSPowerManager.ThermalState.Critical:
                ApplyThermalThrottling();
                break;
                
            case AITiOSPowerManager.ThermalState.Nominal:
            case AITiOSPowerManager.ThermalState.Fair:
                if (powerManager.GetCurrentPowerState().thermalState == AITiOSPowerManager.ThermalState.Nominal)
                {
                    RestoreFromThermalThrottling();
                }
                break;
        }
    }
    
    private void RestoreDefaultSettings()
    {
        currentSettings = JsonUtility.FromJson<MetalPerformanceSettings>(JsonUtility.ToJson(defaultSettings));
        
        #if UNITY_IOS && !UNITY_EDITOR
        EnableMetalFX(currentSettings.enableMetalFX);
        SetMetalMemoryBudget(currentSettings.maxMetalMemoryMB);
        #endif
        
        Debug.Log("[AIT Metal] 기본 Metal 설정 복원");
    }
    
    private void ApplyBalancedMetalSettings()
    {
        currentSettings.enableMetalFX = true;
        currentSettings.maxMetalMemoryMB = defaultSettings.maxMetalMemoryMB * 3 / 4;
        currentSettings.maxTextureSize = 1024;
        
        #if UNITY_IOS && !UNITY_EDITOR
        EnableMetalFX(currentSettings.enableMetalFX);
        SetMetalMemoryBudget(currentSettings.maxMetalMemoryMB);
        #endif
        
        Debug.Log("[AIT Metal] 균형 Metal 설정 적용");
    }
    
    private void ApplyPowerSavingMetalSettings()
    {
        currentSettings.enableMetalFX = false;
        currentSettings.maxMetalMemoryMB = defaultSettings.maxMetalMemoryMB / 2;
        currentSettings.maxTextureSize = 512;
        currentSettings.maxDrawCallsPerFrame = 200;
        
        #if UNITY_IOS && !UNITY_EDITOR
        EnableMetalFX(false);
        SetMetalMemoryBudget(currentSettings.maxMetalMemoryMB);
        #endif
        
        ApplyTextureOptimizations();
        
        Debug.Log("[AIT Metal] 절전 Metal 설정 적용");
    }
    
    private void ApplyUltraPowerSavingMetalSettings()
    {
        currentSettings.enableMetalFX = false;
        currentSettings.maxMetalMemoryMB = defaultSettings.maxMetalMemoryMB / 4;
        currentSettings.maxTextureSize = 256;
        currentSettings.maxDrawCallsPerFrame = 100;
        
        #if UNITY_IOS && !UNITY_EDITOR
        EnableMetalFX(false);
        SetMetalMemoryBudget(currentSettings.maxMetalMemoryMB);
        #endif
        
        // 극한 최적화
        QualitySettings.masterTextureLimit = 2;
        QualitySettings.shadows = ShadowQuality.Disable;
        Shader.globalMaximumLOD = 100;
        
        Debug.LogWarning("[AIT Metal] 극한 절전 Metal 설정 적용");
    }
    
    private void ApplyThermalThrottling()
    {
        Debug.LogWarning("[AIT Metal] 열 제한 적용");
        
        // 프레임레이트 강제 제한
        Application.targetFrameRate = 20;
        
        // Metal 메모리 대폭 감소
        currentSettings.maxMetalMemoryMB = Mathf.Max(128, currentSettings.maxMetalMemoryMB / 3);
        
        #if UNITY_IOS && !UNITY_EDITOR
        SetMetalMemoryBudget(currentSettings.maxMetalMemoryMB);
        EnableMetalFX(false);
        #endif
        
        // 렌더링 스케일 대폭 감소
        UnityEngine.XR.XRSettings.renderViewportScale = 0.5f;
    }
    
    private void RestoreFromThermalThrottling()
    {
        Debug.Log("[AIT Metal] 열 제한 해제");
        
        // 전력 모드에 맞는 설정으로 복원
        OnPowerModeChanged(powerManager.GetCurrentPowerState().isLowPowerMode ? 
            AITiOSPowerManager.PowerMode.PowerSaving : AITiOSPowerManager.PowerMode.Balanced);
    }
    
    // 공개 API 메서드들
    public MetalPerformanceStats GetMetalPerformanceStats()
    {
        return new MetalPerformanceStats
        {
            currentGPUFrameTime = currentGPUFrameTime,
            currentDrawCalls = currentDrawCalls,
            metalMemoryUsage = currentMetalMemoryUsage,
            maxMetalMemory = currentSettings.maxMetalMemoryMB,
            averageFrameTime = GetAverageFrameTime(),
            isMetalFXEnabled = currentSettings.enableMetalFX,
            memoryPressureLevel = GetMemoryPressureLevel()
        };
    }
    
    private int GetMemoryPressureLevel()
    {
        float ratio = (float)currentMetalMemoryUsage / currentSettings.maxMetalMemoryMB;
        
        if (ratio > 0.9f) return 3; // 높음
        if (ratio > 0.7f) return 2; // 보통
        if (ratio > 0.5f) return 1; // 낮음
        return 0; // 없음
    }
    
    public void ForceMetalOptimization()
    {
        Debug.Log("[AIT Metal] 강제 Metal 최적화 실행");
        
        ApplyPerformanceOptimizations();
        OptimizeDrawCalls();
        OptimizeMemoryUsage();
        
        System.GC.Collect();
        Resources.UnloadUnusedAssets();
    }
    
    private void OnDestroy()
    {
        if (powerManager != null)
        {
            AITiOSPowerManager.OnPowerModeChanged -= OnPowerModeChanged;
            AITiOSPowerManager.OnThermalStateChanged -= OnThermalStateChanged;
        }
    }
}

[System.Serializable]
public class MetalPerformanceStats
{
    public float currentGPUFrameTime;    // ms
    public int currentDrawCalls;
    public int metalMemoryUsage;         // MB
    public int maxMetalMemory;           // MB
    public float averageFrameTime;       // ms
    public bool isMetalFXEnabled;
    public int memoryPressureLevel;      // 0-3 (없음-높음)
    
    public float GetMemoryUsageRatio()
    {
        return maxMetalMemory > 0 ? (float)metalMemoryUsage / maxMetalMemory : 0f;
    }
    
    public string GetPerformanceRating()
    {
        if (averageFrameTime < 16.67f) return "Excellent"; // 60+ FPS
        if (averageFrameTime < 22.22f) return "Good";      // 45+ FPS
        if (averageFrameTime < 33.33f) return "Fair";      // 30+ FPS
        return "Poor";                                      // <30 FPS
    }
    
    public string GetMemoryPressureText()
    {
        return memoryPressureLevel switch
        {
            0 => "없음",
            1 => "낮음",
            2 => "보통",
            3 => "높음",
            _ => "알 수 없음"
        };
    }
}
```

### 3. 네이티브 iOS 통합 코드

```objective-c
// iOS Native - AITiOSPowerBridge.mm
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import <sys/sysctl.h>
#import <mach/mach.h>
#import <Metal/Metal.h>

extern "C" {
    // 배터리 관련 함수들
    float GetBatteryLevel() {
        UIDevice *device = [UIDevice currentDevice];
        device.batteryMonitoringEnabled = YES;
        return device.batteryLevel;
    }
    
    int GetBatteryState() {
        UIDevice *device = [UIDevice currentDevice];
        device.batteryMonitoringEnabled = YES;
        return (int)device.batteryState;
    }
    
    bool IsLowPowerModeEnabled() {
        NSProcessInfo *processInfo = [NSProcessInfo processInfo];
        return processInfo.isLowPowerModeEnabled;
    }
    
    // 열 상태 관련 함수들
    float GetThermalState() {
        NSProcessInfo *processInfo = [NSProcessInfo processInfo];
        return (float)processInfo.thermalState;
    }
    
    // 프레임레이트 설정
    void SetPreferredFrameRate(int frameRate) {
        if (@available(iOS 10.3, *)) {
            [UIScreen mainScreen].maximumFramesPerSecond = frameRate;
        }
    }
    
    // Metal 관련 함수들
    void EnableMetalPerformanceShaders(bool enabled) {
        // MetalPerformanceShaders 활성화/비활성화
        // 실제 구현은 렌더링 파이프라인에 따라 달라집니다
    }
    
    void EnableMetalFX(bool enabled) {
        if (@available(iOS 16.0, *)) {
            // MetalFX 업스케일링 설정
            // 실제 구현 필요
        }
    }
    
    void SetMetalMemoryBudget(int megabytes) {
        // Metal 메모리 예산 설정
        // 실제 구현 필요
    }
    
    int GetMetalMemoryUsage() {
        // 현재 Metal 메모리 사용량 반환
        // 실제 구현 필요
        return 0;
    }
    
    void OptimizeMetalPipelines() {
        // Metal 파이프라인 최적화
        // 실제 구현 필요
    }
    
    float GetGPUFrameTime() {
        // GPU 프레임 시간 측정
        // 실제 구현 필요
        return 16.67f; // 60 FPS 기본값
    }
    
    int GetActiveDrawCalls() {
        // 현재 드로우콜 수 반환
        // 실제 구현 필요
        return 100;
    }
    
    // CPU/GPU 사용률 측정
    float GetProcessorUsage() {
        host_cpu_load_info_data_t cpuinfo;
        mach_msg_type_number_t count = HOST_CPU_LOAD_INFO_COUNT;
        
        if (host_statistics(mach_host_self(), HOST_CPU_LOAD_INFO, 
            (host_info_t)&cpuinfo, &count) == KERN_SUCCESS) {
            
            unsigned long totalTicks = cpuinfo.cpu_ticks[CPU_STATE_USER] + 
                                      cpuinfo.cpu_ticks[CPU_STATE_SYSTEM] + 
                                      cpuinfo.cpu_ticks[CPU_STATE_IDLE] + 
                                      cpuinfo.cpu_ticks[CPU_STATE_NICE];
            
            unsigned long usedTicks = totalTicks - cpuinfo.cpu_ticks[CPU_STATE_IDLE];
            
            return (float)usedTicks / totalTicks;
        }
        
        return 0.0f;
    }
    
    float GetGPUUsage() {
        // GPU 사용률 측정 (복잡한 구현 필요)
        // 간단한 추정값 반환
        return 0.5f;
    }
    
    // 시스템 알림 등록
    void RegisterForPowerNotifications() {
        // 배터리 상태 변경 알림
        [[NSNotificationCenter defaultCenter] addObserverForName:UIDeviceBatteryStateDidChangeNotification
                                                          object:nil
                                                           queue:[NSOperationQueue mainQueue]
                                                      usingBlock:^(NSNotification *notification) {
            UnitySendMessage("AITiOSPowerManager", "OnBatteryStateChanged", "changed");
        }];
        
        // 저전력 모드 변경 알림
        [[NSNotificationCenter defaultCenter] addObserverForName:NSProcessInfoPowerStateDidChangeNotification
                                                          object:nil
                                                           queue:[NSOperationQueue mainQueue]
                                                      usingBlock:^(NSNotification *notification) {
            NSProcessInfo *processInfo = [NSProcessInfo processInfo];
            const char* enabled = processInfo.isLowPowerModeEnabled ? "true" : "false";
            UnitySendMessage("AITiOSPowerManager", "OnLowPowerModeChangedNative", enabled);
        }];
        
        // 열 상태 변경 알림 (iOS 11+)
        if (@available(iOS 11.0, *)) {
            [[NSNotificationCenter defaultCenter] addObserverForName:NSProcessInfoThermalStateDidChangeNotification
                                                              object:nil
                                                               queue:[NSOperationQueue mainQueue]
                                                          usingBlock:^(NSNotification *notification) {
                NSProcessInfo *processInfo = [NSProcessInfo processInfo];
                NSString *thermalState = @"";
                switch (processInfo.thermalState) {
                    case NSProcessInfoThermalStateNominal:
                        thermalState = @"nominal";
                        break;
                    case NSProcessInfoThermalStateFair:
                        thermalState = @"fair";
                        break;
                    case NSProcessInfoThermalStateSerious:
                        thermalState = @"serious";
                        break;
                    case NSProcessInfoThermalStateCritical:
                        thermalState = @"critical";
                        break;
                }
                UnitySendMessage("AITiOSPowerManager", "OnThermalStateChangedNative", 
                               [thermalState UTF8String]);
            }];
        }
    }
}
```

***

## 코드 예제 및 설정

### 1. 앱인토스 통합 전력 관리

```c#
// Unity C# - 앱인토스 통합 전력 관리
using UnityEngine;

public class AITIntegratedPowerManager : MonoBehaviour
{
    private AITiOSPowerManager powerManager;
    private AITMetalOptimizer metalOptimizer;
    private AITParticleBudgetManager particleBudgetManager;
    
    [Header("앱인토스 통합 설정")]
    public bool enableTossAppIntegration = true;        // 토스 앱과의 통합
    public bool enableBackgroundOptimization = true;    // 백그라운드 최적화
    public bool enablePredictivePowerManagement = true; // 예측적 전력 관리
    
    private void Start()
    {
        powerManager = AITiOSPowerManager.Instance;
        metalOptimizer = FindObjectOfType<AITMetalOptimizer>();
        particleBudgetManager = AITParticleBudgetManager.Instance;
        
        InitializeIntegratedPowerManagement();
    }
    
    private void InitializeIntegratedPowerManagement()
    {
        if (powerManager != null)
        {
            // 전력 관리 이벤트 구독
            AITiOSPowerManager.OnPowerModeChanged += OnPowerModeChanged;
            AITiOSPowerManager.OnThermalStateChanged += OnThermalStateChanged;
            AITiOSPowerManager.OnLowPowerModeEnabled += OnLowPowerModeEnabled;
        }
        
        // 토스 앱과의 통합 설정
        if (enableTossAppIntegration)
        {
            ConfigureTossAppIntegration();
        }
        
        Debug.Log("[AIT Integrated] 통합 전력 관리 초기화 완료");
    }
    
    private void ConfigureTossAppIntegration()
    {
        // 토스 앱의 전력 정책에 맞춰 설정 조정
        #if UNITY_WEBGL && !UNITY_EDITOR
        // WebView 환경에서의 최적화
        Application.ExternalCall("configureTossAppPowerIntegration");
        #endif
        
        // 토스 앱의 백그라운드 정책에 맞춰 조정
        if (enableBackgroundOptimization)
        {
            Application.focusChanged += OnTossAppFocusChanged;
        }
    }
    
    private void OnPowerModeChanged(AITiOSPowerManager.PowerMode newMode)
    {
        Debug.Log($"[AIT Integrated] 전력 모드 변경: {newMode}");
        
        // 모든 시스템에 전력 모드 변경 전달
        ApplyIntegratedPowerSettings(newMode);
        
        // 토스 앱에 전력 상태 알림
        if (enableTossAppIntegration)
        {
            NotifyTossAppPowerChange(newMode);
        }
    }
    
    private void ApplyIntegratedPowerSettings(AITiOSPowerManager.PowerMode mode)
    {
        switch (mode)
        {
            case AITiOSPowerManager.PowerMode.HighPerformance:
                ApplyHighPerformanceIntegration();
                break;
                
            case AITiOSPowerManager.PowerMode.Balanced:
                ApplyBalancedIntegration();
                break;
                
            case AITiOSPowerManager.PowerMode.PowerSaving:
                ApplyPowerSavingIntegration();
                break;
                
            case AITiOSPowerManager.PowerMode.UltraPowerSaving:
                ApplyUltraPowerSavingIntegration();
                break;
        }
    }
    
    private void ApplyHighPerformanceIntegration()
    {
        // Unity 최고 품질 설정
        QualitySettings.SetQualityLevel(QualitySettings.names.Length - 1);
        
        // 파티클 시스템 고품질
        particleBudgetManager?.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.High);
        
        // Metal 최적화 해제 (최고 품질을 위해)
        // metalOptimizer는 자체적으로 전력 모드 변경을 감지하므로 별도 호출 불필요
        
        Debug.Log("[AIT Integrated] 고성능 통합 설정 적용");
    }
    
    private void ApplyBalancedIntegration()
    {
        // 균형잡힌 품질 설정
        int balancedQuality = Mathf.RoundToInt(QualitySettings.names.Length * 0.6f);
        QualitySettings.SetQualityLevel(balancedQuality);
        
        // 파티클 시스템 중품질
        particleBudgetManager?.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Medium);
        
        Debug.Log("[AIT Integrated] 균형 통합 설정 적용");
    }
    
    private void ApplyPowerSavingIntegration()
    {
        // 절전 품질 설정
        int powerSavingQuality = Mathf.RoundToInt(QualitySettings.names.Length * 0.3f);
        QualitySettings.SetQualityLevel(powerSavingQuality);
        
        // 파티클 시스템 저품질
        particleBudgetManager?.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Low);
        
        // 추가 절전 최적화
        AudioListener.volume = 0.7f;  // 오디오 볼륨 감소
        Screen.brightness = Mathf.Max(0.3f, Screen.brightness * 0.8f);  // 화면 밝기 감소
        
        Debug.Log("[AIT Integrated] 절전 통합 설정 적용");
    }
    
    private void ApplyUltraPowerSavingIntegration()
    {
        // 극한 절전 설정
        QualitySettings.SetQualityLevel(0);
        
        // 파티클 시스템 비활성화
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        foreach (var ps in particleSystems)
        {
            ps.Stop(true, ParticleSystemStopBehavior.StopEmittingAndClear);
        }
        
        // 오디오 최소화
        AudioListener.volume = 0.3f;
        AudioListener.pause = true;
        
        // 업데이트 빈도 감소
        Time.fixedDeltaTime = 0.1f;  // 물리 업데이트 10Hz로 감소
        
        Debug.LogWarning("[AIT Integrated] 극한 절전 통합 설정 적용");
    }
    
    private void OnThermalStateChanged(AITiOSPowerManager.ThermalState thermalState)
    {
        Debug.Log($"[AIT Integrated] 열 상태 변경: {thermalState}");
        
        // 심각한 열 상태에서는 즉시 절전 모드로 전환
        if (thermalState >= AITiOSPowerManager.ThermalState.Serious)
        {
            ApplyEmergencyThermalProtection();
        }
    }
    
    private void ApplyEmergencyThermalProtection()
    {
        Debug.LogWarning("[AIT Integrated] 긴급 열 보호 모드 활성화");
        
        // 즉시 최저 성능으로 전환
        Application.targetFrameRate = 15;  // 15 FPS로 제한
        
        // 모든 애니메이션 일시정지
        var animators = FindObjectsOfType<Animator>();
        foreach (var animator in animators)
        {
            animator.speed = 0.5f;  // 애니메이션 속도 50% 감소
        }
        
        // 렌더링 스케일 대폭 감소
        UnityEngine.XR.XRSettings.renderViewportScale = 0.4f;
        
        // 파티클 완전 중단
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        foreach (var ps in particleSystems)
        {
            ps.Pause();
        }
    }
    
    private void OnLowPowerModeEnabled()
    {
        Debug.Log("[AIT Integrated] iOS 저전력 모드 감지 - 즉시 절전 모드 전환");
        
        // 저전력 모드가 활성화되면 즉시 절전 설정 적용
        powerManager?.SetPowerMode(AITiOSPowerManager.PowerMode.PowerSaving);
    }
    
    private void OnTossAppFocusChanged(bool hasFocus)
    {
        if (hasFocus)
        {
            // 토스 앱 포그라운드 - 정상 성능 복원
            Debug.Log("[AIT Integrated] 토스 앱 포그라운드 - 성능 복원");
            RestoreNormalPerformance();
        }
        else
        {
            // 토스 앱 백그라운드 - 최소 성능으로 전환
            Debug.Log("[AIT Integrated] 토스 앱 백그라운드 - 최소 성능 전환");
            ApplyBackgroundMinimization();
        }
    }
    
    private void RestoreNormalPerformance()
    {
        // 현재 전력 상태에 맞는 설정으로 복원
        if (powerManager != null)
        {
            var currentState = powerManager.GetCurrentPowerState();
            
            if (currentState.isLowPowerMode)
            {
                ApplyPowerSavingIntegration();
            }
            else if (currentState.batteryLevel > 0.5f)
            {
                ApplyBalancedIntegration();
            }
            else
            {
                ApplyPowerSavingIntegration();
            }
        }
        
        // 오디오 복원
        AudioListener.pause = false;
        AudioListener.volume = 1f;
        
        // 애니메이션 속도 복원
        var animators = FindObjectsOfType<Animator>();
        foreach (var animator in animators)
        {
            animator.speed = 1f;
        }
    }
    
    private void ApplyBackgroundMinimization()
    {
        // 백그라운드에서 최소 성능 유지
        Application.targetFrameRate = 5;  // 5 FPS로 극도로 제한
        
        // 모든 파티클 일시정지
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        foreach (var ps in particleSystems)
        {
            ps.Pause();
        }
        
        // 오디오 일시정지
        AudioListener.pause = true;
        AudioListener.volume = 0f;
        
        // 물리 업데이트 최소화
        Time.fixedDeltaTime = 0.2f;  // 5Hz 물리 업데이트
    }
    
    private void NotifyTossAppPowerChange(AITiOSPowerManager.PowerMode mode)
    {
        #if UNITY_WEBGL && !UNITY_EDITOR
        string modeString = mode.ToString();
        Application.ExternalCall("onUnityPowerModeChanged", modeString);
        #endif
    }
    
    // 공개 API 메서드들
    public PowerPerformanceStats GetIntegratedStats()
    {
        var stats = powerManager?.GetPerformanceStats();
        if (stats == null)
        {
            return new PowerPerformanceStats();
        }
        
        // Metal 통계 추가
        if (metalOptimizer != null)
        {
            var metalStats = metalOptimizer.GetMetalPerformanceStats();
            // 통합 통계 생성 (구현 필요)
        }
        
        return stats;
    }
    
    public void ForceOptimization()
    {
        Debug.Log("[AIT Integrated] 강제 통합 최적화 실행");
        
        // 모든 시스템 최적화
        powerManager?.ForcePowerModeUpdate();
        metalOptimizer?.ForceMetalOptimization();
        particleBudgetManager?.ForceCleanup();
        
        // 메모리 정리
        System.GC.Collect();
        Resources.UnloadUnusedAssets();
    }
    
    private void OnDestroy()
    {
        if (powerManager != null)
        {
            AITiOSPowerManager.OnPowerModeChanged -= OnPowerModeChanged;
            AITiOSPowerManager.OnThermalStateChanged -= OnThermalStateChanged;
            AITiOSPowerManager.OnLowPowerModeEnabled -= OnLowPowerModeEnabled;
        }
        
        if (enableBackgroundOptimization)
        {
            Application.focusChanged -= OnTossAppFocusChanged;
        }
    }
}
```

## 문제 해결 및 디버깅

### 1. iOS 전력 문제 진단 도구

```c#
// Unity C# - iOS 전력 문제 진단기
public class AITiOSPowerDiagnostic : MonoBehaviour
{
    private AITiOSPowerManager powerManager;
    
    [ContextMenu("배터리 상태 진단")]
    public void DiagnoseBatteryIssues()
    {
        if (powerManager == null)
        {
            powerManager = AITiOSPowerManager.Instance;
        }
        
        var powerStats = powerManager?.GetPerformanceStats();
        if (powerStats == null)
        {
            Debug.LogError("[AIT Diagnostic] 전력 관리자를 찾을 수 없음");
            return;
        }
        
        Debug.Log("=== iOS 전력 진단 결과 ===");
        Debug.Log($"배터리 수준: {powerStats.batteryLevel:P0} ({powerStats.GetBatteryStatus()})");
        Debug.Log($"저전력 모드: {(powerStats.isLowPowerMode ? "활성화" : "비활성화")}");
        Debug.Log($"열 상태: {powerStats.GetThermalStatus()}");
        Debug.Log($"현재 FPS: {powerStats.currentFPS}");
        Debug.Log($"CPU 사용률: {powerStats.cpuUsage:P1}");
        Debug.Log($"GPU 사용률: {powerStats.gpuUsage:P1}");
        Debug.Log($"예상 전력 소모: {powerStats.estimatedPowerConsumption:F0} mW");
        Debug.Log($"예상 배터리 수명: {powerStats.estimatedBatteryLife:F1} 시간");
        Debug.Log($"성능 등급: {powerStats.GetPerformanceGrade()}");
        
        // 문제 상황 감지
        DetectPowerIssues(powerStats);
    }
    
    private void DetectPowerIssues(PowerPerformanceStats stats)
    {
        Debug.Log("\n=== 감지된 문제점 ===");
        
        if (stats.batteryLevel <= 0.1f)
        {
            Debug.LogError("위험: 배터리 수준이 매우 낮음 (10% 이하)");
            Debug.LogError("권장사항: 즉시 극한 절전 모드 적용 필요");
        }
        else if (stats.batteryLevel <= 0.2f)
        {
            Debug.LogWarning("경고: 배터리 수준이 낮음 (20% 이하)");
            Debug.LogWarning("권장사항: 절전 모드 적용 권장");
        }
        
        if (stats.thermalState >= AITiOSPowerManager.ThermalState.Serious)
        {
            Debug.LogError($"위험: 심각한 열 상태 ({stats.GetThermalStatus()})");
            Debug.LogError("권장사항: 즉시 성능 제한 필요");
        }
        
        if (stats.currentFPS < 20)
        {
            Debug.LogWarning($"성능: 낮은 프레임레이트 ({stats.currentFPS} FPS)");
            Debug.LogWarning("권장사항: 그래픽 설정 최적화 필요");
        }
        
        if (stats.cpuUsage > 0.8f)
        {
            Debug.LogWarning($"성능: 높은 CPU 사용률 ({stats.cpuUsage:P0})");
            Debug.LogWarning("권장사항: CPU 집약적 작업 최적화 필요");
        }
        
        if (stats.gpuUsage > 0.85f)
        {
            Debug.LogWarning($"성능: 높은 GPU 사용률 ({stats.gpuUsage:P0})");
            Debug.LogWarning("권장사항: 렌더링 최적화 필요");
        }
        
        if (stats.estimatedBatteryLife < 1f)
        {
            Debug.LogError($"위험: 예상 배터리 수명이 매우 짧음 ({stats.estimatedBatteryLife:F1} 시간)");
            Debug.LogError("권장사항: 전력 소모 대폭 감소 필요");
        }
    }
    
    [ContextMenu("성능 최적화 권장사항")]
    public void SuggestOptimizations()
    {
        Debug.Log("=== 성능 최적화 권장사항 ===");
        
        // 현재 Unity 설정 분석
        AnalyzeUnitySettings();
        
        // 프로젝트별 최적화 제안
        AnalyzeProjectOptimizations();
    }
    
    private void AnalyzeUnitySettings()
    {
        Debug.Log("\n--- Unity 설정 분석 ---");
        
        Debug.Log($"현재 품질 레벨: {QualitySettings.names[QualitySettings.GetQualityLevel()]}");
        Debug.Log($"목표 프레임레이트: {Application.targetFrameRate}");
        Debug.Log($"V-Sync: {(QualitySettings.vSyncCount > 0 ? "활성화" : "비활성화")}");
        Debug.Log($"그림자 품질: {QualitySettings.shadows}");
        Debug.Log($"안티앨리어싱: {QualitySettings.antiAliasing}");
        Debug.Log($"텍스처 제한: {QualitySettings.masterTextureLimit}");
        
        // 권장사항 제시
        if (QualitySettings.GetQualityLevel() > 3)
        {
            Debug.LogWarning("권장사항: 모바일에서는 중간 품질 레벨 사용 권장");
        }
        
        if (Application.targetFrameRate > 30)
        {
            Debug.LogWarning("권장사항: 배터리 절약을 위해 30 FPS 제한 고려");
        }
        
        if (QualitySettings.vSyncCount > 0)
        {
            Debug.LogWarning("권장사항: 모바일에서 V-Sync 비활성화로 성능 향상");
        }
    }
    
    private void AnalyzeProjectOptimizations()
    {
        Debug.Log("\n--- 프로젝트 최적화 분석 ---");
        
        // 오브젝트 수 분석
        int totalGameObjects = FindObjectsOfType<GameObject>().Length;
        Debug.Log($"총 GameObject 수: {totalGameObjects}");
        if (totalGameObjects > 1000)
        {
            Debug.LogWarning("권장사항: GameObject 수가 많음, 오브젝트 풀링 고려");
        }
        
        // 렌더러 분석
        var renderers = FindObjectsOfType<Renderer>();
        Debug.Log($"총 Renderer 수: {renderers.Length}");
        
        int shadowCastingRenderers = 0;
        foreach (var renderer in renderers)
        {
            if (renderer.shadowCastingMode != UnityEngine.Rendering.ShadowCastingMode.Off)
            {
                shadowCastingRenderers++;
            }
        }
        
        if (shadowCastingRenderers > 100)
        {
            Debug.LogWarning($"권장사항: 그림자 생성 오브젝트가 많음 ({shadowCastingRenderers}개)");
        }
        
        // 라이트 분석
        var lights = FindObjectsOfType<Light>();
        Debug.Log($"총 Light 수: {lights.Length}");
        if (lights.Length > 5)
        {
            Debug.LogWarning("권장사항: 라이트 수가 많음, 베이크드 라이팅 고려");
        }
        
        // 파티클 시스템 분석
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        int activeParticles = 0;
        foreach (var ps in particleSystems)
        {
            activeParticles += ps.particleCount;
        }
        
        Debug.Log($"총 ParticleSystem 수: {particleSystems.Length}");
        Debug.Log($"활성 파티클 수: {activeParticles}");
        
        if (activeParticles > 1000)
        {
            Debug.LogWarning("권장사항: 활성 파티클 수가 많음, 파티클 예산 관리 적용");
        }
    }
    
    [ContextMenu("메모리 사용량 분석")]
    public void AnalyzeMemoryUsage()
    {
        Debug.Log("=== 메모리 사용량 분석 ===");
        
        // Unity 메모리 분석
        long totalMemory = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(UnityEngine.Profiling.Profiler.Area.Total);
        long managedMemory = System.GC.GetTotalMemory(false);
        
        Debug.Log($"총 할당 메모리: {totalMemory / 1024 / 1024} MB");
        Debug.Log($"관리 메모리: {managedMemory / 1024 / 1024} MB");
        
        // 텍스처 메모리 분석
        var textures = Resources.FindObjectsOfTypeAll<Texture>();
        long textureMemory = 0;
        int largeTextures = 0;
        
        foreach (var texture in textures)
        {
            if (texture is Texture2D tex2D)
            {
                // 대략적인 텍스처 메모리 계산
                int texSize = tex2D.width * tex2D.height * 4; // RGBA 가정
                textureMemory += texSize;
                
                if (tex2D.width > 1024 || tex2D.height > 1024)
                {
                    largeTextures++;
                }
            }
        }
        
        Debug.Log($"텍스처 메모리 (추정): {textureMemory / 1024 / 1024} MB");
        Debug.Log($"대형 텍스처 (1024x1024 이상): {largeTextures}개");
        
        if (textureMemory / 1024 / 1024 > 100)
        {
            Debug.LogWarning("권장사항: 텍스처 메모리 사용량이 높음, 압축 또는 다운스케일 고려");
        }
        
        if (largeTextures > 10)
        {
            Debug.LogWarning("권장사항: 대형 텍스처가 많음, 아틀라싱 또는 크기 최적화 권장");
        }
    }
}
```

***

## 관련 도구 및 리소스

### 1. Xcode Instruments 통합

```objective-c
// iOS Native - Instruments 통합을 위한 코드
#import <os/log.h>
#import <os/signpost.h>

// 성능 측정을 위한 Signpost
static os_log_t ait_performance_log;
static os_signpost_id_t ait_frame_signpost;

void InitializeInstrumentsIntegration() {
    ait_performance_log = os_log_create("com.appintoss.unity", "Performance");
    ait_frame_signpost = os_signpost_id_generate(ait_performance_log);
}

void BeginFrameSignpost() {
    os_signpost_interval_begin(ait_performance_log, ait_frame_signpost, "Frame");
}

void EndFrameSignpost() {
    os_signpost_interval_end(ait_performance_log, ait_frame_signpost, "Frame");
}

void LogPowerEvent(const char* event, const char* details) {
    os_log_with_type(ait_performance_log, OS_LOG_TYPE_INFO, 
                     "Power Event: %{public}s - %{public}s", event, details);
}
```

### 2. 자동화된 성능 테스트 도구

```c#
// Unity C# - 자동화된 성능 테스트
#if UNITY_EDITOR
using UnityEngine;
using UnityEditor;

public class AITiOSPerformanceTestSuite : EditorWindow
{
    private bool isTestRunning = false;
    private float testProgress = 0f;
    private string testStatus = "준비";
    
    [MenuItem("앱인토스/iOS 성능 테스트 도구")]
    public static void ShowWindow()
    {
        GetWindow<AITiOSPerformanceTestSuite>("iOS 성능 테스트");
    }
    
    private void OnGUI()
    {
        GUILayout.Label("iOS 성능 테스트 도구", EditorStyles.boldLabel);
        
        EditorGUILayout.Space();
        
        // 테스트 상태
        EditorGUILayout.LabelField("상태", testStatus);
        
        if (isTestRunning)
        {
            EditorGUILayout.Slider(testProgress, 0f, 1f);
        }
        
        EditorGUILayout.Space();
        
        // 테스트 실행 버튼들
        EditorGUI.BeginDisabledGroup(isTestRunning);
        
        if (GUILayout.Button("배터리 소모 테스트"))
        {
            StartBatteryDrainTest();
        }
        
        if (GUILayout.Button("열 성능 테스트"))
        {
            StartThermalPerformanceTest();
        }
        
        if (GUILayout.Button("메모리 사용량 테스트"))
        {
            StartMemoryUsageTest();
        }
        
        if (GUILayout.Button("종합 성능 테스트"))
        {
            StartComprehensiveTest();
        }
        
        EditorGUI.EndDisabledGroup();
        
        if (isTestRunning && GUILayout.Button("테스트 중단"))
        {
            StopCurrentTest();
        }
    }
    
    private void StartBatteryDrainTest()
    {
        Debug.Log("[AIT Test] 배터리 소모 테스트 시작");
        testStatus = "배터리 테스트 실행 중...";
        isTestRunning = true;
        
        // 실제 배터리 테스트 로직 구현
        EditorApplication.delayCall += () => {
            // 테스트 완료 후
            testStatus = "배터리 테스트 완료";
            isTestRunning = false;
        };
    }
    
    private void StartThermalPerformanceTest()
    {
        Debug.Log("[AIT Test] 열 성능 테스트 시작");
        testStatus = "열 성능 테스트 실행 중...";
        isTestRunning = true;
        
        // GPU 집약적 작업을 통한 열 테스트
    }
    
    private void StartMemoryUsageTest()
    {
        Debug.Log("[AIT Test] 메모리 사용량 테스트 시작");
        testStatus = "메모리 테스트 실행 중...";
        isTestRunning = true;
        
        // 메모리 할당/해제를 통한 메모리 테스트
    }
    
    private void StartComprehensiveTest()
    {
        Debug.Log("[AIT Test] 종합 성능 테스트 시작");
        testStatus = "종합 테스트 실행 중...";
        isTestRunning = true;
        
        // 모든 테스트를 순차적으로 실행
    }
    
    private void StopCurrentTest()
    {
        testStatus = "테스트 중단됨";
        isTestRunning = false;
        testProgress = 0f;
    }
}
#endif
```

***

## 모범 사례

### 1. iOS 전력 최적화 체크리스트

#### 배터리 최적화

* 저전력 모드 감지 및 자동 적응
* 배터리 수준별 성능 조정
* 백그라운드에서 최소 동작
* 불필요한 센서 사용 중단

#### 열 관리

* 열 상태 모니터링
* CPU/GPU 사용률 제한
* 동적 품질 조정
* 긴급 성능 제한

#### 메모리 관리

* Metal 메모리 예산 설정
* 텍스처 크기 최적화
* 정기적 메모리 정리
* 메모리 압박 상황 대응

#### 성능 최적화

* 적응형 프레임레이트
* LOD 시스템 적용
* 드로우콜 최소화
* 파티클 예산 관리

### 2. 토스 앱 통합 고려사항

#### 1. 토스 앱의 전력 정책 준수

* 토스 앱의 백그라운드 정책에 맞춰 동작
* 다른 토스 서비스와의 리소스 공유 고려

#### 2. 사용자 경험 최적화

* 배터리 부족 시 자동 절전 모드
* 성능 저하 시 적절한 사용자 알림

#### 3. 모니터링 및 분석

* 실사용 환경에서의 전력 소모 데이터 수집
* A/B 테스트를 통한 최적화 효과 검증

이러한 iOS 전력 및 성능 관리 시스템을 통해 앱인토스 플랫폼에서 배터리 효율성과 사용자 경험을 동시에 최적화할 수 있어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/runtime/ios.md'
---
# iOS 최적화

앱인토스 Unity 게임을 iOS 환경에서 최적의 성능으로 실행하기 위한 특화된 최적화 기법과 설정을 제공해요.

## 1. iOS 성능 특성 이해

### iOS vs Android 성능 차이점

```
🍎 iOS 성능 특성
├── 메모리 관리
│   ├── 더 엄격한 메모리 제한
│   ├── ARC (Automatic Reference Counting)
│   └── 메모리 압박 시 강제 종료
├── GPU 성능  
│   ├── Metal API 최적화
│   ├── 타일 기반 렌더링
│   └── A-시리즈 칩셋 특성
├── 배터리 관리
│   ├── iOS 전력 관리 시스템
│   ├── 백그라운드 앱 제한
│   └── 열 관리 (Thermal Management)
└── 앱 스토어 가이드라인
    ├── 64비트 필수
    ├── 메모리 사용량 제한
    └── 성능 기준 준수
```

### iOS 기기별 성능 분류

```c#
public enum iOSDeviceTier
{
    HighEnd,    // iPhone 13+ (A15 Bionic+)
    MidHigh,    // iPhone 11-12 (A13-A14 Bionic)  
    MidRange,   // iPhone X-XS (A11-A12 Bionic)
    LowEnd      // iPhone 8 이하 (A10 이하)
}

public class iOSDeviceDetector : MonoBehaviour
{
    public static iOSDeviceTier GetCurrentDeviceTier()
    {
        #if UNITY_IOS
        string deviceModel = SystemInfo.deviceModel;
        
        // A15+ (iPhone 13+)
        if (deviceModel.Contains("iPhone14") || deviceModel.Contains("iPhone15"))
        {
            return iOSDeviceTier.HighEnd;
        }
        // A13-A14 (iPhone 11-12)
        else if (deviceModel.Contains("iPhone12") || deviceModel.Contains("iPhone13"))
        {
            return iOSDeviceTier.MidHigh;
        }
        // A11-A12 (iPhone X-XS)
        else if (deviceModel.Contains("iPhone10") || deviceModel.Contains("iPhone11"))
        {
            return iOSDeviceTier.MidRange;
        }
        // A10 이하
        else
        {
            return iOSDeviceTier.LowEnd;
        }
        #else
        return iOSDeviceTier.MidRange;
        #endif
    }
}
```

***

## 2. Metal 렌더링 최적화

### Metal API 활용

```c#
public class iOSMetalOptimizer : MonoBehaviour
{
    [Header("Metal 설정")]
    public bool enableMetalOptimization = true;
    public bool useMetalPerformanceShaders = true;
    public bool enableGPUInstancing = true;
    
    [Header("렌더링 최적화")]
    public bool useTiledRendering = true;
    public bool enableOcclusionCulling = true;
    public int maxRenderTargets = 4;
    
    void Start()
    {
        #if UNITY_IOS
        if (enableMetalOptimization)
        {
            OptimizeForMetal();
        }
        #endif
    }
    
    void OptimizeForMetal()
    {
        // Metal 전용 설정 적용
        if (SystemInfo.graphicsDeviceType == UnityEngine.Rendering.GraphicsDeviceType.Metal)
        {
            // GPU 인스턴싱 활성화
            if (enableGPUInstancing)
            {
                EnableGPUInstancing();
            }
            
            // 타일 기반 렌더링 최적화
            if (useTiledRendering)
            {
                OptimizeTiledRendering();
            }
            
            // Metal Performance Shaders 사용
            if (useMetalPerformanceShaders)
            {
                EnableMetalPerformanceShaders();
            }
            
            Debug.Log("iOS Metal 최적화 적용 완료");
        }
    }
    
    void EnableGPUInstancing()
    {
        // GPU 인스턴싱을 통한 드로우콜 감소
        var renderers = FindObjectsOfType<MeshRenderer>();
        
        foreach (var renderer in renderers)
        {
            var materials = renderer.materials;
            foreach (var material in materials)
            {
                if (material.shader.name.Contains("Standard"))
                {
                    material.EnableKeyword("_GPU_INSTANCING");
                }
            }
        }
    }
    
    void OptimizeTiledRendering()
    {
        // iOS 타일 기반 렌더링에 최적화
        QualitySettings.antiAliasing = 0; // MSAA 비활성화 (타일 렌더링과 충돌)
        
        // 렌더 타겟 크기 최적화
        Screen.SetResolution(Screen.width, Screen.height, true);
        
        // 후처리 효과 최적화
        var postProcessVolumes = FindObjectsOfType<UnityEngine.Rendering.PostProcessing.PostProcessVolume>();
        foreach (var volume in postProcessVolumes)
        {
            OptimizePostProcessProfile(volume);
        }
    }
    
    void OptimizePostProcessProfile(UnityEngine.Rendering.PostProcessing.PostProcessVolume volume)
    {
        if (volume.profile == null) return;
        
        var deviceTier = iOSDeviceDetector.GetCurrentDeviceTier();
        
        // 기기 등급에 따른 후처리 설정 조정
        switch (deviceTier)
        {
            case iOSDeviceTier.HighEnd:
                // 고사양: 모든 효과 활성화
                break;
                
            case iOSDeviceTier.MidHigh:
                // 중고사양: 일부 효과 품질 조정
                DisableExpensiveEffects(volume, false);
                break;
                
            case iOSDeviceTier.MidRange:
                // 중사양: 기본 효과만 유지
                DisableExpensiveEffects(volume, true);
                break;
                
            case iOSDeviceTier.LowEnd:
                // 저사양: 후처리 비활성화
                volume.enabled = false;
                break;
        }
    }
    
    void DisableExpensiveEffects(UnityEngine.Rendering.PostProcessing.PostProcessVolume volume, bool aggressive)
    {
        var profile = volume.profile;
        
        // 비용이 높은 효과들 비활성화
        if (profile.TryGetSettings(out UnityEngine.Rendering.PostProcessing.Bloom bloom))
        {
            bloom.enabled.value = !aggressive;
        }
        
        if (profile.TryGetSettings(out UnityEngine.Rendering.PostProcessing.DepthOfField dof))
        {
            dof.enabled.value = false; // iOS에서 성능 영향 큰 효과
        }
        
        if (profile.TryGetSettings(out UnityEngine.Rendering.PostProcessing.MotionBlur motionBlur))
        {
            motionBlur.enabled.value = false;
        }
        
        if (profile.TryGetSettings(out UnityEngine.Rendering.PostProcessing.ScreenSpaceReflections ssr))
        {
            ssr.enabled.value = false;
        }
    }
    
    void EnableMetalPerformanceShaders()
    {
        // Metal Performance Shaders 활용
        // 이미지 처리, 머신러닝 등에 GPU 가속 사용
        Debug.Log("Metal Performance Shaders 활성화");
        
        // 앱인토스에 Metal 최적화 적용 알림
        AppsInToss.ReportOptimizationApplied("metal_performance_shaders", "iOS Metal API 최적화");
    }
}
```

***

## 3. iOS 메모리 관리

### ARC 호환 메모리 관리

```c#
public class iOSMemoryManager : MonoBehaviour
{
    [Header("iOS 메모리 설정")]
    public long maxMemoryUsageMB = 180; // iOS 권장 제한 (Android보다 낮음)
    public bool enableAutoMemoryCleanup = true;
    public float memoryCheckInterval = 5f;
    
    [Header("메모리 압박 대응")]
    public bool enableMemoryWarningResponse = true;
    public bool autoReduceQualityOnWarning = true;
    
    private long lastMemoryUsage = 0;
    private int memoryWarningCount = 0;
    
    void Start()
    {
        #if UNITY_IOS
        InitializeiOSMemoryManagement();
        #endif
    }
    
    void InitializeiOSMemoryManagement()
    {
        // iOS 메모리 경고 이벤트 등록
        Application.lowMemory += OnLowMemoryWarning;
        
        // 정기적인 메모리 체크
        if (enableAutoMemoryCleanup)
        {
            InvokeRepeating(nameof(CheckMemoryUsage), memoryCheckInterval, memoryCheckInterval);
        }
        
        Debug.Log("iOS 메모리 관리 시스템 초기화");
    }
    
    void CheckMemoryUsage()
    {
        long currentMemory = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(false);
        long currentMemoryMB = currentMemory / (1024 * 1024);
        
        // 메모리 사용량 급증 감지
        if (lastMemoryUsage > 0)
        {
            long memoryDelta = currentMemory - lastMemoryUsage;
            long deltaMB = memoryDelta / (1024 * 1024);
            
            if (deltaMB > 10) // 10MB 이상 급증
            {
                Debug.LogWarning($"메모리 사용량 급증 감지: +{deltaMB}MB");
                TriggerMemoryCleanup();
            }
        }
        
        lastMemoryUsage = currentMemory;
        
        // iOS 메모리 제한 체크
        if (currentMemoryMB > maxMemoryUsageMB)
        {
            Debug.LogWarning($"iOS 메모리 사용량 초과: {currentMemoryMB}MB > {maxMemoryUsageMB}MB");
            TriggerAggressiveMemoryCleanup();
        }
        
        // 앱인토스에 메모리 사용량 리포트
        AppsInToss.ReportMemoryUsage(currentMemoryMB, "iOS");
    }
    
    void OnLowMemoryWarning()
    {
        memoryWarningCount++;
        Debug.LogWarning($"iOS 메모리 경고 #{memoryWarningCount}");
        
        if (enableMemoryWarningResponse)
        {
            RespondToMemoryWarning();
        }
        
        // 앱인토스에 메모리 경고 리포트
        AppsInToss.ReportPerformanceIssue("ios_memory_warning", memoryWarningCount);
    }
    
    void RespondToMemoryWarning()
    {
        // 즉시 메모리 정리
        TriggerAggressiveMemoryCleanup();
        
        // 품질 설정 자동 조정
        if (autoReduceQualityOnWarning)
        {
            ReduceQualitySettings();
        }
        
        // 백그라운드 작업 중단
        StopBackgroundTasks();
    }
    
    void TriggerMemoryCleanup()
    {
        // 가벼운 메모리 정리
        System.GC.Collect();
        
        // 사용하지 않는 에셋 언로드
        Resources.UnloadUnusedAssets();
        
        Debug.Log("iOS 메모리 정리 수행");
    }
    
    void TriggerAggressiveMemoryCleanup()
    {
        // 적극적인 메모리 정리
        System.GC.Collect();
        System.GC.WaitForPendingFinalizers();
        System.GC.Collect();
        
        // 모든 사용하지 않는 에셋 언로드
        Resources.UnloadUnusedAssets();
        
        // 에셋 번들 캐시 정리
        if (AppsInTossAssetBundleManager.Instance != null)
        {
            AppsInTossAssetBundleManager.Instance.UnloadUnusedBundles();
        }
        
        // 텍스처 캐시 정리
        Caching.ClearCache();
        
        Debug.Log("iOS 적극적 메모리 정리 수행");
    }
    
    void ReduceQualitySettings()
    {
        var deviceTier = iOSDeviceDetector.GetCurrentDeviceTier();
        
        // 기기 등급을 한 단계 낮춤
        switch (deviceTier)
        {
            case iOSDeviceTier.HighEnd:
                ApplyQualitySettings(iOSDeviceTier.MidHigh);
                break;
            case iOSDeviceTier.MidHigh:
                ApplyQualitySettings(iOSDeviceTier.MidRange);
                break;
            case iOSDeviceTier.MidRange:
                ApplyQualitySettings(iOSDeviceTier.LowEnd);
                break;
            case iOSDeviceTier.LowEnd:
                ApplyMinimalQualitySettings();
                break;
        }
        
        Debug.Log($"메모리 경고로 인한 품질 설정 하향: {deviceTier}");
    }
    
    void ApplyQualitySettings(iOSDeviceTier targetTier)
    {
        switch (targetTier)
        {
            case iOSDeviceTier.HighEnd:
                QualitySettings.masterTextureLimit = 0;
                QualitySettings.shadowDistance = 150f;
                Application.targetFrameRate = 60;
                break;
                
            case iOSDeviceTier.MidHigh:
                QualitySettings.masterTextureLimit = 1;
                QualitySettings.shadowDistance = 100f;
                Application.targetFrameRate = 60;
                break;
                
            case iOSDeviceTier.MidRange:
                QualitySettings.masterTextureLimit = 1;
                QualitySettings.shadowDistance = 50f;
                Application.targetFrameRate = 30;
                break;
                
            case iOSDeviceTier.LowEnd:
                QualitySettings.masterTextureLimit = 2;
                QualitySettings.shadowDistance = 25f;
                Application.targetFrameRate = 30;
                break;
        }
    }
    
    void ApplyMinimalQualitySettings()
    {
        // 최소 품질 설정 (생존 모드)
        QualitySettings.masterTextureLimit = 3;
        QualitySettings.shadowDistance = 0f;
        QualitySettings.shadows = ShadowQuality.Disable;
        QualitySettings.antiAliasing = 0;
        Application.targetFrameRate = 20;
        
        Debug.Log("최소 품질 설정 적용");
    }
    
    void StopBackgroundTasks()
    {
        // 백그라운드 로딩 중단
        if (AppsInTossLoadingManager.Instance != null)
        {
            AppsInTossLoadingManager.Instance.PauseBackgroundLoading();
        }
        
        // 불필요한 업데이트 중단
        var backgroundUpdaters = FindObjectsOfType<MonoBehaviour>()
            .Where(mb => mb.GetType().Name.Contains("Background") || 
                         mb.GetType().Name.Contains("Update"))
            .ToArray();
        
        foreach (var updater in backgroundUpdaters)
        {
            updater.enabled = false;
        }
        
        Debug.Log("백그라운드 작업 중단");
    }
    
    void OnApplicationPause(bool pauseStatus)
    {
        if (pauseStatus)
        {
            // 백그라운드 진입 시 메모리 정리
            TriggerMemoryCleanup();
            
            // iOS 백그라운드 제한에 대비한 최소화
            MinimizeMemoryFootprint();
        }
    }
    
    void MinimizeMemoryFootprint()
    {
        // 백그라운드에서 메모리 사용량 최소화
        
        // 오디오 중단
        AudioListener.pause = true;
        
        // 애니메이션 중단
        var animators = FindObjectsOfType<Animator>();
        foreach (var animator in animators)
        {
            animator.enabled = false;
        }
        
        // 파티클 시스템 중단
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        foreach (var ps in particleSystems)
        {
            ps.Pause();
        }
        
        Debug.Log("iOS 백그라운드 메모리 최소화 적용");
    }
    
    void OnApplicationFocus(bool hasFocus)
    {
        if (hasFocus)
        {
            // 포그라운드 복귀 시 시스템 복원
            RestoreFromBackground();
        }
    }
    
    void RestoreFromBackground()
    {
        // 백그라운드에서 복귀 시 시스템 복원
        AudioListener.pause = false;
        
        var animators = FindObjectsOfType<Animator>();
        foreach (var animator in animators)
        {
            animator.enabled = true;
        }
        
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        foreach (var ps in particleSystems)
        {
            ps.Play();
        }
        
        Debug.Log("iOS 포그라운드 복귀 - 시스템 복원");
    }
}
```

***

## 4. iOS 배터리 최적화

### 전력 효율성 개선

```c#
public class iOSBatteryOptimizer : MonoBehaviour
{
    [Header("배터리 최적화 설정")]
    public bool enableBatteryOptimization = true;
    public bool adaptiveFrameRate = true;
    public bool thermalManagement = true;
    
    [Header("전력 임계값")]
    [Range(0f, 1f)]
    public float lowBatteryThreshold = 0.2f; // 20%
    [Range(0f, 1f)] 
    public float criticalBatteryThreshold = 0.1f; // 10%
    
    private float lastBatteryLevel = 1f;
    private bool isLowPowerMode = false;
    
    void Start()
    {
        #if UNITY_IOS
        InitializeBatteryOptimization();
        #endif
    }
    
    void InitializeBatteryOptimization()
    {
        if (enableBatteryOptimization)
        {
            InvokeRepeating(nameof(MonitorBatteryStatus), 30f, 30f); // 30초마다 체크
            
            if (thermalManagement)
            {
                InvokeRepeating(nameof(CheckThermalState), 60f, 60f); // 1분마다 체크
            }
        }
        
        Debug.Log("iOS 배터리 최적화 시스템 초기화");
    }
    
    void MonitorBatteryStatus()
    {
        float currentBattery = SystemInfo.batteryLevel;
        
        if (currentBattery < 0) return; // 배터리 정보 없음
        
        // 배터리 수준에 따른 최적화
        if (currentBattery <= criticalBatteryThreshold && !isLowPowerMode)
        {
            EnableCriticalPowerMode();
        }
        else if (currentBattery <= lowBatteryThreshold && !isLowPowerMode)
        {
            EnableLowPowerMode();
        }
        else if (currentBattery > lowBatteryThreshold + 0.1f && isLowPowerMode)
        {
            DisableLowPowerMode();
        }
        
        // 배터리 소모율 계산
        if (lastBatteryLevel > 0)
        {
            float batteryDrain = lastBatteryLevel - currentBattery;
            if (batteryDrain > 0.02f) // 2% 이상 급격한 소모
            {
                Debug.LogWarning($"배터리 급속 소모 감지: -{batteryDrain * 100:F1}%");
                OptimizePowerConsumption();
            }
        }
        
        lastBatteryLevel = currentBattery;
        
        // 앱인토스에 배터리 상태 리포트
        AppsInToss.ReportBatteryStatus(currentBattery, isLowPowerMode);
    }
    
    void EnableLowPowerMode()
    {
        isLowPowerMode = true;
        
        // 프레임레이트 제한
        Application.targetFrameRate = 20;
        
        // 품질 설정 하향
        QualitySettings.masterTextureLimit = 2;
        QualitySettings.shadowDistance = 25f;
        QualitySettings.shadows = ShadowQuality.HardOnly;
        
        // 파티클 효과 감소
        ReduceParticleEffects(0.5f);
        
        // 백그라운드 업데이트 빈도 감소
        ReduceUpdateFrequency();
        
        Debug.Log("iOS 저전력 모드 활성화");
        AppsInToss.ReportOptimizationApplied("low_power_mode", "iOS 배터리 절약 모드");
    }
    
    void EnableCriticalPowerMode()
    {
        isLowPowerMode = true;
        
        // 극도로 제한적인 설정
        Application.targetFrameRate = 15;
        
        // 최소 품질
        QualitySettings.masterTextureLimit = 3;
        QualitySettings.shadowDistance = 0f;
        QualitySettings.shadows = ShadowQuality.Disable;
        QualitySettings.antiAliasing = 0;
        
        // 효과 대부분 비활성화
        DisableNonEssentialEffects();
        
        Debug.LogWarning("iOS 긴급 절전 모드 활성화");
        AppsInToss.ReportOptimizationApplied("critical_power_mode", "iOS 긴급 배터리 절약");
    }
    
    void DisableLowPowerMode()
    {
        isLowPowerMode = false;
        
        // 정상 설정 복원
        var deviceTier = iOSDeviceDetector.GetCurrentDeviceTier();
        RestoreNormalSettings(deviceTier);
        
        Debug.Log("iOS 저전력 모드 해제");
    }
    
    void RestoreNormalSettings(iOSDeviceTier deviceTier)
    {
        switch (deviceTier)
        {
            case iOSDeviceTier.HighEnd:
                Application.targetFrameRate = 60;
                QualitySettings.masterTextureLimit = 0;
                QualitySettings.shadowDistance = 150f;
                break;
                
            case iOSDeviceTier.MidHigh:
                Application.targetFrameRate = 60;
                QualitySettings.masterTextureLimit = 1;
                QualitySettings.shadowDistance = 100f;
                break;
                
            case iOSDeviceTier.MidRange:
                Application.targetFrameRate = 30;
                QualitySettings.masterTextureLimit = 1;
                QualitySettings.shadowDistance = 50f;
                break;
                
            case iOSDeviceTier.LowEnd:
                Application.targetFrameRate = 30;
                QualitySettings.masterTextureLimit = 2;
                QualitySettings.shadowDistance = 25f;
                break;
        }
        
        // 효과 복원
        RestoreEffects();
    }
    
    void CheckThermalState()
    {
        // iOS 열 상태 체크 (앱인토스 네이티브 API 사용)
        string thermalState = AppsInToss.GetThermalState();
        
        switch (thermalState.ToLower())
        {
            case "normal":
                // 정상 상태 - 추가 조치 불필요
                break;
                
            case "fair":
                // 약간 따뜻함 - 경미한 최적화
                OptimizeForThermal(ThermalLevel.Fair);
                break;
                
            case "serious":
                // 뜨거움 - 적극적 최적화
                OptimizeForThermal(ThermalLevel.Serious);
                break;
                
            case "critical":
                // 과열 - 긴급 최적화
                OptimizeForThermal(ThermalLevel.Critical);
                break;
        }
    }
    
    enum ThermalLevel
    {
        Normal,
        Fair, 
        Serious,
        Critical
    }
    
    void OptimizeForThermal(ThermalLevel level)
    {
        Debug.LogWarning($"iOS 열 관리 최적화 적용: {level}");
        
        switch (level)
        {
            case ThermalLevel.Fair:
                // 경미한 최적화
                Application.targetFrameRate = Mathf.Min(Application.targetFrameRate, 45);
                QualitySettings.lodBias = 0.8f;
                break;
                
            case ThermalLevel.Serious:
                // 적극적 최적화
                Application.targetFrameRate = 30;
                QualitySettings.masterTextureLimit = Mathf.Max(QualitySettings.masterTextureLimit, 1);
                QualitySettings.shadowDistance *= 0.7f;
                ReduceParticleEffects(0.7f);
                break;
                
            case ThermalLevel.Critical:
                // 긴급 최적화
                Application.targetFrameRate = 20;
                QualitySettings.masterTextureLimit = 2;
                QualitySettings.shadowDistance *= 0.5f;
                QualitySettings.shadows = ShadowQuality.Disable;
                DisableNonEssentialEffects();
                break;
        }
        
        AppsInToss.ReportPerformanceIssue($"thermal_{level.ToString().ToLower()}", level.ToString());
    }
    
    void OptimizePowerConsumption()
    {
        // 즉시 전력 소모 최적화
        
        // CPU 사용률 감소
        Time.fixedDeltaTime = 0.04f; // 물리 업데이트 빈도 감소
        
        // GPU 부하 감소
        QualitySettings.pixelLightCount = 1;
        QualitySettings.shadowCascades = 2;
        
        // 불필요한 업데이트 중단
        var inefficientComponents = FindObjectsOfType<MonoBehaviour>()
            .Where(mb => mb.enabled && IsInefficient(mb))
            .ToArray();
        
        foreach (var component in inefficientComponents)
        {
            component.enabled = false;
        }
        
        Debug.Log("전력 소모 최적화 적용");
    }
    
    bool IsInefficient(MonoBehaviour component)
    {
        // 전력 소모가 큰 컴포넌트 식별
        string typeName = component.GetType().Name;
        
        return typeName.Contains("Effect") || 
               typeName.Contains("Animation") || 
               typeName.Contains("Particle") ||
               typeName.Contains("Reflection");
    }
    
    void ReduceParticleEffects(float intensity)
    {
        var particleSystems = FindObjectsOfType<ParticleSystem>();
        
        foreach (var ps in particleSystems)
        {
            var emission = ps.emission;
            var rateOverTime = emission.rateOverTime;
            rateOverTime.constant *= intensity;
            emission.rateOverTime = rateOverTime;
            
            var main = ps.main;
            main.maxParticles = Mathf.RoundToInt(main.maxParticles * intensity);
        }
    }
    
    void ReduceUpdateFrequency()
    {
        // 업데이트 빈도가 높은 컴포넌트들의 빈도 감소
        var frequentUpdaters = FindObjectsOfType<MonoBehaviour>()
            .Where(mb => HasFrequentUpdate(mb))
            .ToArray();
        
        foreach (var updater in frequentUpdaters)
        {
            // 업데이트 간격 조정 (구체적 구현은 컴포넌트별로 다름)
            AdjustUpdateFrequency(updater);
        }
    }
    
    bool HasFrequentUpdate(MonoBehaviour component)
    {
        // 빈번한 업데이트를 하는 컴포넌트 식별
        return component.GetType().GetMethod("Update") != null ||
               component.GetType().GetMethod("LateUpdate") != null ||
               component.GetType().GetMethod("FixedUpdate") != null;
    }
    
    void AdjustUpdateFrequency(MonoBehaviour component)
    {
        // 컴포넌트별 업데이트 빈도 조정
        // 실제 구현은 각 컴포넌트의 특성에 따라 다름
    }
    
    void DisableNonEssentialEffects()
    {
        // 필수적이지 않은 효과들 비활성화
        var effects = FindObjectsOfType<ParticleSystem>();
        foreach (var effect in effects)
        {
            if (!IsEssentialEffect(effect))
            {
                effect.gameObject.SetActive(false);
            }
        }
        
        var audioSources = FindObjectsOfType<AudioSource>();
        foreach (var audio in audioSources)
        {
            if (!IsEssentialAudio(audio))
            {
                audio.enabled = false;
            }
        }
    }
    
    bool IsEssentialEffect(ParticleSystem effect)
    {
        // 필수 효과인지 판단
        return effect.name.Contains("Essential") || 
               effect.name.Contains("UI") ||
               effect.transform.parent?.name.Contains("Critical") == true;
    }
    
    bool IsEssentialAudio(AudioSource audio)
    {
        // 필수 오디오인지 판단
        return audio.name.Contains("UI") || 
               audio.name.Contains("Critical") ||
               audio.name.Contains("Toss"); // 앱인토스 관련 사운드
    }
    
    void RestoreEffects()
    {
        // 비활성화된 효과들 복원
        var disabledEffects = FindObjectsOfType<ParticleSystem>(true)
            .Where(ps => !ps.gameObject.activeInHierarchy)
            .ToArray();
        
        foreach (var effect in disabledEffects)
        {
            effect.gameObject.SetActive(true);
        }
        
        var disabledAudio = FindObjectsOfType<AudioSource>(true)
            .Where(audio => !audio.enabled)
            .ToArray();
        
        foreach (var audio in disabledAudio)
        {
            audio.enabled = true;
        }
    }
    
    // 공개 API
    public bool IsInLowPowerMode()
    {
        return isLowPowerMode;
    }
    
    public float GetBatteryLevel()
    {
        return SystemInfo.batteryLevel;
    }
    
    public void ForceLowPowerMode(bool enable)
    {
        if (enable && !isLowPowerMode)
        {
            EnableLowPowerMode();
        }
        else if (!enable && isLowPowerMode)
        {
            DisableLowPowerMode();
        }
    }
}
```

iOS는 엄격한 메모리 관리와 전력 효율성이 요구돼요.\
Metal API 활용과 ARC 호환 메모리 관리, 적응적 품질 조정을 통해 최적의 iOS 경험을 제공하세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/development/client/ios.md'
description: >-
  React Native 앱인토스 개발을 위한 iOS 환경 설정 가이드입니다. Xcode 설치, Command Line Tools 설정,
  시뮬레이터 실행 및 샌드박스 앱 설치 방법을 확인하세요.
---

# iOS 환경설정

React Native 앱을 개발하기 위해 **iOS 개발 환경 설정 방법**을 안내해요.

::: tip iOS의 서드파티 쿠키 차단 정책
iOS/iPadOS 13.4 이상에서는 **서드파티 쿠키가 완전히 차단**돼요.\
앱인토스 도메인이 아닌 파트너사 도메인에서 **쿠키 기반 로그인**을 구현하면 정상 동작하지 않아요.

* 공식 안내: [Full third-party cookie blocking](https://webkit.org/blog/10218/full-third-party-cookie-blocking-and-more/)
* **토큰 기반 등 대체 인증 방식**을 적용해주세요.
  :::

## 1. XCode 설치

iOS에서 React Native 앱을 테스트하려면 iOS 시뮬레이터가 필요해요. 시뮬레이터를 사용하려면 먼저 **Xcode**를 설치해 주세요.

* [XCode 최신버전 다운로드 링크](https://apps.apple.com/kr/app/xcode/id497799835?mt=12)를 클릭해서 Mac App Store에서 설치해 주세요.

## 2. iOS 컴포넌트 설치

Xcode를 처음 설치한 경우, iOS 시뮬레이터를 사용하려면 iOS 15 이상의 컴포넌트를 추가로 설치해야 해요.\
아래와 같은 창이 표시되면 iOS를 선택해 설치해 주세요.

## 3. XCode Command Line Tools 설치

Xcode를 제대로 사용하려면 **Xcode Command Line Tools**가 설치되어야 하며, **Xcode 본체와 버전이 동일해야** 해요. 아래 단계를 따라 확인해 보세요.

**XCode 버전 확인하기**

1. XCode를 열고 상단 메뉴에서 \[XCode] > \[About XCode] 를 클릭하세요.
2. 화면에 표시된 버전을 확인하세요.

**XCode Command Line Tools 버전 확인하기**

1. XCode에서 \[XCode] > \[Settings] 를 클릭하세요.
2. \[Locations] 탭으로 이동한 뒤, Command Line Tools 항목의 버전을 확인하세요.

## 4. 시뮬레이터 실행

Xcode 설치와 설정이 끝났다면 시뮬레이터를 실행해서 테스트 환경이 준비되었는지 확인해 보세요.

1. XCode 상단 메뉴에서 \[XCode] > \[Open Developer Tool] > \[Simulator] 를 선택하세요.
2. 실행된 시뮬레이터에서 iOS 15 이상의 버전을 사용할 수 있는지 확인하세요.

::: details **시뮬레이터가 보이지 않는다면?**
시뮬레이터가 실행되지 않거나 보이지 않을 경우, 아래 단계를 따라 실행해 보세요.

1. Simulator 앱을 열어요.
2. 상단 메뉴에서 \[File] > \[Open Simulator] 를 클릭하세요.
3. iOS 15 이상 버전을 선택한 뒤, 원하는 기기를 선택하세요.

## 5. 앱인토스 샌드박스 앱 설치

### 1. 앱인토스 샌드박스 앱 다운로드 받기

* [앱인토스 샌드박스 앱 다운로드](/development/test/sandbox)

### 2. 앱 설치하기

1. 다운로드한 **앱인토스 샌드박스 앱 파일을 시뮬레이터 화면으로 드래그 앤드 드롭**하세요.
2. 설치가 완료되면 앱이 시뮬레이터 홈 화면에 표시돼요.

앱 설치 후 완료되기까지 약간의 시간이 걸릴 수 있어요. 잠시 기다려 주세요.

## 6. 실기기 설치

앱인토스 샌드박스 앱은 **앱스토어에서 다운로드받을 수 있어요.**\
아래 가이드를 따라 iOS 실기기에 설치해 주세요.

* [앱인토스 샌드박스 앱 다운로드](/development/test/sandbox)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/KeyboardAboveView.md
---

# KeyboardAboveView

키보드가 화면에 나타날 때 자식 컴포넌트를 키보드 위로 자동으로 올려주는 컴포넌트예요.
예를 들어, 텍스트 입력 중 "전송" 버튼을 키보드 위에 고정시키고 싶을 때 유용해요.

## 시그니처

```typescript
function KeyboardAboveView({ style, children, ...props }: ComponentProps<typeof View>): ReactElement;
```

### 파라미터

### 반환 값

## 예제

### 키보드 위로 요소를 올리기

```tsx
import { ScrollView, TextInput, View, Text } from 'react-native';
import { KeyboardAboveView } from '@granite-js/react-native';

function KeyboardAboveViewExample() {
  return (
    <>
      <ScrollView>
        <TextInput placeholder="placeholder" />
      </ScrollView>

      <KeyboardAboveView>
        <View style={{ width: '100%', height: 50, backgroundColor: 'yellow' }}>
          <Text>Keyboard 위에 있어요.</Text>
        </View>
      </KeyboardAboveView>
    </>
  );
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/listHeader.md'
description: 토스 디자인 시스템(TDS)의 ListHeader 컴포넌트 가이드입니다. 목록 헤더 구성 및 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

`ListHeader` 컴포넌트는 사용자가 특정 동작을 실행하거나 추가 정보로 안내될 수 있는 헤더 UI 요소예요. 페이지나 섹션의 상단에 배치되어 사용자에게 제목, 설명, 그리고 상호작용 가능한 요소를 제공할 수 있어요. 주로 제목, 오른쪽의 부가 콘텐츠, 보조 설명을 포함해요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/list-header/)

![List Header](/assets/Thumbnail-ListHeader.Bns9QJRQ.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/list.md'
description: 토스 디자인 시스템(TDS)의 ListRow 컴포넌트 가이드입니다. 리스트 아이템 구성 및 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

`ListRow` 컴포넌트는 리스트 형태의 UI를 구성할 때 사용해요. `left`, `contents`, `right` 세 영역으로 나뉘어 있으며, 각 영역에 아이콘, 텍스트, 이미지를 추가해 직관적인 리스트 아이템을 만들 수 있어요.
또한 터치 효과와 화살표 속성으로 사용자가 리스트 아이템의 동작을 쉽게 예측할 수 있고, 비활성화 속성을 사용해 특정 항목을 비활성화할 수도 있어요.
이를 통해 상황에 맞춰 다양한 리스트 UI를 구성할 수 있어요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/ListRow/list-row-overview/)

![list](/assets/Thumbnail-ListRow.d_7A0vSe.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/development/llms.md'
description: >-
  IDE에서 AI가 더 정확한 코드를 생성할 수 있도록 컨텍스트 파일을 사용하는 방법을 안내합니다. llms.txt, 문서 URL, @docs
  기능을 활용하여 프로젝트 정보를 AI에게 주입해 보세요.
---

# LLMs 사용하기

AI가 프로젝트의 문맥을 이해하면 더 정확한 코드와 답변을 제공할 수 있어요.\
Cursor에서는 **문서(URL)** 또는 **llms.txt** 파일을 등록해 AI가 참고할 컨텍스트를 제공할 수 있으며,\
추가로 **MCP 서버를 사용하면** 훨씬 깊은 수준의 프로젝트 정보를 AI가 활용할 수 있어요.

::: tip 왜 컨텍스트가 필요한가요?
AI는 기본적으로 프로젝트의 도메인 지식을 알고 있지 않아요.\
SDK 사용법, API 구조, 에러 규칙 등 필요한 정보를 함께 제공하면 **정확도**와 **일관성**이 크게 향상돼요.
:::

이 문서는 **Cursor IDE**를 기준으로 설명해요.\
그렇지만 VSCode 등 다른 IDE에서도 유사한 방식으로 활용할 수 있어요.

## 1. 문서 URL 등록하기 (@docs)

앱인토스 문서를 AI에 연결하려면 Cursor의 **Docs 인덱싱** 기능을 사용하세요.\
아래 단계에 따라 필요한 문서를 빠르게 등록할 수 있어요.

1. Cursor 화면 우측 상단의 **톱니바퀴(⚙️)** 아이콘을 클릭하세요.
2. 왼쪽 메뉴에서 **Indexing & Docs**를 선택하세요.
3. 화면 하단의 **Docs** 섹션으로 이동하세요.
4. `+Add Doc` 버튼을 클릭해 문서를 추가하세요.

### 추가할 수 있는 문서 URL

| 유형                           | 설명                                                                                             | URL                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| **기본 문서 (권장)**           | 앱인토스 기능을 사용하는 데 필요한 핵심 정보들이 포함돼 있어요.                                  | `https://developers-apps-in-toss.toss.im/llms.txt`              |
| **모든 기능 포함 문서 (Full)** | 전체 문서를 포함한 확장 버전이에요.컨텍스트는 풍부하지만 **토큰 소모량이 증가**할 수 있어요. | `https://developers-apps-in-toss.toss.im/llms-full.txt`         |
| **예제 전용 문서**             | 앱인토스 예제 코드만 빠르게 참고하고 싶을 때 사용해요.                                           | `https://developers-apps-in-toss.toss.im/tutorials/examples.md` |
| **TDS 문서 (WebView)**         | TDS WebView 관련 정보가 포함돼 있어요.                                                           | `https://tossmini-docs.toss.im/tds-mobile/llms-full.txt`        |
| **TDS 문서 (React Native)**    | TDS React Native 정보가 포함돼 있어요.                                                           | `https://tossmini-docs.toss.im/tds-react-native/llms-full.txt`  |

![llms-1](/assets/llms-1.Ddl9380t.png)

## 2. 문서를 기반으로 AI 활용하기

문서를 등록하면 AI가 해당 문서를 기반으로 더 정확한 답변을 생성할 수 있어요.\
특히 Cursor에서는 `@docs` 명령을 사용하여 *지정된 문서를 우선적으로 참고*하도록 요청할 수 있어요.

```
@docs 앱인토스 인앱광고 샘플 코드 작성해줘
```

::: tip @docs는 언제 사용하나요?

* SDK처럼 **정확한 규칙 기반 코드**가 필요한 경우
* 문서 기반 의존도가 높은 기능을 사용할 때
* AI에게 “문서를 기반으로 답변해 달라”고 명확히 전달하고 싶을 때\
  `@docs`를 사용하면 AI는 문서를 우선적으로 참고해 더 안정적인 답변을 제공합니다.
  :::

AI는 `@docs` 없이도 문서를 자동으로 참고하지만,\
**정밀한 문맥 이해가 필요할 때는 `@docs`를 사용해 명시적으로 지시하는 것이 좋아요.**

## 3. MCP(Model Context Protocol) 서버 사용하기

Cursor는 **MCP(Model Context Protocol)** 를 지원해요.\
MCP는 IDE와 AI 모델 사이에서 프로젝트 정보를 더 구조적으로 전달하는 표준 프로토콜로,\
AI가 코드베이스의 맥락을 더 깊이 이해할 수 있도록 도와주는 역할을 해요.

앱인토스는 다양한 **SDK와 API(인앱 광고, 인앱 결제, 딥링크 등)** 를 제공하고 있는데,\
MCP를 함께 사용하면 다음과 같은 장점이 있어요:

* AI가 앱인토스 SDK 문서, API 스펙, 설정 파일을 자동으로 참조
* 인앱 광고, 인앱 결제 등 앱인토스의 기능을 더 짧은 코드로 빠르게 구현
* 잘못된 API 사용이나 누락된 파라미터 등을 AI가 조기에 감지
* 프로젝트 전체 구조(폴더, 설정, 자원 파일 등)를 기반으로 정확한 자동 생성 코드 구현

즉, MCP를 사용하면

> **앱인토스가 제공하는 기능을 훨씬 쉽게, 더 정확하게 구현할 수 있는 개발 환경을 만들 수 있어요.**\
> 기존 문서 기반 컨텍스트보다 더 깊은 통합을 제공한다는 점이 핵심입니다.

### 설치하기

::: code-group

```[MacOS]
brew tap toss/tap && brew install ax
```

```[Windows]
scoop bucket add toss  https://github.com/toss/scoop-bucket.git
scoop install ax
```

:::

### Cursor에 MCP 서버 연결하기

버튼이 작동하지 않을 경우, `.cursor/mcp.json` 파일을 생성하거나 수정해 아래 내용을 추가하세요.

```
{
 "mcpServers": {
   "apps-in-toss": {
     "command": "ax",
     "args": [
       "mcp", "start"
     ]
   }
 }
}
```

### Claude Code에서 MCP 연결하기

```
claude mcp add --transport stdio ax mcp start
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/Lottie.md
---

# Lottie

`Lottie` 컴포넌트를 사용하면 Lottie JSON 파일을 불러와 애니메이션을 재생할 수 있어요.\
높이를 필수로 지정해야 레이아웃 시프트(Layout Shift)를 방지할 수 있어요.

## 시그니처

```typescript
function Lottie({ width, maxWidth, height, src, autoPlay, speed, style, onAnimationFailure, ...props }: Props): import("react/jsx-runtime").JSX.Element;
```

### 파라미터

### 반환 값

## 예제

### Lottie 애니메이션 렌더링하기

아래 예시는 Lottie 애니메이션을 불러와 재생하고,\
애니메이션 로드 실패 및 종료 시 각각 로그를 출력하는 방법을 보여줘요.

```tsx
import { Lottie } from '@granite-js/react-native';

function LottieExample() {
 return (
   <Lottie
     height={100}
     src="https://my-lottie-animation-url.com"
     autoPlay={true}
     loop={false}
     onAnimationFailure={() => {
       console.log('Animation Failed');
     }}
     onAnimationFinish={() => {
       console.log('Animation Finished');
     }}
   />
 );
```

## 참고사항

* `height`는 반드시 지정해야 레이아웃 시프트가 발생하지 않아요.
* 애니메이션이 정상적으로 동작하지 않으면 `onAnimationFailure` 콜백을 통해 에러 로그를 확인할 수 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/style-utils/margin.md
---

# margin

`margin`은 컴포넌트의 **외부 여백**을 간결하게 지정하는 유틸이에요.\
가로(`x`), 세로(`y`), 개별 방향(`top`, `right`, `bottom`, `left`)으로 숫자 값을 줄 수 있고,\
자주 쓰는 고정 값 프리셋(`x8`, `y16` 등)도 바로 사용할 수 있어요.

## 시그니처

```typescript
margin: BoxSpacing
```

## 프로퍼티

아래 항목들은 모두 스타일 객체를 반환하며, 컴포넌트의 style에 그대로 전달해 사용해요.
숫자 단위는 React Native의 일반적인 숫자 단위(dp)를 따릅니다.

## 프리셋

동일 패턴의 **고정 값 프리셋**을 제공해요. (지원 값 예: `4 | 8 | 12 | 16 | 24 | 32`)

* `margin.x8` → `{ marginHorizontal: 8 }`
* `margin.y16` → `{ marginVertical: 16 }`
* `margin.top24`, `margin.right4`, `margin.bottom12`, `margin.left32` 등

## 예제

#### 가로·세로 프리셋 + 임의 값 혼합 사용

```tsx
import { View, Text } from 'react-native';
import { margin } from '@granite-js/react-native';

function Component() {
  return (
    <View>
      <View style={margin.x8}>
        <Text>가로 여백이 있어요</Text>
      </View>

      <View style={margin.y8}>
        <Text>세로 여백이 있어요</Text>
      </View>

      <View style={margin.bottom(100)}>
        <Text>아래에 100만큼의 여백이 있어요</Text>
      </View>
    </View>
  );
}
```

#### StyleSheet와 함께 쓰기

```tsx
import { View, Text, StyleSheet } from 'react-native';
import { margin } from '@granite-js/react-native';

const styles = StyleSheet.create({
  card: {
    ...margin.y16,          // 세로 16
    ...margin.x12,          // 가로 12
  },
  footer: {
    ...margin.top24,        // 위 24
    ...margin.left8,        // 왼 8
  },
});

function Card() {
  return (
    <View style={styles.card}>
      <Text>콘텐츠</Text>
      <View style={styles.footer}>
        <Text>푸터</Text>
      </View>
    </View>
  );
}
```

## 참고사항

* `margin.*`은 `React Native`의 `margin*` 스타일을 **얇게 감싼 헬퍼**예요.
* 프리셋은 팀 내 디자인 간격 체계를 빠르게 일관 적용하기 좋고,\
  함수형(`margin.top(6)`)은 비정형 간격이 필요할 때 유용해요.

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/navigation.md'
description: 토스 디자인 시스템(TDS)의 Navigation 컴포넌트 가이드입니다. 화면 상단 네비게이션 바 구성 및 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

네비게이션은 화면의 최상단에서 현재 어떤 서비스를 이용하고 있는지 안내하고 서비스의 기능이나 신고/문의하기, 토스로 되돌아가는 기능을 포함합니다.

앱인토스 브랜드 인지에 중요한 역할을 하는 영역으로 모든 화면의 상단에 반드시 배치됩니다.

[자세히 알아보기 >](/bedrock/reference/framework/UI/NavigationBar.md)

![Navigation](/assets/Thumbnail-Navigation.CWZT6Ky5.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/marketing/open-graph.md'
---
# OG 이미지

## OG 이미지(Open Graph) 란?

Open Graph(이하 ‘OG 이미지) 는 미니앱의 공유 링크가 카카오톡 등 소셜 플랫폼에서 공유될 때 함께 보이는 대표 이미지로, 사용자가 가장 먼저 인지하는 시각적 요소예요.\
앱인토스에서는 파트너사에서 보다 효과적으로 마케팅을 할 수 있게 OG 이미지 기능을 제공하고,\
파트너사는 미니앱의 링크를 공유하면 자동으로 나타나는 썸네일 이미지를 미리 설정할 수 있어요.

![open graph 1](/assets/open_graph_1.D1ERRA3V.png)

## OG 이미지를 사용하면 무엇이 좋은가요?

**① 미니앱의 인지도를 높일 수 있어요.**

* 미니앱의 스타일이나 메시지를 담은 이미지를 노출할 수 있어서, 사용자가 링크만 보고도 어떤 서비스인지 쉽게 알 수 있어요.

**② 미니앱에 접속하게 되는 사용자가 증가할 수 있어요.**

* 시각적으로 돋보이는 이미지가 함께 노출되면 사용자가 링크를 눌러볼 확률이 높아지고 미니앱 접속으로 이어질 수 있어요.

**③ 전달하고 싶은 정보를 더 효과적으로 보여줄 수 있어요.**

* 이벤트, 캠페인 등 알리고자 하는 내용을 이미지 안에 담아 직관적으로 전달할 수 있어요.

***

## OG 이미지 규칙

아래 내용은 OG 이미지를 사용할 때 꼭 지켜주셔야 하는 규칙이에요.\
모니터링 등을 통해 규칙을 어긴 사실이 확인 되었을 때는 **수정 조치 등 제한이 될 수 있으니 꼭 지켜주세요.**

### 사이즈는 1200 \* 600 으로 만들어주세요.

![open graph 2](/assets/open_graph_2.DatTL5vn.png)

### 고화질 이미지를 사용하세요.

선명한 고화질 이미지를 등록해주세요.\
저화질 이미지는 전체적인 완성도를 떨어뜨리고 서비스의 인상에 부정적인 영향을 줄 수 있어요.

### 민감하거나 부적절한 용어를 포함하지 마세요.

비속어나 은어, 정치적 용어 등 자극적인 표현이 들어가지 않도록 이미지를 제작해주세요.

### 썸네일에 많은 텍스트를 배치하지 마세요.

시선을 과도하게 끄는 크기나 디자인의 텍스트는 사용이 불가해요. 텍스트가 많으면 썸네일이 복잡해질 수 있어요. 다만, 로고와 함께 사용하는 슬로건이나 이미지 이해를 돕는 보조 텍스트는 적절한 크기와 위치로 배치한다면 괜찮아요.

### 라이팅 가이드를 참고해 주세요.

토스의 보이스톤을 적용한 문구를 쓸 수 있도록 제공된 [라이팅 가이드라인](/design/ux-writing.html)을 지켜주세요.

***

## 개발하기

OG 이미지의 소개와 규칙을 확인하셨다면, 이제 실제로 미니앱에 OG 이미지를 적용해 보세요.\
[토스앱 공유 링크 만들기](/bedrock/reference/framework/공유/getTossShareLink.html) 개발 문서에서 확인할 수 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/OnAudioFocusChanged.md
---

# OnAudioFocusChanged

오디오 포커스가 변경될 때 호출되는 콜백 함수에요. `muted` 가 `false` 인 경우에 필수로 구현해야해요.

## 시그니처

```typescript
type OnAudioFocusChanged = NonNullable<VideoProperties['onAudioFocusChanged']>;
```

### 파라미터

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/카메라/OpenCameraPermissionError.md
---

# OpenCameraPermissionError

카메라 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof OpenCameraPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class OpenCameraPermissionError extends PermissionError {
    constructor();
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/overlay/useOverlay.md
---

# Overlay

오버레이 사용 방법을 안내해요.

오버레이(Overlay)는 **모달, 바텀시트, 다이얼로그 등 별도의 UI 레이어를 표시할 때** 사용하는 기능이에요.\
`useOverlay`와 `useOverlayBase` 훅을 사용하면 Overlay의 열림/닫힘 상태를 간단하고 안정적으로 제어할 수 있어요.

## 1. Overlay 제어하기 (`useOverlay`)

`useOverlay`는 Overlay의 열림(open)과 닫힘(close) 상태를 간단히 관리하는 훅이에요.\
뒤로가기 버튼으로 Overlay를 닫거나, 비동기적으로 Overlay를 제어하는 데 활용할 수 있어요.

### 시그니처

```typescript
function useOverlay(): {
    close: () => void;
    open: (overlayElement: CreateOverlayElement) => void;
};
```

### 반환 값

### 예제

```tsx
import { useOverlay } from '@apps-in-toss/framework';

 const overlay = useOverlay();

  const openBottomSheet = useCallback(() => {
    return new Promise<void>((resolve) => {
      overlay.open(({ isOpen, exit, close }) => {
        const handleClose = () => {
          close();
          resolve();
        };

        return (
          <BottomSheet
            open={isOpen}
            onClose={handleClose}
            onExited={exit}
            header={<BottomSheet.Header>BottomSheet V1 Header</BottomSheet.Header>}
            cta={<BottomSheet.CTA onPress={handleClose}>확인</BottomSheet.CTA>}
          >
            <View>
              <TextField size="classic" label="name" value="FOCUS ME" />
            </View>
          </BottomSheet>
        );
      });
    });
  }, []);
```

## 2. Overlay 생성·관리하기 (`useOverlayBase`)

`useOverlayBase`는 Dialog처럼 **선언형으로 Overlay를 관리**할 수 있는 훅이에요.
Promise 기반으로 동작해, Overlay의 닫힘 시점을 기준으로 이후 로직을 실행할 수 있어요.
이 훅을 사용하려면 `_app.tsx`에 `OverlayProvider`를 추가해야 해요.

### 시그니처

```typescript
function useOverlayBase({ exitOnUnmount }?: Options): {
    open: (overlayElement: CreateOverlayElement) => void;
    close: () => void;
};
```

### 파라미터

### 반환 값

### 예제

#### ① OverlayProvider 설정

`useOverlayBase`를 사용하기 전에 루트(App) 컴포넌트에 `OverlayProvider`를 등록해야 해요.

```tsx
// _app.tsx
import { OverlayProvider } from '@apps-in-toss/framework';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <OverlayProvider>
      <Component {...pageProps} />
    </OverlayProvider>
  )
}
```

#### ② Overlay 관리 예시

```tsx
// Page.tsx
import { useOverlayBase } from '@react-native-bedrock/core';

const overlay = useOverlayBase();
const openFooConfirmDialog = () => {
  return new Promise<boolean>(resolve => {
    overlay.open(({ isOpen, close }) => (
      <FooConfirmDialog
        open={isOpen}
        onClose={() => {
          resolve(false);
          close();
        }}
        onConfirm={() => {
          resolve(true);
          close();
        }}
      />
    ));
  });
};

await openFooConfirmDialog();
// ConfirmDialog의 confirmButton을 누르거나 onClose가 호출된 후
console.log('dialog closed');
```

## 참고사항

* `useOverlay`는 간단한 Overlay 제어용, `useOverlayBase`는 선언적 Overlay 관리용이에요.
* `OverlayProvider`를 루트(App) 컴포넌트에 추가해야 Overlay가 정상 동작해요.
* 여러 개의 Overlay를 동시에 다뤄야 한다면 `useOverlayBase`를 여러 번 호출하면 돼요.
* Overlay 종료 시에는 반드시 `close()` 또는 `exit()`로 명시적으로 처리해 주세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/style-utils/padding.md
---

# padding

`padding`은 컴포넌트의 **안쪽 여백**을 간결하게 지정하는 유틸이에요.\
가로(`x`), 세로(`y`), 개별 방향(`top`, `right`, `bottom`, `left`)으로 숫자 값을 줄 수 있고,\
자주 쓰는 고정 값 프리셋(`x8`, `y16` 등)도 바로 사용할 수 있어요.

## 시그니처

```typescript
padding: BoxSpacing
```

## 프로퍼티

아래 항목들은 모두 스타일 객체를 반환하며, 컴포넌트의 style에 그대로 전달해 사용해요.
숫자 단위는 React Native의 일반적인 숫자 단위(dp)를 따릅니다.

## 프리셋

동일 패턴의 **고정 값 프리셋**을 제공해요. (지원 값 예: `4 | 8 | 12 | 16 | 24 | 32`)

* `padding.x8` → `{ paddingHorizontal: 8 }`
* `padding.y16` → `{ paddingVertical: 16 }`
* `padding.top24`, `padding.right4`, `padding.bottom12`, `padding.left32` 등

## 예제

#### 가로·세로 프리셋 + 임의 값 혼합 사용

```tsx
import { View, Text } from 'react-native';
import { padding } from '@granite-js/react-native';

function Component() {
  return (
    <View>
      <View style={padding.x8}>
        <Text>가로 안쪽 여백이 있어요</Text>
      </View>

      <View style={padding.y8}>
        <Text>세로 안쪽 여백이 있어요</Text>
      </View>

      <View style={padding.bottom(100)}>
        <Text>아래에 100만큼의 안쪽 여백이 있어요</Text>
      </View>
    </View>
  );
}
```

#### StyleSheet와 함께 쓰기

```tsx
import { View, Text, StyleSheet } from 'react-native';
import { padding } from '@granite-js/react-native';

const styles = StyleSheet.create({
  card: {
    ...padding.y16,          // 세로 16
    ...padding.x12,          // 가로 12
  },
  footer: {
    ...padding.top24,        // 위 24
    ...padding.left8,        // 왼 8
  },
});

function Card() {
  return (
    <View style={styles.card}>
      <Text>콘텐츠</Text>
      <View style={styles.footer}>
        <Text>푸터</Text>
      </View>
    </View>
  );
}
```

## 참고사항

* `padding.*`은 `React Native`의 `padding*` 스타일을 **얇게 감싼 헬퍼**예요.
* 프리셋은 팀 내 디자인 간격 체계를 빠르게 일관 적용하기 좋고,\
  함수형(`padding.top(6)`)은 비정형 간격이 필요할 때 유용해요.

---

---
url: 'https://developers-apps-in-toss.toss.im/ads/qa.md'
description: 인앱 광고 자주 묻는 질문과 답변입니다. 주요 이슈 해결 방법을 확인하세요.
---

# QA 진행하기

인앱 광고 연동을 마쳤다면 아래 항목을 **꼼꼼히 점검**해 주세요.

::: tip 실기기 권장
**실단말**에서 네트워크/오디오/백그라운드 전환 동작을 확인하세요.
:::

| 항목 | 내용 |
| --- | --- |
| 사전 체크 | 화면 진입 시 사전 로드가 수행되는지 확인해주세요.   |
| 기본 연동 | 광고 로드 완료 후 지연 없이 재생되는지 확인해주세요. |
|  | 광고 종료 시 미니앱 화면으로 정상 복귀하는지 확인해주세요. |
|  | 광고 재생 시 미니앱 배경음/효과음이 일시 정지되는지 확인해주세요. |
|  | 복귀 후 배경음/효과음이 정상 재개되는지 확인해주세요. |
|  | 광고 재생 도중 닫았을 때 예외 없이 복귀되는지 확인해주세요. |
| 보상형 광고 | 시청 완료 이벤트에서만 보상이 지급되는지 확인해주세요. |
|  | 중복 보상 방지 로직이 동작하는지(재요청·새로고침 등) 확인해주세요. |
| 안정성/정책 | 광고 빈도 제한·쿨다운이 적용되어 남용을 방지하는지 확인해주세요. |
|  | 핵심 플로우 차단(결제/가입/로그인 중) 노출이 없는지 확인해주세요. |
|  | 가로/세로 전환, 백그라운드 복귀 시 정상 동작하는지 확인해주세요. |
|  | 네트워크 실패 시 재시도/대체 흐름이 준비되어 있는지 확인해주세요. |
|  | 메모리/CPU 사용량 급증이나 앱 크래시가 없는지 확인해주세요. |
| 로그/정산 | 광고 노출/완료/보상 지급 이벤트 로그가 수집되고, 대시보드/정산과 식별자가 일치하는지 확인해주세요. |

---

---
url: 'https://developers-apps-in-toss.toss.im/game-center/qa.md'
description: 게임 센터 자주 묻는 질문과 답변입니다. 주요 이슈 해결 방법을 확인하세요.
---

# QA 진행하기

게임 프로필 & 리더보드 연동을 마쳤다면 아래 항목을 **꼼꼼히 점검**해 주세요.

::: tip 실기기 권장

* 토스앱 5.221.0 이상에서 테스트하세요.
* 네트워크 온/오프, 포그라운드↔백그라운드 전환, 가로/세로 회전을 실기기에서 확인해 주세요.
  :::

| 항목 | 내용 |
| --- | --- |
| 사전 체크 | 최초 진입 시 프로필 생성 모달이 노출되는지 확인해주세요. |
|  | 프로필(닉네임/이미지) 생성 완료 전에는 게임 진행이 불가한지 확인해주세요. |
|  | 프로필 생성 후 환영 메시지가 노출되고, 재접속 시 유지되는지 확인해주세요. |
| 점수 제출 | 게임 종료 후에만 점수 제출 API를 호출하는지 확인해주세요. |
|  | 동일 플레이에서 중복 제출이 방지되는지(연타/재시도) 확인해주세요. |
|  | 네트워크 오류/타임아웃 시 재시도·대체 흐름이 준비되어 있는지 확인해주세요. |
| 리더보드 열기 | 리더보드 진입 시 화면 오버레이 겹침 없이 정상 표시되는지 확인해주세요. |
|  | 친구 랭킹 / 전체 랭킹 탭 전환이 부드럽고, 스크롤/페이지네이션이 정상인지 확인해주세요. |
|  | 점수 제출 후 리더보드 반영(새로고침/재진입 시)이 되는지 확인해주세요. |
|  | 동점/무점수 사용자 표시가 일관된 규칙으로 노출되는지 확인해주세요. |
| 공유/소셜 | 리더보드에서 내 점수 자랑하기 공유 시 OS 공유 시트가 열리고, 링크/미리보기가 정상인지 확인해주세요. |
|  | 친구 맺기 흐름이 안내에 따라 동작하고, 친구 기준 랭킹이 올바르게 계산되는지 확인해주세요. |
| 안정성/정책 | 포그라운드 복귀/가로·세로 전환 시 UI 깨짐·리셋 없이 상태가 유지되는지 확인해주세요. |
|  | 메모리/CPU 급증, 크래시 없이 안정적으로 동작하는지 확인해주세요. |

---

---
url: 'https://developers-apps-in-toss.toss.im/iap/qa.md'
description: 인앱 결제 자주 묻는 질문과 답변입니다. 주요 이슈 해결 방법을 확인하세요.
---

# QA 진행하기

인앱결제 연동을 마쳤다면 아래 항목을 **꼼꼼히 점검**해 주세요.

::: tip 운영 팁

* 주문 키(orderId)는 단건-단결제 원칙으로 운영하고, 모든 처리 결과를 서버에 영구 저장하세요.
* 비소모품(권한/광고 제거) 은 반드시 복원(restore) 경로를 제공하세요.
* 재요청·중복 클릭에 대비해 멱등성(idempotency) 을 고려한 설계가 좋아요.
  :::

| 항목 | 내용 |
| --- | --- |
| 기본 연동 | 미니앱 주문 금액과 스토어 결제창 금액이 일치하는지 확인해주세요. |
|  | 인앱결제가 정상 진행되는지 확인해주세요. |
|  | 결제 후 미니앱 화면/서버가 동일한 결과로 처리하는지 확인해주세요. |
|  | **주문 내역 조회(영수증 검증 완료 기준)** 가 가능한지 확인해주세요. |
|  | 스토어 결제창 ‘취소’ 시 주문 화면으로 정상 복귀하는지 확인해주세요. |
|  | 실패 시 원인 메시지가 사용자에게 명확히 노출되는지 확인해주세요. |
|  | 결제 취소/환불 안내 흐름이 준비되어 있는지 확인해주세요. |
| 데이터/권한 | 비소모품 재설치/기기변경 시 복원 흐름이 준비되어 있는지 확인해주세요. |
|  | 중복 구매/중복 지급 방지 로직이 있는지 확인해주세요. |
| 안정성 | 네트워크 장애/타임아웃 시 재시도·대체 흐름이 있는지 확인해주세요. |
|  | 앱 재시작/백그라운드 복귀 시 상태 일관성이 유지되는지 확인해주세요. |
|  | 최소 지원 버전 미만에서는 해당 상품이 노출/결제되지 않는지 확인해주세요. |

---

---
url: 'https://developers-apps-in-toss.toss.im/login/qa.md'
description: 토스 로그인 자주 묻는 질문과 답변입니다. 주요 이슈 해결 방법을 확인하세요.
---

# QA 진행하기

토스 로그인 연동을 마쳤다면 아래 항목을 **꼼꼼히 점검**해 주세요.

| 항목 | 내용 |
| ----|------|
| 사전 체크 | 콘솔 계약/설정이 승인 상태인지, 약관 링크가 정상 열리는지 확인해주세요. |
| 최초 로그인 | 인가 코드 수신 → 서버 교환 → 사용자 정보 복호화/저장 후 홈으로 진입되는지 확인해주세요. |
| 재로그인 | 약관 동의 없이 인가 코드를 즉시 수신하고 정상 진입하는지 확인해주세요. |
| 토큰 만료 직전 호출 | 자동 리프레시로 토큰이 갱신되고 재시도가 성공하는지(실패 시 재로그인 요구) 확인해주세요. |
| 로그인 끊기 콜백 | 서버에서 토큰이 즉시 폐기되고, 재진입 시 로그인 요구되는지 확인해주세요. |
|  | 콜백을 수신·검증해 세션을 해제하고 사용자에게 안내 후 재로그인을 유도하는지 확인해주세요. |
| 네트워크 장애 | 지수 백오프/재시도 적용, 사용자 안내 문구 노출, 복구 후 자동 재시도가 성공하는지 확인해주세요. |

---

---
url: 'https://developers-apps-in-toss.toss.im/promotion/qa.md'
description: 프로모션(토스 포인트) 자주 묻는 질문과 답변입니다. 주요 이슈 해결 방법을 확인하세요.
---

# QA 진행하기

프로모션 연동을 마쳤다면 아래 항목을 **꼼꼼히 점검**해 주세요.

| 항목 | 내용 |
|-----|------|
| 사전 체크 | 계약/정산 승인, 비즈 월렛 잔액, 프로모션 승인/활성, mTLS 적용, 테스트 계정 준비(`x-toss-user-key` 전달) 여부를 확인해주세요. |
| 정상 지급 플로우 | `get-key → execute-promotion → execution-result` 순서로 호출해 최종 `SUCCESS`가 되는지 확인해주세요. |
| 혜택탭 노출 | 미션명이 12자 이내 “~하기” 형식인지, 지급 금액/이동 URL이 정확히 노출·동작하는지 확인해주세요. |
| 중복 지급 방지 | 빠른 연속 클릭/새로고침에도 1회만 지급되고 나머지는 차단/무시되는지 확인해주세요. |
| KEY 유효시간 | KEY(1시간 유효) 만료되면 다시 재시도해주세요. |
| 사용자 식별 헤더 | `x-toss-user-key` 누락/변조 시 권한 오류 처리와 로그인/재시도 안내가 노출되는지 확인해주세요. |
| 예산 소진 | 예산 초과 시 지급이 차단되고 안내 문구 및 혜택탭 미노출이 적용되는지 확인해주세요. |
| 종료일 경과 | 종료일 이후 지급이 차단되고 종료 안내가 노출되는지 확인해주세요. |
| 한도 정책 | 1회/일일 한도 초과 시 차단 및 안내가 동작하는지 확인해주세요. |
| 코드/KEY 오류 | 잘못된 `promotionCode`/위·변조된 KEY 사용 시 실패 처리 및 재시도 안내가 노출되는지 확인해주세요. |
| 네트워크/타임아웃 | 실패 시 지수 백오프로 재시도하고 중복 지급 없이 복구 후 성공하는지 확인해주세요. |
| 서버 장애 대응 | 5xx/에러코드 발생 시 안전한 사용자 안내 및 자동 재시도 또는 “나중에 받기” 흐름이 제공되는지 확인해주세요. |
| 로깅/대사 | `userKey/promotionCode/amount/txId/status` 등 필수 필드가 로그에 남고 대사가 가능한지 확인해주세요. |
| 동시성 제어 | 멀티탭/다중 클릭 동시 호출에도 단 1건만 유효 처리되는지 확인해주세요. |

---

---
url: 'https://developers-apps-in-toss.toss.im/push/qa.md'
description: 푸시 알림 자주 묻는 질문과 답변입니다. 주요 이슈 해결 방법을 확인하세요.
---

# QA 진행하기

푸시, 알림 기능 개발이 완료되었다면 점검해보세요.

| 항목 | 내용 |
|-----|------|
| 사전 체크 | 계약/템플릿 승인, mTLS 적용, 테스트 계정의 x-toss-user-key 준비 상태를 확인해주세요. |
| 템플릿 변수 | 템플릿의 필수 변수(예: {date}, {storeName})가 빠짐없이 치환되는지 확인해주세요. |
| 길이/톤 | 제목 13자, 본문 20자 권장에 맞고 해요체/마침표 규칙을 지키는지 확인해주세요. |
| 수신 해제 | 앱 내 알림 해제 경로가 보이고, 해제 시 미즉시/다음 발송 차단되는지 확인해주세요. |
| 발송 결과 응답 | API 응답의 `msgCount/sentPush/sentInbox` 가 기대와 일치하고, 실패 건의 `reachFailReason`을 로그로 남기는지 확인해주세요. |
| 중복 방지 | 빠른 연속 클릭/재시도에도 중복 발송이 발생하지 않도록 멱등 처리(요청 키/쿨다운)가 적용되는지 확인해주세요. |
| 빈도 제한 | 개인/세션 빈도·쿨다운(예: N분 1회, 일 N회)이 적용되어 스팸성 발송을 막는지 확인해주세요. |
| 링크/딥링크 | 알림 클릭 시 의도한 화면/스킴으로 정확히 진입하는지, 백스택이 자연스러운지 확인해주세요. |
| 표시/도달성 | iOS/Android에서 푸시 배너/알림함 모두 정상 노출되고, 소리·배지·미리보기 설정이 매너 있게 동작하는지 확인해주세요. |
| 네트워크 장애 | 타임아웃/5xx 시 지수 백오프 재시도 후 사용자 안내가 노출되는지, 중복 발송 없이 복구되는지 확인해주세요. |
| 대량 발송 | 대량/배치 시 레이트 리밋을 준수하고, 큐 대기·부분 실패가 리포트/로그로 확인되는지 확인해주세요. |

---

---
url: 'https://developers-apps-in-toss.toss.im/reward/qa.md'
description: 공유 리워드 자주 묻는 질문과 답변입니다. 주요 이슈 해결 방법을 확인하세요.
---

# QA 진행하기

공유 리워드 연동을 마쳤다면 아래 항목을 **꼼꼼히 점검**해 주세요.

| 항목 | 내용 |
|----------------|---------|
| 사전 체크 | 콘솔에 등록한 리워드 단위/수량이 초대 화면 미리보기와 동일하게 노출되는지 확인해주세요. |
| 공유 흐름 | 공유/알림 시트가 정상 열리고, 카드·링크 미리보기가 깨지지 않는지 확인해주세요. |
| 성공 콜백 | 성공 콜백에서만 보상이 지급되는지, 실패/취소 시 미지급이 보장되는지 확인해주세요. |
| 복귀 동작 | 공유 후 게임으로 복귀 시 음악/진행도/일시정지 상태가 그대로 유지되는지 확인해주세요. |
| 오류 처리 | 네트워크 오류/타임아웃 시 재시도/대체 안내가 동작하는지 확인해주세요. |
| 안정성 | 메모리/CPU 급증, 스피너 무한대기, 크래시가 없는지 확인해주세요. |

---

---
url: 'https://developers-apps-in-toss.toss.im/tosspay/qa.md'
description: 토스페이 자주 묻는 질문과 답변입니다. 주요 이슈 해결 방법을 확인하세요.
---

# QA 진행하기

토스페이 기능 개발을 마쳤다면 아래 항목을 **꼼꼼히 점검**해 주세요.

::: tip 운영 팁

* orderNo는 중복 불가합니다.
* 승인/환불 결과를 저장하고, transactionId 기준으로 대사하면 사고 대응이 빨라요.
  :::

| 항목 | 내용 |
| --- | --- |
| 기본 연동 | 미니앱 주문 금액과 토스페이 결제창 금액이 일치하는지 확인해주세요. |
|  | 결제 인증 → 승인(실행) 흐름이 정상 동작하는지 확인해주세요. |
|  | 결제 후 미니앱 화면에서 처리 결과가 일관되게 반영되는지 확인해주세요. |
|  | 미니앱에서 결제 내역 조회가 가능한지 확인해주세요. |
|  | 결제창 ‘취소’ 시 주문 화면으로 정상 복귀하는지 확인해주세요. |
|  | 결제 실패 시 원인 메시지가 사용자에게 명확히 노출되는지 확인해주세요. |
|  | 결제 취소/환불이 정상 처리되는지 확인해주세요. |
| 타임아웃 | 결제 후 통신 장애/타임아웃으로 응답 미수신 시 망취소/실패 처리 등 대응이 준비되어 있는지 확인해주세요. |
| 상태 조회 | 상태 조회 API로 승인/환불 결과를 대사 복구할 수 있는지 확인해주세요. |
| 보안 | mTLS 적용 및 키·토큰 보관(서버 전용) 정책을 준수하는지 확인해주세요. |

---

---
url: 'https://developers-apps-in-toss.toss.im/tutorials/react-native.md'
description: >-
  앱인토스 미니앱을 React Native로 개발 시작할 때 사용하는 튜토리얼입니다. React Native로 프로젝트를 스캐폴딩하는 방법들을
  담고 있습니다.
---

# React Native

:::tip 기존 RN 프로젝트가 있는 경우
이미 React Native로 만든 서비스가 있어도 앱인토스에서 동작하려면 **Granite 기반으로 스캐폴딩** 해야 해요.\
:::

Granite을 사용해 "Welcome!"페이지가 표시되는 서비스를 만들어볼게요.\
이를 통해 로컬 서버를 연결하는 방법과 파일 기반 라우팅을 배울 수 있어요.

## 스캐폴딩

앱을 만들 위치에서 다음 명령어를 실행하세요.

이 명령어는 프로젝트를 초기화하고 필요한 파일과 디렉토리를 자동으로 생성해요.

::: code-group

```sh [npm]
$ npm create granite-app
```

```sh [pnpm]
$ pnpm create granite-app
```

```sh [yarn]
$ yarn create granite-app
```

:::

### 1. 앱 이름 지정하기

앱 이름은 [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case) 형식으로 만들어 주세요.
예를 들어, 아래와 같이 입력해요.

```shell
# 예시
my-granite-app
```

### 2. 도구 선택하기

`granite`에서는 프로젝트를 생성할 때 필요한 도구를 선택할 수 있어요. 현재 제공되는 선택지는 다음 두 가지예요. 둘 중 한 가지 방법을 선택해서 개발 환경을 세팅하세요.

* `prettier` + `eslint`: 코드 포맷팅과 린팅을 각각 담당하며, 세밀한 설정과 다양한 플러그인으로 유연한 코드 품질 관리를 지원해요.
* `biome`: Rust 기반의 빠르고 통합적인 코드 포맷팅과 린팅 도구로, 간단한 설정으로 효율적인 작업이 가능해요.

### 3. 의존성 설치하기

프로젝트 디렉터리로 이동한 뒤, 사용 중인 패키지 관리자에 따라 의존성을 설치하세요.

::: code-group

```sh [npm]
$ cd my-granite-app
$ npm install
```

```sh [pnpm]
$ cd my-granite-app
$ pnpm install
```

```sh [yarn]
$ cd my-granite-app
$ yarn install
```

:::

### 스캐폴딩 전체 예시

아래는 `my-granite-app`이라는 이름으로 새로운 앱을 스캐폴딩한 결과예요.

스캐폴딩을 마쳤다면 프로젝트 구조가 생성돼요.

## 환경 구성하기

ReactNative SDK를 이용해 번들 파일을 생성하고 출시하는 방법을 소개해요.

### 설치하기

앱인토스 미니앱을 개발하려면 `@apps-in-toss/framework` 패키지를 설치해야 해요. 사용하는 패키지 매니저에 따라 아래 명령어를 실행하세요.

::: code-group

```sh [npm]
$ npm install @apps-in-toss/framework
```

```sh [pnpm]
$ pnpm install @apps-in-toss/framework
```

```sh [yarn]
$ yarn add @apps-in-toss/framework
```

:::

### 설정파일 구성하기

`ait init` 명령어로 앱 개발에 필요한 기본 환경을 구성할 수 있어요.\
자세한 설정 방법은 [공통 설정](/bedrock/reference/framework/UI/Config.html) 문서를 확인해 주세요.

1. 아래 명령어 중 사용하는 패키지 관리자에 맞는 명령어를 실행하세요.\
   ::: code-group

   ```sh [npm]
    npx ait init
   ```

   ```sh [pnpm]
    pnpm ait init
   ```

   ```sh [yarn]
    yarn ait init
   ```

   :::

2. 프레임워크를 선택하세요.

3. 앱 이름(`appName`)을 입력하세요.

   이 이름은 앱인토스 콘솔에서 앱을 만들 때 사용한 이름과 같아야 해요. 앱인토스 콘솔에서 앱 이름을 확인할 수 있어요.

모든 과정을 완료하면 프로젝트 루트에 `granite.config.ts` 파일이 생성돼요. 이 파일은 앱 설정을 관리하는 데 사용돼요.

::: code-group

```ts [granite.config.ts]
import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  appName: '<app-name>',
  plugins: [
    appsInToss({
      brand: {
        displayName: '%%appName%%', // 화면에 노출될 앱의 한글 이름으로 바꿔주세요.
        primaryColor: '#3182F6', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
        icon: null, // 화면에 노출될 앱의 아이콘 이미지 주소로 바꿔주세요.
      },
      permissions: [],
    }),
  ],
});
```

:::

* `<app-name>`: 앱인토스에서 만든 앱 이름이에요.
* `brand`: 앱 브랜드와 관련된 구성이에요.
  * `displayName`: 내비게이션 바에 표시할 앱 이름이에요.
  * `icon`: 앱 아이콘 이미지 주소예요. 사용자에게 앱 브랜드를 전달해요.
  * `primaryColor`: Toss 디자인 시스템(TDS) 컴포넌트에서 사용할 대표 색상이에요. RGB HEX 형식(eg. `#3182F6`)으로 지정해요.
* `permissions`: [권한이 필요한 함수 앱 설정하기](/bedrock/reference/framework/권한/permission) 문서를 참고해서 설정하세요.

### React Native TDS 패키지 설치하기

**TDS (Toss Design System)** 패키지는 RN 기반 미니앱이 일관된 UI/UX를 유지하도록 돕는 토스의 디자인 시스템이에요.\
`@apps-in-toss/framework`를 사용하려면 TDS React Native 패키지를 추가로 설치해야 해요.\
모든 비게임 React Native 미니앱은 TDS 사용이 필수이며, 검수 승인 기준에도 포함돼요.

| @apps-in-toss/framework 버전 | 사용할 패키지                    |
| ---------------------------- | -------------------------------- |
| < 1.0.0                      | @toss-design-system/react-native |
| >= 1.0.0                     | @toss/tds-react-native           |

TDS에 대한 자세한 가이드는 [React Native TDS](https://tossmini-docs.toss.im/tds-react-native/)를 참고해 주세요.

### 번들 파일 생성하기

번들 파일은 `.ait` 확장자를 가진 파일로, 빌드된 프로젝트를 패키징한 결과물이에요. 이를 생성하려면 아래 명령어를 실행하세요.

::: code-group

```sh [npm]
npm run build
```

```sh [pnpm]
pnpm build
```

```sh [yarn]
yarn build
```

:::

위 명령어를 실행하면 프로젝트 루트 디렉터리에 `<서비스명>.ait` 파일이 생성돼요. 해당 파일은 앱을 출시할 때 사용해요.

### 앱 출시하기

앱을 출시하는 방법은 [앱 출시하기](/development/test/toss)문서를 참고하세요.

## 코드 확인해보기

프로젝트의 `_app.tsx` 파일에 다음과 같은 코드가 들어있을 거예요.

::: code-group

```tsx [_app.tsx]
import { AppsInToss } from '@apps-in-toss/framework';
import { PropsWithChildren } from 'react';
import { InitialProps } from '@granite-js/react-native';
import { context } from '../require.context';

function AppContainer({ children }: PropsWithChildren<InitialProps>) {
  return <>{children}</>;
}

export default AppsInToss.registerApp(AppContainer, { context });
```

:::

### 스캐폴딩 된 코드 알아보기

스캐폴딩 명령어를 실행하면 다음과 같은 파일이 생성돼요.

::: code-group

```tsx [/pages/index.tsx]
import { createRoute } from '@granite-js/react-native';
import React from 'react';
import { StyleSheet, View, Text, TouchableOpacity } from 'react-native';

export const Route = createRoute('/', {
  component: Page,
});

function Page() {
  const navigation = Route.useNavigation();

  const goToAboutPage = () => {
    navigation.navigate('/about');
  };

  return (
    <Container>
      <Text style={styles.title}>🎉 Welcome! 🎉</Text>
      <Text style={styles.subtitle}>
        This is a demo page for the <Text style={styles.brandText}>Granite</Text> Framework.
      </Text>
      <Text style={styles.description}>This page was created to showcase the features of the Granite.</Text>
      <TouchableOpacity style={styles.button} onPress={goToAboutPage}>
        <Text style={styles.buttonText}>Go to About Page</Text>
      </TouchableOpacity>
    </Container>
  );
}

function Container({ children }: { children: React.ReactNode }) {
  return <View style={styles.container}>{children}</View>;
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 16,
    backgroundColor: 'white',
    justifyContent: 'center',
    alignItems: 'center',
  },
  brandText: {
    color: '#0064FF',
    fontWeight: 'bold',
  },
  text: {
    fontSize: 24,
    color: '#202632',
    textAlign: 'center',
    marginBottom: 10,
  },
  title: {
    fontSize: 32,
    fontWeight: 'bold',
    color: '#1A202C',
    textAlign: 'center',
    marginBottom: 16,
  },
  subtitle: {
    fontSize: 18,
    color: '#4A5568',
    textAlign: 'center',
    marginBottom: 24,
  },
  description: {
    fontSize: 16,
    color: '#718096',
    textAlign: 'center',
    marginBottom: 32,
    lineHeight: 24,
  },
  button: {
    backgroundColor: '#0064FF',
    paddingVertical: 12,
    paddingHorizontal: 32,
    borderRadius: 8,
    shadowColor: '#000',
    shadowOffset: {
      width: 0,
      height: 2,
    },
    shadowOpacity: 0.25,
    shadowRadius: 3.84,
    elevation: 5,
  },
  buttonText: {
    color: 'white',
    fontSize: 16,
    fontWeight: 'bold',
    textAlign: 'center',
  },
  codeContainer: {
    padding: 8,
    backgroundColor: '#333',
    borderRadius: 4,
    width: '100%',
  },
  code: {
    color: 'white',
    fontFamily: 'monospace',
    letterSpacing: 0.5,
    fontSize: 14,
  },
});
```

:::

## 파일 기반 라우팅 이해하기

Granite 개발 환경은 Next.js와 비슷한 [파일 시스템 기반의 라우팅](https://nextjs.org/docs/app/building-your-application/routing#roles-of-folders-and-files)을 사용해요.

파일 기반 라우팅은 파일 구조에 따라 자동으로 경로(URL 또는 스킴)가 결정되는 시스템이에요. 예를 들어, pages라는 디렉토리에 `detail.ts` 파일이 있다면, 이 파일은 자동으로 `/detail` 경로로 연결돼요.

Granite 애플리케이션에서는 이 개념이 스킴과 연결돼요. 스킴은 특정 화면으로 연결되는 주소인데요. 예를 들어, `pages/detail.ts`라는 파일은 자동으로 `intoss://my-granite-app/detail` 이라는 스킴으로 접근할 수 있는 화면이에요. 모든 Granite 화면은 `intoss://` 스킴으로 시작해요.

```
my-granite-app
└─ pages
    ├─ index.tsx       // intoss://my-granite-app
    ├─ detail.tsx      // intoss://my-granite-app/detail
    └─ item
        ├─ index.tsx    // intoss://my-granite-app/item
        └─ detail.tsx    // intoss://my-granite-app/item/detail
```

* `index.tsx` 파일: `intoss://my-granite-app`
* `detail.tsx` 파일: `intoss://my-granite-app/detail`
* `item/index.tsx` 파일: `intoss://my-granite-app/item`
* `item/detail.tsx` 파일: `intoss://my-granite-app/item/detail`

```jsx
┌─ 모든 Granite 화면을 가리키는 스킴은
│  intoss:// 으로 시작해요
│
-------------
intoss://my-granite-app/detail
         ==============~~~~~~~
             │           └─ pages 하위에 있는 경로를 나타내요
             │
             └─ 서비스 이름을 나타내요
```

이렇게 개발자는 별도로 라우팅 설정을 하지 않아도, 파일을 추가하기만 하면 새로운 화면이 자동으로 설정돼요.

## 서버 실행하기

### 로컬 개발 서버 실행하기

이제 여러분만의 Granite 페이지를 만들 준비가 끝났어요. 🎉
다음으로 로컬에서 `my-granite-app` 서비스를 실행해 볼게요.

::: tip 앱 실행 환경을 먼저 설정하세요.

* [iOS 환경설정](/development/client/ios)
* [Android 환경설정](/development/client/android)

:::

스캐폴딩된 프로젝트 디렉터리로 이동한 뒤, 선택한 패키지 매니저를 사용해 `dev` 스크립트를 실행하세요. 이렇게 하면 개발 서버가 시작돼요.

::: code-group

```sh [npm]
$ cd my-granite-app
$ npm run dev
```

```sh [pnpm]
$ cd my-granite-app
$ pnpm dev
```

```sh [yarn]
$ cd my-granite-app
$ yarn dev
```

:::

명령어를 실행하면 아래와 같은 화면이 표시돼요.
![Metro 실행 예시](/assets/local-develop-js-1.B_LK2Zlw.png)

::: tip 참고하세요
개발 서버 실행 중 too many open files 에러가 발생한다면, node\_modules 디렉터리를 삭제한 뒤 다시 의존성을 설치해 보세요.

```sh
rm -rf node_modules
npm install  # 또는 yarn, pnpm에 맞게
```

:::

::: tip 실행 혹은 빌드시 '\[Apps In Toss Plugin] 플러그인 옵션이 올바르지 않습니다' 에러가 발생한다면?
'\[Apps In Toss Plugin] 플러그인 옵션이 올바르지 않습니다. granite.config.ts 구성을 확인해주세요.'\
라는 메시지가 보인다면, `granite.config.ts`의 `icon` 설정을 확인해주세요.\
아이콘을 아직 정하지 않았다면 ''(빈 문자열)로 비워둔 상태로도 테스트할 수 있어요.

```ts
...
displayName: 'test-app', // 화면에 노출될 앱의 한글 이름으로 바꿔주세요.
primaryColor: '#3182F6', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
icon: '',// 화면에 노출될 앱의 아이콘 이미지 주소로 바꿔주세요.
...
```

:::

## 미니앱 실행하기(시뮬레이터·실기기)

:::info 준비가 필요해요
미니앱은 샌드박스 앱을 통해서만 실행되기때문에 **샌드박스 앱(테스트앱)** 설치가 필수입니다.\
개발 및 테스트를 위해 [샌드박스앱](/development/test/sandbox)을 설치해주세요.
:::

### iOS 시뮬레이터(샌드박스앱)에서 실행하기

1. **앱인토스 샌드박스 앱**을 실행해요.
2. 샌드박스 앱에서 스킴을 실행해요. 예를 들어 서비스 이름이 `kingtoss`라면, `intoss://kingtoss`를 입력하고 "스키마 열기" 버튼을 눌러주세요.
3. Metro 서버가 실행 중이라면 시뮬레이터와 자동으로 연결돼요. 화면 상단에 `Bundling {n}%...`가 표시되면 연결이 성공한 거예요.

아래는 iOS 시뮬레이터에서 로컬 서버를 연결한 후 "Welcome!" 페이지를 표시하는 예시예요.

### iOS 실기기에서 실행하기

### 서버 주소 입력하기

아이폰에서 **앱인토스 샌드박스 앱**을 실행하려면 로컬 서버와 같은 와이파이에 연결되어 있어야 해요. 아래 단계를 따라 설정하세요.

1. **샌드박스 앱**을 실행하면 **"로컬 네트워크" 권한 요청 메시지**가 표시돼요. 이때 **"허용"** 버튼을 눌러주세요.

2) **샌드박스 앱**에서 서버 주소를 입력하는 화면이 나타나요.

3) 컴퓨터에서 로컬 서버 IP 주소를 확인하고, 해당 주소를 입력한 뒤 저장해주세요.
   * IP 주소는 한 번 저장하면 앱을 다시 실행해도 변경되지 않아요.
   * macOS를 사용하는 경우, 터미널에서 `ipconfig getifaddr en0` 명령어로 로컬 서버의 IP 주소를 확인할 수 있어요.

4) **"스키마 열기"** 버튼을 눌러주세요.

5) 화면 상단에 `Bundling {n}%...` 텍스트가 표시되면 로컬 서버에 성공적으로 연결된 거예요.

::: details "로컬 네트워크"를 수동으로 허용하는 방법
**"로컬 네트워크" 권한을 허용하지 못한 경우, 아래 방법으로 수동 설정이 가능해요.**

1. 아이폰의 \[설정] 앱에서 **"앱인토스"** 를 검색해 이동해요.
2. **"로컬 네트워크"** 옵션을 찾아 켜주세요.

:::

***

### Android 실기기 또는 에뮬레이터 연결하기

1. Android 실기기(휴대폰 또는 태블릿)를 컴퓨터와 USB로 연결하세요. ([USB 연결 가이드](/development/client/android.html#기기-연결하기))

2. `adb` 명령어를 사용해서 `8081` 포트와 `5173`포트를 연결하고 연결 상태를 확인해요.

   **8081 포트, 5173 포트 연결하기**

   기기가 하나만 연결되어 있다면 아래 명령어만 실행해도 돼요.

   ```shell
   adb reverse tcp:8081 tcp:8081
   adb reverse tcp:5173 tcp:5173
   ```

   특정 기기를 연결하려면 `-s` 옵션과 디바이스 아이디를 추가해요.

   ```shell
   adb -s {디바이스아이디} reverse tcp:8081 tcp:8081
   # 예시: adb -s R3CX30039GZ reverse tcp:8081 tcp:8081
   adb -s {디바이스아이디} reverse tcp:5173 tcp:5173
   # 예시: adb -s R3CX30039GZ reverse tcp:5173 tcp:5173
   ```

   **연결 상태 확인하기**

   연결된 기기와 포트를 확인하려면 아래 명령어를 사용하세요.

   ```shell
   adb reverse --list
   # 연결된 경우 예시: UsbFfs tcp:8081 tcp:8081

   ```

   특정 기기를 확인하려면 `-s` 옵션을 추가해요.

   ```shell
   adb -s {디바이스아이디} reverse --list
   # 예시: adb -s R3CX30039GZ reverse --list

   # 연결된 경우 예시: UsbFfs tcp:8081 tcp:8081
   ```

3. **앱인토스 샌드박스 앱**에서 스킴을 실행하세요. 예를 들어, 서비스 이름이 `kingtoss`라면 `intoss://kingtoss`를 입력하고 실행 버튼을 누르세요.

4. Metro 서버가 실행 중이라면 실기기 또는 에뮬레이터와 자동으로 연결돼요. 화면 상단에 번들링 프로세스가 진행 중이면 연결이 완료된 거예요.

   아래는 Android 시뮬레이터에서 로컬 서버를 연결한 후 "Welcome!" 페이지를 표시하는 예시예요.

### 자주 쓰는 `adb` 명령어(Android)

개발 중에 자주 쓰는 `adb` 명령어를 정리했어요.

#### 연결 끊기

```shell
adb kill-server
```

#### 8081 포트 연결하기

```shell
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173
# 특정 기기 연결: adb -s {디바이스아이디} reverse tcp:8081 tcp:8081
```

#### 연결 상태 확인하기

```shell
adb reverse --list
# 특정 기기 확인: adb -s {디바이스아이디} reverse --list
```

### 트러블슈팅

::: details Q. Metro 개발 서버가 열려 있는데 `잠시 문제가 생겼어요`라는 메시지가 표시돼요.

개발 서버에 제대로 연결되지 않은 문제일 수 있어요. `adb` 연결을 끊고 다시 `8081` 포트를 연결하세요.
:::

::: details Q. PC웹에서 Not Found 오류가 발생해요.

8081 포트는 샌드박스 내에서 인식하기 위한 포트예요.\
PC웹에서 8081 포트는 Not Found 오류가 발생해요.
:::

::: details 연결 가능한 기기가 없다고 떠요

React Native View가 나타나는 시점에 개발 서버와 기기가 연결됩니다. 만약 연결 가능한 기기가 없다고 뜬다면, 개발 서버가 제대로 빌드되고 있는지 확인해 보세요. 다음 화면처럼 개발 서버가 빌드를 시작했다면 기기와의 연결이 정상적으로 이루어진 것입니다.

![개발 서버 연결 상태 확인 이미지](/assets/debugging-22.B1aIn4qo.png)
:::

::: details REPL가 동작하지 않아요

React Native의 버그로 인해 가끔 REPL이 멈추는 현상이 발생할 수 있어요. 이 문제를 해결하려면, 콘솔 탭 옆에 있는 눈 모양 아이콘을 클릭하고 입력 필드에 임의의 코드를 작성하고 평가해 보세요. 예를 들어 `__DEV__`, `1`, `undefined` 등의 코드를 입력하면 돼요.

![REPL 프리징 해결 방법 이미지](/resources/learn-more/debugging/debugging-23.png)

:::

::: details 네트워크 인스펙터가 동작하지 않아요

React Native 애플리케이션에서 여러 개의 인스턴스가 생성될 수 있는데, 현재 네트워크 인스펙터는 다중 인스턴스를 지원하지 않아요. 따라서 가장 최근에 생성된 인스턴스와만 데이터를 주고받게 됩니다. 이로 인해 소켓 커넥션이 꼬여 네이티브에서 전송하는 데이터를 인스펙터가 받지 못할 수 있어요.

이 문제를 해결하려면 다음을 시도해 보세요.

1. 앱을 완전히 종료해요.
2. 개발 서버를 중단하고 네트워크 인스펙터를 닫아요.
3. 앱을 다시 시작하고 `dev` 스크립트를 실행해 개발 서버를 재실행해요.

이 절차로도 문제가 해결되지 않으면, 담당자에게 제보해 주세요.

:::

## 토스앱에서 테스트하기

토스앱에서 테스트하는 방법은 [토스앱](/development/test/toss) 문서를 참고하세요.

## 출시하기

출시하는 방법은 [미니앱 출시](/development/deploy) 문서를 참고하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/RNVideoRef.md
---

# RNVideoRef

`react-native-video`의 ref 타입이에요.

## 시그니처

```typescript
type RNVideoRef = VideoRef;
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/safe-area.md
---

# Safe Area 여백 값 구하기

모바일 브라우저에서는 상태바나 홈 인디케이터 같은 시스템 UI 때문에 콘텐츠가 가려질 때가 있어요.\
앱인토스 SDK는 이런 상황을 방지하기 위해 화면의 안전 영역(Safe Area) 여백 값을 픽셀 단위로 계산하는 함수를 제공해요.

특히 iPhone X 이상 기기나 일부 Android 기기에서는 전체 화면을 사용하는 웹 앱에서 시스템 UI가 콘텐츠를 가리는 경우가 자주 있어요.\
아래 함수를 사용하면 콘텐츠가 안전하게 표시되도록 여백을 쉽게 조절할 수 있어요.

## `SafeAreaInsets`

화면 모드가 바뀔 때 `safearea` 값을 확인할 수 있어요.\
화면 전환 시 안전 영역 정보를 가져오거나, 변경을 구독할 수도 있어요.\
이 기능을 사용하면 다양한 디바이스 환경에서도 안정적인 UI를 구현할 수 있어요.

* `SafeAreaInsets.get()` : 현재 화면 모드의 `safearea` 값을 가져와요.
* `SafeAreaInsets.subscribe()` : 화면 모드가 바뀔 때마다 `safearea` 값 변화를 구독해요.

:::tip 게임 내 X 버튼 좌표
X 버튼은 프레임워크에 기본으로 포함되어 제공돼요.\
화면의 **오른쪽 상단**에 고정되어 있으며, 위치는 아래와 같이 계산할 수 있어요.

* **X축:** `safeAreaInsetsValue.right + 10`
* **Y축:** `safeAreaInsetsValue.top + 5` (iOS) / `safeAreaInsetsValue.top +10` (Android)

게임 내 버튼이 프레임워크의 X 버튼과 겹치면 검수 과정에서 반려될 수 있어요.
:::

### 예시

```tsx
import { SafeAreaInsets } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';

interface SafeAreaInsets {
  top: number;
  bottom: number;
  left: number;
  right: number;
}

function Page() {
  const [safeAreaInsetsValue, setSafeAreaInsetsValue] = useState<SafeAreaInsets>(() => SafeAreaInsets.get())
  // 네비게이션 바 상단 여백: safeAreaInsetsValue.top
  // 네비게이션 바 우측 여백: safeAreaInsetsValue.right + 10


  useEffect(() => {
    const cleanup = SafeAreaInsets.subscribe({
      onEvent: (insets) => {
        setSafeAreaInsetsValue(insets);
      }
    });
    return () => cleanup();
  }, []);

  // ...
}
```

## `getSafeAreaInsets`

::: tip 이 함수는 SDK 1.4.6 버전까지만 사용할 수 있어요
**1.4.7 버전 부터는 deprecated** 되었어요
:::

```ts
import { getSafeAreaInsets } from "@apps-in-toss/web-framework";

const insets = getSafeAreaInsets();
// 예시 반환값: { top: 44, bottom: 34 }
```

반환되는 객체는 다음 속성을 포함해요.

* `top`: 상단 상태바에 가리지 않도록 확보해야 하는 여백이에요.
* `bottom`: 하단 홈 인디케이터에 가리지 않도록 확보해야 하는 여백이에요.

이 값은 전체 화면(`viewport`)에 맞춰 UI를 만들 때 자주 사용돼요.\
예를 들어, 하단 고정 버튼에 여백을 주거나 상단 헤더가 상태바에 겹치지 않도록 만들 수 있어요.

### 하단 여백 적용 예시

하단 고정 버튼이 홈 인디케이터에 겹치지 않도록 여백을 주는 예시예요.

```tsx
import { getSafeAreaInsets } from "@apps-in-toss/web-framework";

const insets = getSafeAreaInsets();

const Button = () => {
  return (
    <div style={{ paddingBottom: `${insets.bottom}px` }}>
      <button>확인</button>
    </div>
  );
};
```

### 상단 여백 적용 예시

상단 고정 헤더가 상태바에 겹치지 않도록 여백을 주는 예시예요.

```tsx
import { getSafeAreaInsets } from "@apps-in-toss/web-framework";

const insets = getSafeAreaInsets();

const Header = () => {
  return (
    <div style={{ paddingTop: `${insets.top}px` }}>
      <h1>제목</h1>
    </div>
  );
};
```

## `useSafeAreaInsets`

모바일 브라우저에서 상태바나 홈 인디케이터 같은 시스템 UI에 의해 콘텐츠가 가려지는 문제를 방지할 수 있도록, 화면의 안전 영역(Safe Area) 여백 값을 픽셀 단위로 계산해줘요.\
`useSafeAreaInsets` 는 ReactNative 로 개발할 때 사용할 수 있어요.

```tsx
import { useSafeAreaInsets } from '@granite-js/native/react-native-safe-area-context';
const { top: safeAreaTop, right: safeAreaRight } = useSafeAreaInsets();
// 네비바 상단 여백: safeAreaTop
// 네비바 우측 여백: safeAreaRight + 10
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/ScrollViewInertialBackground.md
---

# ScrollViewInertialBackground

iOS `ScrollView` 콘텐츠의 위, 아래 공간에 배경색을 추가해서, 스크롤 했을 때 자연스러운 시각 효과를 제공해요.
iOS에서는 스크롤이 끝에 도달했을 때 살짝 튕기는 듯한 [Bounce 효과](https://medium.com/@wcandillon/ios-bounce-list-effect-with-react-native-5102e3a83999)가 발생해요. 이때 콘텐츠 위, 아래 공간에 배경색을 설정하면 더 일관된 유저 경험을 제공할 수 있어요.

## 시그니처

```typescript
function ScrollViewInertialBackground({ topColor, bottomColor, spacer: _spacer, }: ScrollViewInertialBackgroundProps): import("react/jsx-runtime").JSX.Element;
```

### 파라미터

## 예제

### 스크롤 뷰 위, 아래에 배경색을 추가하기

스크롤 뷰 위에 빨간색, 아래에 파란색 배경색을 추가해요. 스크롤을 벗어난 영역에 배경색이 적용돼요.

```tsx
import { ScrollView, View, Text } from 'react-native';
import { ScrollViewInertialBackground } from '@granite-js/react-native';

const dummies = Array.from({ length: 20 }, (_, i) => i);

function InertialBackgroundExample() {
  return (
    <ScrollView>
      <ScrollViewInertialBackground topColor="red" bottomColor="blue" />
      {dummies.map((i) => (
        <View
          key={`dummy-${i}`}
          style={{ width: '100%', height: 100, borderBottomColor: 'black', borderBottomWidth: 1 }}
        >
          <Text>스크롤을 해보세요.</Text>
        </View>
      ))}
    </ScrollView>
  );
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/learn-more/sentry-monitoring.md'
description: Sentry를 이용한 앱인토스 미니앱 모니터링 가이드입니다. 에러 추적 및 성능 모니터링 방법을 확인하세요.
---

# Sentry 설정하기

앱에 **Sentry**를 연동하면 JavaScript에서 발생한 오류를 자동으로 감지하고 모니터링할 수 있어요.\
이를 통해 앱의 안정성을 높이고, 사용자에게 더 나은 경험을 제공할 수 있어요.

## 1. Sentry 초기 설정

[Sentry 공식 가이드](https://docs.sentry.io/platforms/react-native)를 참고하여 앱에서 Sentry를 초기화해주세요.

앱인토스 환경에서는 네이티브 오류 추적 기능을 사용할 수 없으므로 `enableNative` 옵션을 `false`로 설정해야 해요.

::: tip 네이티브 오류 추적은 지원되지 않아요
앱인토스 환경에서는 JavaScript 오류만 추적할 수 있어요.
:::

```ts
import * as Sentry from '@sentry/react-native';

Sentry.init({
  // ...
  enableNative: false,
});
```

## 2. Sentry 플러그인 설치

프로젝트 루트 디렉터리에서 사용 중인 패키지 관리자에 맞는 명령어를 실행해 Sentry 플러그인을 설치하세요.

::: code-group

```sh [npm]
npm install @granite-js/plugin-sentry
```

```sh [pnpm]
pnpm install @granite-js/plugin-sentry
```

```sh [yarn]
yarn add @granite-js/plugin-sentry
```

:::

## 3. 플러그인 구성

설치한 `@granite-js/plugin-sentry`를 `granite.config.ts` 파일의 `plugins` 항목에 추가하세요.
앱인토스 환경에서는 **`useClient` 옵션을 반드시 `false`로 설정**해야 해요.

::: tip 왜 `useClient` 옵션을 꺼야 하나요?

`useClient`를 `false`로 설정하면 앱 빌드 시 Sentry에 소스맵이 자동으로 업로드되지 않아요.
앱인토스 환경에서는 빌드 후 **수동으로 소스맵을 업로드**해야 하므로, 이 옵션을 꺼야 해요.

:::

```ts [granite.config.ts]
import { defineConfig } from '@granite-js/react-native/config';
import { sentry } from '@granite-js/plugin-sentry'; // [!code highlight]
import { appsInToss } from '@apps-in-toss/framework/plugins';

export default defineConfig({
  // ...,
  plugins: [
    sentry({ useClient: false }), // [!code highlight]
    appsInToss({
      // ...
    }),
  ],
});
```

## 4. 앱 출시하기

앱을 출시하는 방법은 [미니앱 출시](/development/deploy.md) 문서를 참고하세요.

## 5. Sentry에 소스맵 업로드

출시된 미니앱의 오류를 정확히 추적하려면\
빌드 후 생성된 **소스맵을 Sentry에 업로드**해야 해요.

아래 명령어를 실행하면 소스맵이 업로드돼요.

::: tip 입력값 안내

* `<API_KEY>`: 앱인토스 콘솔에서 발급받은 API 키예요.
* `<APP_NAME>`: Sentry에 등록된 서비스 이름이에요.
* `<DEPLOYMENT_ID>`: 앱을 배포할 때 사용한 배포 ID예요.

:::

::: code-group

```sh [npm]
npx ait sentry upload-sourcemap \
  --api-key <API_KEY> \
  --app-name <APP_NAME> \
  --deployment-id <DEPLOYMENT_ID>
```

```sh [pnpm]
pnpm ait sentry upload-sourcemap \
  --api-key <API_KEY> \
  --app-name <APP_NAME> \
  --deployment-id <DEPLOYMENT_ID>
```

```sh [yarn]
yarn ait sentry upload-sourcemap \
  --api-key <API_KEY> \
  --app-name <APP_NAME> \
  --deployment-id <DEPLOYMENT_ID>
```

:::

명령어 실행 후 Sentry의 조직(Org), 프로젝트(Project), 인증 토큰 입력이 요청됩니다.\
모든 정보를 입력하면 해당 서비스의 소스맵이 Sentry에 업로드돼요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/클립보드/SetClipboardTextPermissionError.md
---

# SetClipboardTextPermissionError

클립보드 쓰기 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof SetClipboardTextPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class SetClipboardTextPermissionError extends PermissionError {
    constructor();
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/style-utils/Spacing.md
---

# Spacing

`Spacing`은 빈 공간을 차지해 **가로 또는 세로 방향으로 여백을 추가**하는 컴포넌트예요.\
화면 요소 사이의 간격을 일정하게 맞추거나, 시각적인 구분을 줄 때 사용해요.

## 시그니처

```typescript
Spacing: import("react").NamedExoticComponent<Props>
```

## 파라미터

## 예제

#### 세로 방향으로 여백 추가하기

```tsx
import { View, Text } from 'react-native';
import { Spacing } from '@granite-js/react-native';

function VerticalSpacingExample() {
  return (
    <View>
      <Text>Top</Text>
      <Spacing size={16} direction="vertical" style={{ backgroundColor: 'red', width: 5 }} />
      <Text>Bottom — 세로 여백만큼 아래에 위치해요</Text>
    </View>
  );
}
```

#### 가로 방향으로 여백 추가하기

```tsx
import { View, Text } from 'react-native';
import { Spacing } from '@granite-js/react-native';

function HorizontalSpacingExample() {
  return (
    <View style={{ flexDirection: 'row' }}>
      <Text>Left</Text>
      <Spacing size={16} direction="horizontal" style={{ backgroundColor: 'red', height: 5 }} />
      <Text>Right — 가로 여백만큼 옆에 위치해요</Text>
    </View>
  );
}
```

## 참고사항

* `Spacing`은 `margin`이나 `padding` 대신 명시적으로 간격을 줄 때 유용해요.
* `direction` 속성을 통해 한쪽 방향의 여백만 적용할 수 있어요.
* `size` 값은 숫자(px 단위)로 지정하며, 반응형 간격이 필요할 경우 `StyleSheet`와 함께 사용할 수 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/style-utils/Stack.md
---

# Stack

`Stack`은 자식 요소를 **가로 또는 세로 방향으로 일정 간격을 두고 배치**하는 레이아웃 컴포넌트예요.\
`direction` 속성으로 방향을 설정하고, `gutter` 속성으로 요소 간 간격을 조절할 수 있어요.\
가로 배치는 `Stack.Horizontal`, 세로 배치는 `Stack.Vertical`로 간편하게 사용할 수 있어요.

### 시그니처

```typescript
Stack: StackType
```

### 파라미터

### 예제 : 가로·세로 방향으로 배치하기

```tsx
import { Text } from 'react-native';
import { Stack } from '@granite-js/react-native';

function StackExample() {
  return (
    <>
      <Stack gutter={16} direction="horizontal">
        <Text>16간격을 두고 가로 방향으로 배치해요</Text>
        <Text>1</Text>
        <Text>2</Text>
        <Text>3</Text>
      </Stack>
      <Stack gutter={16} direction="vertical">
        <Text>16간격을 두고 세로 방향으로 배치해요</Text>
        <Text>1</Text>
        <Text>2</Text>
        <Text>3</Text>
      </Stack>
    </>
  );
}
```

## 가로로 배치하기 (`Stack.Horizontal`)

`Stack.Horizontal`은 자식 요소를 **가로 방향**으로 쌓아 배치해요.\
`gutter` 속성으로 간격을 설정해 일정한 가로 레이아웃을 유지할 수 있어요.

### 예제

```tsx
import { Stack } from '@granite-js/react-native';
import { View, Text } from 'react-native';

function StackHorizontalExample() {
  return (
       <Stack.Horizontal gutter={16}>
        <Text>16간격을 두고 가로 방향으로 배치해요</Text>
        <Text>1</Text>
        <Text>2</Text>
        <Text>3</Text>
      </Stack.Horizontal>
  );
}
```

## 세로로 배치하기 (`Stack.Vertical`)

`Stack.Vertical`은 자식 요소를 **세로 방향**으로 쌓아 배치해요.\
`gutter` 속성으로 요소 간의 간격을 쉽게 제어할 수 있어요.

### 예제

```tsx
import { Stack } from '@granite-js/react-native';
import { View, Text } from 'react-native';

function StackVerticalExample() {
  return (
       <Stack.Vertical gutter={16}>
        <Text>16간격을 두고 세로 방향으로 배치해요</Text>
        <Text>1</Text>
        <Text>2</Text>
        <Text>3</Text>
      </Stack.Vertical>
  );
}
```

## 참고사항

* Stack은 `Flexbox` 기반으로 구성되어 있어요.
* `gutter`를 통해 일정한 간격을 유지할 수 있고, React 컴포넌트를 전달해 커스텀 간격도 만들 수 있어요.
* `Stack.Horizontal`과 `Stack.Vertical`을 사용하면 가로·세로 레이아웃을 더 간결하게 구성할 수 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/위치
  정보/StartUpdateLocationPermissionError.md
---

# StartUpdateLocationPermissionError

위치 업데이트 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof StartUpdateLocationPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
StartUpdateLocationPermissionError: typeof GetCurrentLocationPermissionError
```

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/tab.md'
description: 토스 디자인 시스템(TDS)의 Tab 컴포넌트 가이드입니다. 탭 네비게이션 구성 및 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

`Tab` 컴포넌트는 여러 콘텐츠를 한 화면에서 효율적으로 전환할 수 있도록 도와줘요. 각 탭은 콘텐츠 목록을 보여주고, 사용자가 선택한 탭에 따라 해당 콘텐츠를 전환해요. `Tab` 컴포넌트를 사용하면 여러 콘텐츠를 한 번에 볼 수 있고, 전환도 간편하게 할 수 있어요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/tab/)

![tab](/assets/Thumbnail-Tab.D8dHQEie.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/tabbar.md'
description: 토스 디자인 시스템(TDS)의 Tabbar 컴포넌트 가이드입니다. 하단 탭바 구성 및 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

하단 탭바는 서비스의 주요 기능에 빠르게 접근할 수 있도록 돕는 내비게이션 요소입니다.

필수 컴포넌트는 아니지만, 탭바가 필요하다면 TDS 미사용 시에도 반드시 토스에서 제공하는 플로팅 형태의 탭바를 사용해야 합니다.

![tabbar](/assets/Thumbnail-Tabbar.B3GwW4mW.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/Text.md'
description: Bedrock 프레임워크 레퍼런스 문서입니다.
---

# Text

`Text` 컴포넌트를 이용해서 글자를 화면에 표시할 수 있어요.\
예를 들어, 아래 코드는 안녕하세요라는 글자를 화면에 표시하는 예제에요.

```tsx
import { Text } from "react-native";

export default function TextPage() {
  return <Text>안녕하세요</Text>;
}
```

::: tip 글자는 `Text` 컴포넌트로 감싸지 않으면 에러가 발생해요.

에러 메시지는 다음과 같아요. 글자를 화면에 표시하려면 반드시 `Text` 컴포넌트를 사용해야 해요.

```
Error: Text strings must be rendered within a <Text> component.
```

:::

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/text.md'
description: 토스 디자인 시스템(TDS)의 Text 컴포넌트 가이드입니다. 텍스트 스타일 및 타이포그래피 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

컴포넌트에 기본 포함된 텍스트를 제외한 모든 문구는 이 컴포넌트를 통해 입력합니다.

토스 전용 폰트인 ‘토스 프로덕트 산스’가 기본으로 적용되어 있습니다.

![text](/assets/Thumbnail-Text.CUOGp53J.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components/top.md'
description: 토스 디자인 시스템(TDS)의 Top 컴포넌트 가이드입니다. 상단 영역 구성 및 사용법을 확인하세요.
---

# {{ $frontmatter.title }}

`Top` 컴포넌트는 다양한 레이아웃을 지원하는 페이지 상단 컴포넌트로, 여러 요소(텍스트, 버튼, 이미지 등)를 쉽게 배치할 수 있어요. 주로 페이지의 최상단에 사용되어 헤더나 타이틀 영역을 구성하는 데 활용돼요.

[자세히 알아보기 >](https://tossmini-docs.toss.im/tds-mobile/components/top/)

![top](/assets/Thumbnail-Top.DW3dRbnk.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/unity-profiler.md
---
# Unity Profiler

앱인토스 Unity 게임 개발에서 Unity Profiler를 효과적으로 활용하여 성능 이슈를 진단하고 해결하는 완전한 가이드입니다.

***

## 1. Profiler 설정 및 연결

### 앱인토스 환경 Profiler 설정

```c#
public class AppsInTossProfilerSetup : MonoBehaviour
{
    [Header("Profiler 연결 설정")]
    public bool enableAutoConnect = true;
    public string remoteIP = "192.168.1.100";
    public int profilerPort = 54998;
    
    [Header("프로파일링 영역")]
    public bool enableCPUProfiling = true;
    public bool enableMemoryProfiling = true;
    public bool enableGPUProfiling = true;
    public bool enableAudioProfiling = true;
    public bool enableNetworkProfiling = true;
    
    void Start()
    {
        #if DEVELOPMENT_BUILD || UNITY_EDITOR
        SetupProfilerConnection();
        ConfigureProfilerAreas();
        #endif
    }
    
    void SetupProfilerConnection()
    {
        if (enableAutoConnect)
        {
            // 자동 연결 시도
            ProfilerDriver.profileEditor = false;
            ProfilerDriver.connectedProfiler = 0;
            
            Debug.Log($"Unity Profiler 자동 연결 시작: {remoteIP}:{profilerPort}");
        }
        
        // 앱인토스 환경 정보 로깅
        LogAppsInTossEnvironmentInfo();
    }
    
    void ConfigureProfilerAreas()
    {
        List<ProfilerArea> activeAreas = new List<ProfilerArea>();
        
        if (enableCPUProfiling) activeAreas.Add(ProfilerArea.CPU);
        if (enableMemoryProfiling) activeAreas.Add(ProfilerArea.Memory);
        if (enableGPUProfiling) activeAreas.Add(ProfilerArea.GPU);
        if (enableAudioProfiling) activeAreas.Add(ProfilerArea.Audio);
        if (enableNetworkProfiling) activeAreas.Add(ProfilerArea.NetworkOperations);
        
        Debug.Log($"활성화된 Profiler 영역: {string.Join(", ", activeAreas)}");
    }
    
    void LogAppsInTossEnvironmentInfo()
    {
        Debug.Log("=== 앱인토스 환경 정보 ===");
        Debug.Log($"플랫폼: {Application.platform}");
        Debug.Log($"기기 모델: {SystemInfo.deviceModel}");
        Debug.Log($"메모리: {SystemInfo.systemMemorySize}MB");
        Debug.Log($"GPU: {SystemInfo.graphicsDeviceName}");
        Debug.Log($"GPU 메모리: {SystemInfo.graphicsMemorySize}MB");
        Debug.Log($"프로세서: {SystemInfo.processorType}");
        Debug.Log($"코어 수: {SystemInfo.processorCount}");
        Debug.Log($"배터리 레벨: {SystemInfo.batteryLevel * 100}%");
        Debug.Log("========================");
    }
}
```

***

## 2. 커스텀 Profiler 마커

### 앱인토스 특화 성능 마커

```c#
using Unity.Profiling;

public static class AppsInTossProfilerMarkers
{
    // 앱인토스 특화 성능 마커들
    public static readonly ProfilerMarker TossLoginMarker = new ProfilerMarker("AppsInToss.Login");
    public static readonly ProfilerMarker TossPaymentMarker = new ProfilerMarker("AppsInToss.Payment");
    public static readonly ProfilerMarker TossAnalyticsMarker = new ProfilerMarker("AppsInToss.Analytics");
    public static readonly ProfilerMarker AssetLoadingMarker = new ProfilerMarker("AppsInToss.AssetLoading");
    public static readonly ProfilerMarker SceneTransitionMarker = new ProfilerMarker("AppsInToss.SceneTransition");
    public static readonly ProfilerMarker UIUpdateMarker = new ProfilerMarker("AppsInToss.UIUpdate");
    public static readonly ProfilerMarker NetworkRequestMarker = new ProfilerMarker("AppsInToss.NetworkRequest");
    public static readonly ProfilerMarker GameLogicMarker = new ProfilerMarker("AppsInToss.GameLogic");
    
    // 메모리 관련 마커
    public static readonly ProfilerMarker MemoryCleanupMarker = new ProfilerMarker("AppsInToss.MemoryCleanup");
    public static readonly ProfilerMarker GarbageCollectionMarker = new ProfilerMarker("AppsInToss.GC");
    
    // 렌더링 관련 마커
    public static readonly ProfilerMarker BatchingMarker = new ProfilerMarker("AppsInToss.Batching");
    public static readonly ProfilerMarker LODUpdateMarker = new ProfilerMarker("AppsInToss.LODUpdate");
    public static readonly ProfilerMarker CullingMarker = new ProfilerMarker("AppsInToss.Culling");
}

// 사용 예제
public class AppsInTossGameManager : MonoBehaviour
{
    void Update()
    {
        using (AppsInTossProfilerMarkers.GameLogicMarker.Auto())
        {
            UpdateGameLogic();
        }
        
        using (AppsInTossProfilerMarkers.UIUpdateMarker.Auto())
        {
            UpdateUI();
        }
    }
    
    void UpdateGameLogic()
    {
        // 게임 로직 처리
    }
    
    void UpdateUI()
    {
        // UI 업데이트 로직
    }
    
    public void ProcessTossLogin()
    {
        using (AppsInTossProfilerMarkers.TossLoginMarker.Auto())
        {
            // 토스 로그인 처리
            AppsInToss.Login((result) => {
                Debug.Log($"토스 로그인 결과: {result}");
            });
        }
    }
    
    public void ProcessPayment(float amount)
    {
        using (AppsInTossProfilerMarkers.TossPaymentMarker.Auto())
        {
            // 토스페이 결제 처리
            AppsInToss.ProcessPayment(amount, (success) => {
                Debug.Log($"결제 결과: {success}");
            });
        }
    }
}
```

***

## 3. 자동화된 성능 분석

### Profiler 데이터 자동 분석

```c#
#if UNITY_EDITOR
using UnityEngine;
using UnityEditor;
using UnityEditorInternal;
using System.Collections.Generic;
using System.Linq;

public class AppsInTossProfilerAnalyzer : EditorWindow
{
    [System.Serializable]
    public class PerformanceIssue
    {
        public string category;
        public string description;
        public float severity; // 0-1
        public string suggestion;
        public int frameNumber;
    }
    
    private List<PerformanceIssue> detectedIssues = new List<PerformanceIssue>();
    private Vector2 scrollPosition;
    private bool isAnalyzing = false;
    
    [MenuItem("AppsInToss/Profiler Analyzer")]
    public static void ShowWindow()
    {
        GetWindow<AppsInTossProfilerAnalyzer>("Profiler Analyzer");
    }
    
    void OnGUI()
    {
        GUILayout.Label("앱인토스 Profiler 자동 분석", EditorStyles.boldLabel);
        GUILayout.Space(10);
        
        if (GUILayout.Button(isAnalyzing ? "분석 중..." : "성능 분석 시작", GUILayout.Height(30)))
        {
            if (!isAnalyzing)
            {
                StartPerformanceAnalysis();
            }
        }
        
        GUILayout.Space(10);
        
        // 이슈 목록 표시
        DrawIssueList();
        
        GUILayout.Space(10);
        
        // 최적화 제안
        DrawOptimizationSuggestions();
    }
    
    void StartPerformanceAnalysis()
    {
        isAnalyzing = true;
        detectedIssues.Clear();
        
        // Profiler 데이터 분석
        AnalyzeProfilerData();
        
        isAnalyzing = false;
        Repaint();
    }
    
    void AnalyzeProfilerData()
    {
        int frameCount = ProfilerDriver.lastFrameIndex - ProfilerDriver.firstFrameIndex;
        
        for (int i = ProfilerDriver.firstFrameIndex; i <= ProfilerDriver.lastFrameIndex; i++)
        {
            AnalyzeFrame(i);
        }
        
        Debug.Log($"성능 분석 완료: {frameCount}프레임, {detectedIssues.Count}개 이슈 발견");
    }
    
    void AnalyzeFrame(int frameIndex)
    {
        // CPU 사용량 분석
        float cpuTime = ProfilerDriver.GetFormattedStatisticsValue(frameIndex, ProfilerArea.CPU, "Total");
        if (cpuTime > 33.33f) // 30 FPS 기준
        {
            detectedIssues.Add(new PerformanceIssue
            {
                category = "CPU",
                description = $"높은 CPU 사용량: {cpuTime:F2}ms",
                severity = Mathf.Clamp01(cpuTime / 100f),
                suggestion = "CPU 집약적인 작업을 최적화하거나 프레임에 분산하세요",
                frameNumber = frameIndex
            });
        }
        
        // 메모리 사용량 분석
        long memoryUsage = ProfilerDriver.GetStatisticsValue(frameIndex, ProfilerArea.Memory, "Total Reserved Memory");
        if (memoryUsage > 200 * 1024 * 1024) // 200MB 초과
        {
            detectedIssues.Add(new PerformanceIssue
            {
                category = "Memory",
                description = $"높은 메모리 사용량: {memoryUsage / (1024*1024)}MB",
                severity = Mathf.Clamp01((float)memoryUsage / (300f * 1024 * 1024)),
                suggestion = "메모리 사용량을 줄이거나 가비지 컬렉션을 최적화하세요",
                frameNumber = frameIndex
            });
        }
        
        // 렌더링 분석
        float renderingTime = ProfilerDriver.GetFormattedStatisticsValue(frameIndex, ProfilerArea.Rendering, "Camera.Render");
        if (renderingTime > 16.67f) // 60 FPS 기준
        {
            detectedIssues.Add(new PerformanceIssue
            {
                category = "Rendering",
                description = $"높은 렌더링 시간: {renderingTime:F2}ms",
                severity = Mathf.Clamp01(renderingTime / 50f),
                suggestion = "드로우콜을 줄이거나 LOD 시스템을 최적화하세요",
                frameNumber = frameIndex
            });
        }
        
        // 가비지 컬렉션 분석
        float gcTime = ProfilerDriver.GetFormattedStatisticsValue(frameIndex, ProfilerArea.Memory, "GC.Collect");
        if (gcTime > 1f)
        {
            detectedIssues.Add(new PerformanceIssue
            {
                category = "GC",
                description = $"가비지 컬렉션 지연: {gcTime:F2}ms",
                severity = Mathf.Clamp01(gcTime / 10f),
                suggestion = "메모리 할당을 줄이고 오브젝트 풀링을 사용하세요",
                frameNumber = frameIndex
            });
        }
    }
    
    void DrawIssueList()
    {
        GUILayout.Label($"발견된 성능 이슈 ({detectedIssues.Count}개)", EditorStyles.boldLabel);
        
        if (detectedIssues.Count == 0)
        {
            GUILayout.Label("성능 이슈가 발견되지 않았습니다.");
            return;
        }
        
        scrollPosition = GUILayout.BeginScrollView(scrollPosition, GUILayout.Height(200));
        
        var groupedIssues = detectedIssues.GroupBy(i => i.category);
        
        foreach (var group in groupedIssues)
        {
            GUILayout.Label(group.Key, EditorStyles.boldLabel);
            
            foreach (var issue in group.Take(5)) // 카테고리당 최대 5개만 표시
            {
                Color originalColor = GUI.color;
                GUI.color = GetSeverityColor(issue.severity);
                
                GUILayout.BeginVertical("box");
                GUILayout.Label($"프레임 {issue.frameNumber}: {issue.description}");
                GUILayout.Label($"제안: {issue.suggestion}", EditorStyles.wordWrappedMiniLabel);
                GUILayout.EndVertical();
                
                GUI.color = originalColor;
            }
            
            GUILayout.Space(5);
        }
        
        GUILayout.EndScrollView();
    }
    
    Color GetSeverityColor(float severity)
    {
        if (severity > 0.8f) return Color.red;
        else if (severity > 0.5f) return Color.yellow;
        else return Color.green;
    }
    
    void DrawOptimizationSuggestions()
    {
        GUILayout.Label("최적화 제안", EditorStyles.boldLabel);
        
        var categoryGroups = detectedIssues.GroupBy(i => i.category);
        
        foreach (var group in categoryGroups)
        {
            string category = group.Key;
            int issueCount = group.Count();
            float avgSeverity = group.Average(i => i.severity);
            
            GUILayout.BeginVertical("box");
            GUILayout.Label($"{category} 최적화 ({issueCount}개 이슈, 심각도: {avgSeverity:F2})");
            
            switch (category)
            {
                case "CPU":
                    GUILayout.Label("• Update 함수 최적화", EditorStyles.miniLabel);
                    GUILayout.Label("• 코루틴 사용 고려", EditorStyles.miniLabel);
                    GUILayout.Label("• 물리 연산 최적화", EditorStyles.miniLabel);
                    break;
                    
                case "Memory":
                    GUILayout.Label("• 오브젝트 풀링 적용", EditorStyles.miniLabel);
                    GUILayout.Label("• 메모리 누수 체크", EditorStyles.miniLabel);
                    GUILayout.Label("• 에셋 언로딩", EditorStyles.miniLabel);
                    break;
                    
                case "Rendering":
                    GUILayout.Label("• 배칭 최적화", EditorStyles.miniLabel);
                    GUILayout.Label("• LOD 시스템 적용", EditorStyles.miniLabel);
                    GUILayout.Label("• 컬링 최적화", EditorStyles.miniLabel);
                    break;
                    
                case "GC":
                    GUILayout.Label("• string 할당 최소화", EditorStyles.miniLabel);
                    GUILayout.Label("• 배열 재사용", EditorStyles.miniLabel);
                    GUILayout.Label("• StringBuilder 사용", EditorStyles.miniLabel);
                    break;
            }
            
            GUILayout.EndVertical();
        }
    }
}
#endif
```

Unity Profiler를 활용한 체계적인 성능 분석을 통해 앱인토스 게임의 성능 병목점을 정확히 진단하고 최적화하세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/debug/debug-exception.md'
---
# Unity WebGL 디버깅 및 예외 처리 가이드

Unity WebGL에서의 디버깅과 예외 처리는 앱인토스 플랫폼에서 안정적인 게임 서비스를 위해 필수예요.\
이 가이드는 효과적인 디버깅 방법과 예외 처리 전략을 제공해요.

***

## 디버깅 시스템

### 1. 통합 로깅 시스템

```c#
using UnityEngine;
using System.Collections.Generic;
using System.Text;
using System;

public enum LogLevel
{
    Debug,
    Info,
    Warning,
    Error,
    Critical
}

public class DebugLogger : MonoBehaviour
{
    [Header("로깅 설정")]
    public bool enableConsoleOutput = true;
    public bool enableFileOutput = false;
    public bool enableWebOutput = true;
    public LogLevel minLogLevel = LogLevel.Debug;
    
    [Header("웹 출력 설정")]
    public int maxWebLogs = 100;
    public bool sendToAppsInToss = true;
    
    private static DebugLogger instance;
    private Queue<LogEntry> logBuffer = new Queue<LogEntry>();
    private StringBuilder logStringBuilder = new StringBuilder();
    
    [System.Serializable]
    public class LogEntry
    {
        public LogLevel level;
        public string message;
        public string stackTrace;
        public DateTime timestamp;
        public string tag;
        
        public LogEntry(LogLevel level, string message, string stackTrace = "", string tag = "")
        {
            this.level = level;
            this.message = message;
            this.stackTrace = stackTrace;
            this.timestamp = DateTime.Now;
            this.tag = tag;
        }
        
        public string ToJson()
        {
            return JsonUtility.ToJson(this);
        }
    }
    
    public static DebugLogger Instance
    {
        get
        {
            if (instance == null)
            {
                GameObject loggerGO = new GameObject("DebugLogger");
                instance = loggerGO.AddComponent<DebugLogger>();
                DontDestroyOnLoad(loggerGO);
            }
            return instance;
        }
    }
    
    private void Awake()
    {
        if (instance == null)
        {
            instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeLogger();
        }
        else if (instance != this)
        {
            Destroy(gameObject);
        }
    }
    
    private void InitializeLogger()
    {
        // Unity의 기본 로그 핸들러 오버라이드
        Application.logMessageReceived += HandleUnityLog;
        
        LogInfo("DebugLogger 초기화 완료", "System");
    }
    
    private void HandleUnityLog(string logString, string stackTrace, LogType type)
    {
        LogLevel level = ConvertLogType(type);
        
        if (level >= minLogLevel)
        {
            LogEntry entry = new LogEntry(level, logString, stackTrace, "Unity");
            AddLogEntry(entry);
        }
    }
    
    private LogLevel ConvertLogType(LogType unityLogType)
    {
        switch (unityLogType)
        {
            case LogType.Log: return LogLevel.Info;
            case LogType.Warning: return LogLevel.Warning;
            case LogType.Error: return LogLevel.Error;
            case LogType.Exception: return LogLevel.Critical;
            case LogType.Assert: return LogLevel.Error;
            default: return LogLevel.Info;
        }
    }
    
    private void AddLogEntry(LogEntry entry)
    {
        logBuffer.Enqueue(entry);
        
        // 버퍼 크기 제한
        while (logBuffer.Count > maxWebLogs)
        {
            logBuffer.Dequeue();
        }
        
        // 출력 처리
        if (enableConsoleOutput)
        {
            Debug.Log($"[{entry.level}][{entry.tag}] {entry.message}");
        }
        
        if (enableWebOutput)
        {
            SendLogToWeb(entry);
        }
        
        if (sendToAppsInToss)
        {
            SendLogToAppsInToss(entry);
        }
    }
    
    private void SendLogToWeb(LogEntry entry)
    {
        string logData = entry.ToJson();
        Application.ExternalCall("ReceiveUnityLog", logData);
    }
    
    private void SendLogToAppsInToss(LogEntry entry)
    {
        if (entry.level >= LogLevel.Error)
        {
            Application.ExternalCall("SendErrorToAppsInToss", entry.ToJson());
        }
    }
    
    // 공개 로깅 메서드들
    public static void LogDebug(string message, string tag = "")
    {
        Instance.AddLogEntry(new LogEntry(LogLevel.Debug, message, "", tag));
    }
    
    public static void LogInfo(string message, string tag = "")
    {
        Instance.AddLogEntry(new LogEntry(LogLevel.Info, message, "", tag));
    }
    
    public static void LogWarning(string message, string tag = "")
    {
        Instance.AddLogEntry(new LogEntry(LogLevel.Warning, message, "", tag));
    }
    
    public static void LogError(string message, string tag = "", Exception exception = null)
    {
        string stackTrace = exception?.StackTrace ?? Environment.StackTrace;
        Instance.AddLogEntry(new LogEntry(LogLevel.Error, message, stackTrace, tag));
    }
    
    public static void LogCritical(string message, string tag = "", Exception exception = null)
    {
        string stackTrace = exception?.StackTrace ?? Environment.StackTrace;
        Instance.AddLogEntry(new LogEntry(LogLevel.Critical, message, stackTrace, tag));
    }
    
    // 로그 내보내기
    public string ExportLogs()
    {
        logStringBuilder.Clear();
        
        foreach (LogEntry entry in logBuffer)
        {
            logStringBuilder.AppendLine($"[{entry.timestamp:yyyy-MM-dd HH:mm:ss}] [{entry.level}] [{entry.tag}] {entry.message}");
            if (!string.IsNullOrEmpty(entry.stackTrace))
            {
                logStringBuilder.AppendLine($"Stack Trace: {entry.stackTrace}");
            }
            logStringBuilder.AppendLine();
        }
        
        return logStringBuilder.ToString();
    }
}
```

### 2. 시각적 디버그 도구

```c#
using UnityEngine;
using System.Collections.Generic;

public class VisualDebugger : MonoBehaviour
{
    [Header("디스플레이 설정")]
    public bool showDebugGUI = false;
    public KeyCode toggleKey = KeyCode.F12;
    public Color debugColor = Color.green;
    
    [Header("성능 모니터링")]
    public bool showFPS = true;
    public bool showMemory = true;
    public bool showDrawCalls = true;
    
    private static Dictionary<string, object> debugVariables = new Dictionary<string, object>();
    private static List<DebugCommand> debugCommands = new List<DebugCommand>();
    private Vector2 scrollPosition;
    private string commandInput = "";
    
    public class DebugCommand
    {
        public string name;
        public string description;
        public System.Action<string[]> action;
        
        public DebugCommand(string name, string description, System.Action<string[]> action)
        {
            this.name = name;
            this.description = description;
            this.action = action;
        }
    }
    
    private void Start()
    {
        RegisterDefaultCommands();
    }
    
    private void Update()
    {
        if (Input.GetKeyDown(toggleKey))
        {
            showDebugGUI = !showDebugGUI;
        }
    }
    
    private void RegisterDefaultCommands()
    {
        // 기본 디버그 명령어들
        RegisterCommand("fps", "FPS 표시 토글", (args) => {
            showFPS = !showFPS;
            DebugLogger.LogInfo($"FPS 표시: {showFPS}", "Debug");
        });
        
        RegisterCommand("memory", "메모리 정보 표시", (args) => {
            long memory = System.GC.GetTotalMemory(false);
            DebugLogger.LogInfo($"현재 메모리 사용량: {memory / 1024 / 1024} MB", "Debug");
        });
        
        RegisterCommand("quality", "품질 설정 변경", (args) => {
            if (args.Length > 0 && int.TryParse(args[0], out int level))
            {
                QualitySettings.SetQualityLevel(level);
                DebugLogger.LogInfo($"품질 레벨을 {level}로 변경", "Debug");
            }
        });
        
        RegisterCommand("timescale", "타임 스케일 변경", (args) => {
            if (args.Length > 0 && float.TryParse(args[0], out float scale))
            {
                Time.timeScale = scale;
                DebugLogger.LogInfo($"타임 스케일을 {scale}로 변경", "Debug");
            }
        });
    }
    
    private void OnGUI()
    {
        if (!showDebugGUI) return;
        
        GUILayout.BeginArea(new Rect(10, 10, Screen.width - 20, Screen.height - 20));
        
        GUILayout.BeginVertical("box");
        GUILayout.Label("Unity WebGL 디버그 콘솔", GUI.skin.box);
        
        // 성능 정보
        if (showFPS || showMemory || showDrawCalls)
        {
            GUILayout.BeginHorizontal();
            
            if (showFPS)
            {
                float fps = 1.0f / Time.smoothDeltaTime;
                GUILayout.Label($"FPS: {fps:F1}");
            }
            
            if (showMemory)
            {
                long memory = System.GC.GetTotalMemory(false);
                GUILayout.Label($"Memory: {memory / 1024 / 1024} MB");
            }
            
            if (showDrawCalls)
            {
                GUILayout.Label($"Quality: {QualitySettings.GetQualityLevel()}");
            }
            
            GUILayout.EndHorizontal();
        }
        
        GUILayout.Space(10);
        
        // 디버그 변수들
        if (debugVariables.Count > 0)
        {
            GUILayout.Label("디버그 변수:", GUI.skin.box);
            
            scrollPosition = GUILayout.BeginScrollView(scrollPosition, GUILayout.Height(150));
            
            foreach (var kvp in debugVariables)
            {
                GUILayout.Label($"{kvp.Key}: {kvp.Value}");
            }
            
            GUILayout.EndScrollView();
        }
        
        // 명령어 입력
        GUILayout.Label("명령어 입력:");
        
        GUILayout.BeginHorizontal();
        commandInput = GUILayout.TextField(commandInput);
        
        if (GUILayout.Button("실행") || (Event.current.type == EventType.KeyDown && Event.current.keyCode == KeyCode.Return))
        {
            ExecuteCommand(commandInput);
            commandInput = "";
        }
        
        GUILayout.EndHorizontal();
        
        // 사용 가능한 명령어 목록
        GUILayout.Label("사용 가능한 명령어:");
        foreach (var command in debugCommands)
        {
            GUILayout.Label($"• {command.name}: {command.description}");
        }
        
        GUILayout.EndVertical();
        GUILayout.EndArea();
    }
    
    // 디버그 변수 등록/업데이트
    public static void SetDebugVariable(string name, object value)
    {
        debugVariables[name] = value;
    }
    
    public static void RemoveDebugVariable(string name)
    {
        debugVariables.Remove(name);
    }
    
    // 디버그 명령어 등록
    public static void RegisterCommand(string name, string description, System.Action<string[]> action)
    {
        debugCommands.Add(new DebugCommand(name, description, action));
    }
    
    private void ExecuteCommand(string input)
    {
        if (string.IsNullOrEmpty(input)) return;
        
        string[] parts = input.Split(' ');
        string commandName = parts[0].ToLower();
        string[] args = parts.Length > 1 ? 
            new string[parts.Length - 1] : new string[0];
        
        if (args.Length > 0)
        {
            System.Array.Copy(parts, 1, args, 0, args.Length);
        }
        
        foreach (var command in debugCommands)
        {
            if (command.name.Equals(commandName, System.StringComparison.OrdinalIgnoreCase))
            {
                command.action?.Invoke(args);
                return;
            }
        }
        
        DebugLogger.LogWarning($"알 수 없는 명령어: {commandName}", "Debug");
    }
}
```

***

## 예외 처리 시스템

### 1. 중앙 집중식 예외 처리

```c#
using UnityEngine;
using System;
using System.Collections.Generic;

public class ExceptionHandler : MonoBehaviour
{
    [Header("예외 처리 설정")]
    public bool enableGlobalHandling = true;
    public bool enableRecoveryAttempts = true;
    public int maxRecoveryAttempts = 3;
    
    private static ExceptionHandler instance;
    private Dictionary<Type, Func<Exception, bool>> recoveryStrategies = new Dictionary<Type, Func<Exception, bool>>();
    private Dictionary<Type, int> exceptionCounts = new Dictionary<Type, int>();
    
    public static ExceptionHandler Instance
    {
        get
        {
            if (instance == null)
            {
                GameObject handlerGO = new GameObject("ExceptionHandler");
                instance = handlerGO.AddComponent<ExceptionHandler>();
                DontDestroyOnLoad(handlerGO);
            }
            return instance;
        }
    }
    
    private void Awake()
    {
        if (instance == null)
        {
            instance = this;
            DontDestroyOnLoad(gameObject);
            SetupExceptionHandling();
        }
        else if (instance != this)
        {
            Destroy(gameObject);
        }
    }
    
    private void SetupExceptionHandling()
    {
        if (enableGlobalHandling)
        {
            Application.logMessageReceived += HandleLogMessage;
        }
        
        RegisterRecoveryStrategies();
    }
    
    private void RegisterRecoveryStrategies()
    {
        // OutOfMemoryException 복구 전략
        recoveryStrategies[typeof(OutOfMemoryException)] = RecoverFromOutOfMemory;
        
        // NullReferenceException 복구 전략
        recoveryStrategies[typeof(NullReferenceException)] = RecoverFromNullReference;
        
        // ArgumentException 복구 전략
        recoveryStrategies[typeof(ArgumentException)] = RecoverFromInvalidArgument;
    }
    
    private void HandleLogMessage(string logString, string stackTrace, LogType type)
    {
        if (type == LogType.Exception)
        {
            HandleException(logString, stackTrace);
        }
    }
    
    public bool HandleException(Exception exception)
    {
        return HandleException(exception.Message, exception.StackTrace, exception.GetType());
    }
    
    public bool HandleException(string message, string stackTrace, Type exceptionType = null)
    {
        // 예외 카운트 증가
        if (exceptionType != null)
        {
            exceptionCounts[exceptionType] = exceptionCounts.GetValueOrDefault(exceptionType, 0) + 1;
        }
        
        // 로깅
        DebugLogger.LogError($"예외 발생: {message}", "Exception");
        DebugLogger.LogError($"스택 트레이스: {stackTrace}", "Exception");
        
        // 복구 시도
        bool recovered = false;
        if (enableRecoveryAttempts && exceptionType != null)
        {
            recovered = AttemptRecovery(exceptionType);
        }
        
        // AppsInToss에 리포트
        ReportExceptionToAppsInToss(message, stackTrace, exceptionType, recovered);
        
        return recovered;
    }
    
    private bool AttemptRecovery(Type exceptionType)
    {
        if (recoveryStrategies.TryGetValue(exceptionType, out Func<Exception, bool> strategy))
        {
            try
            {
                return strategy(null); // 간소화된 호출
            }
            catch (Exception recoveryException)
            {
                DebugLogger.LogError($"복구 시도 중 예외 발생: {recoveryException.Message}", "Exception");
                return false;
            }
        }
        
        return false;
    }
    
    private bool RecoverFromOutOfMemory(Exception exception)
    {
        DebugLogger.LogInfo("메모리 부족 예외 복구 시도", "Recovery");
        
        // 리소스 해제
        Resources.UnloadUnusedAssets();
        System.GC.Collect();
        System.GC.WaitForPendingFinalizers();
        System.GC.Collect();
        
        // 품질 설정 낮추기
        QualitySettings.SetQualityLevel(0);
        QualitySettings.masterTextureLimit = 2;
        
        DebugLogger.LogInfo("메모리 부족 예외 복구 완료", "Recovery");
        return true;
    }
    
    private bool RecoverFromNullReference(Exception exception)
    {
        DebugLogger.LogInfo("NullReference 예외 복구 시도", "Recovery");
        
        // 필수 컴포넌트들 재초기화 시도
        try
        {
            // 게임 매니저 재초기화
            var gameManager = FindObjectOfType<GameManager>();
            if (gameManager != null)
            {
                gameManager.SendMessage("Reinitialize", SendMessageOptions.DontRequireReceiver);
            }
            
            return true;
        }
        catch
        {
            return false;
        }
    }
    
    private bool RecoverFromInvalidArgument(Exception exception)
    {
        DebugLogger.LogInfo("잘못된 인수 예외 복구 시도", "Recovery");
        
        // 기본값으로 재설정
        // 구체적인 복구 로직은 게임에 따라 다름
        return true;
    }
    
    private void ReportExceptionToAppsInToss(string message, string stackTrace, Type exceptionType, bool recovered)
    {
        string exceptionData = JsonUtility.ToJson(new {
            message = message,
            stackTrace = stackTrace,
            exceptionType = exceptionType?.Name ?? "Unknown",
            recovered = recovered,
            timestamp = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"),
            exceptionCount = exceptionType != null ? exceptionCounts.GetValueOrDefault(exceptionType, 0) : 0
        });
        
        Application.ExternalCall("SendExceptionToAppsInToss", exceptionData);
    }
    
    // 예외 통계
    public void GetExceptionStatistics()
    {
        DebugLogger.LogInfo("=== 예외 통계 ===", "Statistics");
        
        foreach (var kvp in exceptionCounts)
        {
            DebugLogger.LogInfo($"{kvp.Key.Name}: {kvp.Value}회", "Statistics");
        }
    }
}
```

### 2. 안전한 코루틴 래퍼

```c#
using UnityEngine;
using System.Collections;
using System;

public static class SafeCoroutines
{
    public static Coroutine StartSafe(MonoBehaviour behaviour, IEnumerator routine, string routineName = "")
    {
        return behaviour.StartCoroutine(SafeWrapper(routine, routineName));
    }
    
    private static IEnumerator SafeWrapper(IEnumerator routine, string routineName)
    {
        bool hasError = false;
        
        while (true)
        {
            object current = null;
            bool moveNext = false;
            
            try
            {
                moveNext = routine.MoveNext();
                current = routine.Current;
            }
            catch (Exception e)
            {
                hasError = true;
                string name = string.IsNullOrEmpty(routineName) ? "Unknown" : routineName;
                DebugLogger.LogError($"코루틴 '{name}'에서 예외 발생: {e.Message}", "Coroutine", e);
                
                // 예외 처리
                ExceptionHandler.Instance.HandleException(e);
                
                // 코루틴 종료
                yield break;
            }
            
            if (!moveNext)
                break;
            
            yield return current;
        }
        
        if (!hasError)
        {
            string name = string.IsNullOrEmpty(routineName) ? "Unknown" : routineName;
            DebugLogger.LogDebug($"코루틴 '{name}' 정상 완료", "Coroutine");
        }
    }
}

// 사용 예제
public class SafeCoroutineExample : MonoBehaviour
{
    private void Start()
    {
        SafeCoroutines.StartSafe(this, RiskyOperation(), "RiskyOperation");
    }
    
    private IEnumerator RiskyOperation()
    {
        for (int i = 0; i < 10; i++)
        {
            // 위험할 수 있는 작업
            yield return new WaitForSeconds(1f);
            
            if (i == 5)
            {
                // 의도적으로 예외 발생 시켜보기
                throw new InvalidOperationException("테스트 예외");
            }
        }
    }
}
```

***

## 성능 이슈 진단

### 1. 자동 성능 진단 도구

```c#
using UnityEngine;
using System.Collections.Generic;
using System.Linq;

public class PerformanceDiagnostics : MonoBehaviour
{
    [Header("진단 설정")]
    public bool enableAutoDiagnosis = true;
    public float diagnosisInterval = 5f;
    public float fpsThreshold = 30f;
    public float memoryThreshold = 100f; // MB
    
    private List<DiagnosticResult> diagnosticHistory = new List<DiagnosticResult>();
    
    [System.Serializable]
    public class DiagnosticResult
    {
        public float timestamp;
        public float fps;
        public float memoryUsage;
        public int activeObjects;
        public int activeRenderers;
        public string[] issues;
        public string[] recommendations;
    }
    
    private void Start()
    {
        if (enableAutoDiagnosis)
        {
            InvokeRepeating(nameof(RunDiagnosis), diagnosisInterval, diagnosisInterval);
        }
    }
    
    private void RunDiagnosis()
    {
        DiagnosticResult result = new DiagnosticResult
        {
            timestamp = Time.time,
            fps = 1.0f / Time.smoothDeltaTime,
            memoryUsage = System.GC.GetTotalMemory(false) / 1024f / 1024f,
            activeObjects = FindObjectsOfType<GameObject>().Length,
            activeRenderers = FindObjectsOfType<Renderer>().Where(r => r.enabled).Count()
        };
        
        List<string> issues = new List<string>();
        List<string> recommendations = new List<string>();
        
        // FPS 문제 진단
        if (result.fps < fpsThreshold)
        {
            issues.Add($"낮은 FPS: {result.fps:F1}");
            
            // 원인 분석
            if (result.activeRenderers > 100)
            {
                recommendations.Add("렌더러 수 감소 (현재: " + result.activeRenderers + ")");
            }
            
            if (QualitySettings.GetQualityLevel() > 2)
            {
                recommendations.Add("품질 설정 낮추기");
            }
        }
        
        // 메모리 문제 진단
        if (result.memoryUsage > memoryThreshold)
        {
            issues.Add($"높은 메모리 사용량: {result.memoryUsage:F1}MB");
            recommendations.Add("Resources.UnloadUnusedAssets() 호출");
            recommendations.Add("GC.Collect() 실행");
        }
        
        // 오브젝트 수 진단
        if (result.activeObjects > 1000)
        {
            issues.Add($"과도한 활성 오브젝트: {result.activeObjects}");
            recommendations.Add("오브젝트 풀링 사용");
            recommendations.Add("비활성화 가능한 오브젝트 정리");
        }
        
        result.issues = issues.ToArray();
        result.recommendations = recommendations.ToArray();
        
        diagnosticHistory.Add(result);
        
        // 히스토리 크기 제한
        if (diagnosticHistory.Count > 20)
        {
            diagnosticHistory.RemoveAt(0);
        }
        
        // 문제가 있는 경우 로그
        if (issues.Count > 0)
        {
            DebugLogger.LogWarning($"성능 문제 감지: {string.Join(", ", issues)}", "Performance");
            DebugLogger.LogInfo($"권장사항: {string.Join(", ", recommendations)}", "Performance");
        }
        
        // AppsInToss에 진단 결과 전송
        SendDiagnosticResultToAppsInToss(result);
    }
    
    private void SendDiagnosticResultToAppsInToss(DiagnosticResult result)
    {
        string diagnosticData = JsonUtility.ToJson(result);
        Application.ExternalCall("SendDiagnosticDataToAppsInToss", diagnosticData);
    }
    
    public DiagnosticResult GetLatestDiagnostic()
    {
        return diagnosticHistory.LastOrDefault();
    }
    
    public DiagnosticResult[] GetDiagnosticHistory()
    {
        return diagnosticHistory.ToArray();
    }
}
```

***

## 문제 해결 가이드

### 일반적인 WebGL 문제들

1. 메모리 관련 문제
   * Out of Memory 에러
   * 가비지 컬렉션으로 인한 끊김
   * 메모리 누수

2. 성능 문제
   * 낮은 프레임률
   * 긴 로딩 시간
   * 버벅거림

3. 호환성 문제
   * 브라우저별 차이
   * 모바일 기기 대응
   * 오래된 디바이스 지원

### 해결 전략

```c#
public class TroubleshootingHelper : MonoBehaviour
{
    public static void DiagnoseCommonIssues()
    {
        DebugLogger.LogInfo("=== 일반적인 문제 진단 ===", "Troubleshooting");
        
        // 1. 메모리 체크
        long memory = System.GC.GetTotalMemory(false);
        if (memory > 100 * 1024 * 1024) // 100MB
        {
            DebugLogger.LogWarning("높은 메모리 사용량 감지", "Troubleshooting");
            DebugLogger.LogInfo("권장사항: Resources.UnloadUnusedAssets() 호출", "Troubleshooting");
        }
        
        // 2. 품질 설정 체크
        int qualityLevel = QualitySettings.GetQualityLevel();
        if (qualityLevel > 2)
        {
            DebugLogger.LogInfo($"현재 품질 레벨: {qualityLevel} (높음)", "Troubleshooting");
            DebugLogger.LogInfo("권장사항: 모바일 환경에서는 품질 낮추기", "Troubleshooting");
        }
        
        // 3. 렌더러 수 체크
        int rendererCount = FindObjectsOfType<Renderer>().Length;
        if (rendererCount > 100)
        {
            DebugLogger.LogWarning($"많은 렌더러 수: {rendererCount}", "Troubleshooting");
            DebugLogger.LogInfo("권장사항: 배칭 최적화 또는 LOD 사용", "Troubleshooting");
        }
        
        // 4. 텍스처 설정 체크
        Texture2D[] textures = Resources.FindObjectsOfTypeAll<Texture2D>();
        int uncompressedTextures = textures.Count(t => t.format == TextureFormat.RGBA32);
        
        if (uncompressedTextures > 10)
        {
            DebugLogger.LogWarning($"압축되지 않은 텍스처: {uncompressedTextures}개", "Troubleshooting");
            DebugLogger.LogInfo("권장사항: 텍스처 압축 적용", "Troubleshooting");
        }
    }
}
```

***

## 베스트 프랙티스

1. **프로액티브 로깅** - 문제가 발생하기 전에 충분한 로그 수집
2. **예외 복구 전략** - 예외 발생 시 게임이 계속 실행될 수 있도록 복구 로직 구현
3. **성능 모니터링** - 지속적인 성능 모니터링으로 문제 조기 발견
4. **AppsInToss 연동** - 플랫폼 기능을 활용한 효과적인 디버깅
5. **사용자 피드백** - 사용자가 겪는 문제를 쉽게 리포트할 수 있는 시스템 구축

이 가이드를 통해 Unity WebGL 게임의 안정성과 디버깅 효율성을 크게 향상시킬 수 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/performance.md
---
# Unity WebGL 런타임 성능 최적화 가이드

Unity WebGL 환경에서 런타임 성능을 최적화하는 건, 앱인토스 미니앱에서 부드러운 게임 경험을 만드는 핵심이에요.\
이 가이드에서는 프레임률 향상, CPU 사용량 감소, GPU 최적화 방법을 함께 다뤄요.

***

## CPU 최적화

### 1. 프레임률 관리 시스템

```c#
using UnityEngine;
using System.Collections;

public class PerformanceManager : MonoBehaviour
{
    [Header("성능 설정")]
    public int targetFrameRate = 60;
    public bool adaptiveFrameRate = true;
    public float performanceCheckInterval = 2f;
    
    [Header("성능 임계값")]
    public float lowPerformanceThreshold = 40f;
    public float highPerformanceThreshold = 55f;
    
    private float averageFrameRate;
    private int qualityLevel;
    private bool isLowPerformanceMode = false;
    
    private void Start()
    {
        qualityLevel = QualitySettings.GetQualityLevel();
        Application.targetFrameRate = targetFrameRate;
        
        if (adaptiveFrameRate)
        {
            StartCoroutine(AdaptivePerformanceRoutine());
        }
    }
    
    private IEnumerator AdaptivePerformanceRoutine()
    {
        while (true)
        {
            yield return new WaitForSeconds(performanceCheckInterval);
            
            averageFrameRate = 1.0f / Time.smoothDeltaTime;
            AdjustPerformanceSettings();
            
            // AppsInToss 플랫폼에 성능 정보 전송
            SendPerformanceDataToAppsInToss();
        }
    }
    
    private void AdjustPerformanceSettings()
    {
        if (averageFrameRate < lowPerformanceThreshold && !isLowPerformanceMode)
        {
            EnableLowPerformanceMode();
        }
        else if (averageFrameRate > highPerformanceThreshold && isLowPerformanceMode)
        {
            DisableLowPerformanceMode();
        }
    }
    
    private void EnableLowPerformanceMode()
    {
        isLowPerformanceMode = true;
        
        // 품질 설정 낮추기
        QualitySettings.SetQualityLevel(Mathf.Max(0, qualityLevel - 1));
        
        // 그림자 비활성화
        QualitySettings.shadows = ShadowQuality.Disable;
        
        // 파티클 수 감소
        QualitySettings.particleRaycastBudget = 16;
        
        // 물리 업데이트 빈도 감소
        Time.fixedDeltaTime = 1f / 30f;
        
        Debug.Log("저성능 모드 활성화됨");
    }
    
    private void DisableLowPerformanceMode()
    {
        isLowPerformanceMode = false;
        
        // 원래 품질 설정 복원
        QualitySettings.SetQualityLevel(qualityLevel);
        QualitySettings.shadows = ShadowQuality.All;
        QualitySettings.particleRaycastBudget = 256;
        Time.fixedDeltaTime = 1f / 50f;
        
        Debug.Log("일반 성능 모드 복원됨");
    }
    
    private void SendPerformanceDataToAppsInToss()
    {
        string performanceData = JsonUtility.ToJson(new {
            frameRate = averageFrameRate,
            isLowPerformanceMode = isLowPerformanceMode,
            qualityLevel = QualitySettings.GetQualityLevel()
        });
        
        Application.ExternalCall("SendPerformanceDataToAppsInToss", performanceData);
    }
}
```

### 2. 효율적인 업데이트 관리

```c#
using UnityEngine;
using System.Collections.Generic;

public class UpdateManager : MonoBehaviour
{
    private static UpdateManager instance;
    public static UpdateManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = FindObjectOfType<UpdateManager>();
                if (instance == null)
                {
                    GameObject go = new GameObject("UpdateManager");
                    instance = go.AddComponent<UpdateManager>();
                    DontDestroyOnLoad(go);
                }
            }
            return instance;
        }
    }
    
    private List<IUpdatable> updatables = new List<IUpdatable>();
    private List<IFixedUpdatable> fixedUpdatables = new List<IFixedUpdatable>();
    private List<ILateUpdatable> lateUpdatables = new List<ILateUpdatable>();
    
    // 성능 최적화를 위한 업데이트 빈도 제어
    private int frameCount = 0;
    
    private void Update()
    {
        frameCount++;
        
        // 매 프레임 업데이트
        for (int i = updatables.Count - 1; i >= 0; i--)
        {
            if (updatables[i] != null)
                updatables[i].OnUpdate();
        }
        
        // 2프레임마다 업데이트 (30Hz)
        if (frameCount % 2 == 0)
        {
            for (int i = updatables.Count - 1; i >= 0; i--)
            {
                if (updatables[i] is ISlowUpdatable slowUpdatable)
                    slowUpdatable.OnSlowUpdate();
            }
        }
    }
    
    private void FixedUpdate()
    {
        for (int i = fixedUpdatables.Count - 1; i >= 0; i--)
        {
            if (fixedUpdatables[i] != null)
                fixedUpdatables[i].OnFixedUpdate();
        }
    }
    
    private void LateUpdate()
    {
        for (int i = lateUpdatables.Count - 1; i >= 0; i--)
        {
            if (lateUpdatables[i] != null)
                lateUpdatables[i].OnLateUpdate();
        }
    }
    
    public void RegisterUpdatable(IUpdatable updatable)
    {
        if (!updatables.Contains(updatable))
            updatables.Add(updatable);
    }
    
    public void UnregisterUpdatable(IUpdatable updatable)
    {
        updatables.Remove(updatable);
    }
}

// 인터페이스들
public interface IUpdatable
{
    void OnUpdate();
}

public interface ISlowUpdatable
{
    void OnSlowUpdate();
}

public interface IFixedUpdatable
{
    void OnFixedUpdate();
}

public interface ILateUpdatable
{
    void OnLateUpdate();
}

// 사용 예제
public class OptimizedBehavior : MonoBehaviour, IUpdatable, ISlowUpdatable
{
    private Vector3 targetPosition;
    private bool needsPositionUpdate = true;
    
    private void OnEnable()
    {
        UpdateManager.Instance.RegisterUpdatable(this);
    }
    
    private void OnDisable()
    {
        UpdateManager.Instance.UnregisterUpdatable(this);
    }
    
    public void OnUpdate()
    {
        // 매 프레임 필요한 업데이트
        if (needsPositionUpdate)
        {
            transform.position = Vector3.Lerp(transform.position, targetPosition, Time.deltaTime * 5f);
            
            if (Vector3.Distance(transform.position, targetPosition) < 0.01f)
            {
                needsPositionUpdate = false;
            }
        }
    }
    
    public void OnSlowUpdate()
    {
        // 2프레임마다 수행되는 업데이트 (AI, 경로 찾기 등)
        UpdateAI();
    }
    
    private void UpdateAI()
    {
        // 비용이 큰 AI 로직
    }
}
```

***

## GPU 최적화

### 1. 배칭 최적화

```c#
using UnityEngine;
using System.Collections.Generic;

public class BatchingOptimizer : MonoBehaviour
{
    [Header("배칭 설정")]
    public bool enableStaticBatching = true;
    public bool enableDynamicBatching = true;
    public bool enableInstancing = true;
    
    [Header("인스턴싱")]
    public GameObject instancedPrefab;
    public Material instancedMaterial;
    public int maxInstances = 1000;
    
    private Matrix4x4[] instanceMatrices;
    private MaterialPropertyBlock propertyBlock;
    private Mesh instanceMesh;
    private List<Vector3> instancePositions = new List<Vector3>();
    
    private void Start()
    {
        SetupBatching();
        SetupInstancing();
    }
    
    private void SetupBatching()
    {
        // 정적 배칭 활성화
        if (enableStaticBatching)
        {
            GameObject[] staticObjects = GameObject.FindGameObjectsWithTag("StaticBatchable");
            StaticBatchingUtility.Combine(staticObjects, this.gameObject);
        }
    }
    
    private void SetupInstancing()
    {
        if (!enableInstancing || instancedPrefab == null) return;
        
        instanceMatrices = new Matrix4x4[maxInstances];
        propertyBlock = new MaterialPropertyBlock();
        
        MeshRenderer renderer = instancedPrefab.GetComponent<MeshRenderer>();
        if (renderer != null)
        {
            instanceMesh = instancedPrefab.GetComponent<MeshFilter>().sharedMesh;
        }
    }
    
    private void Update()
    {
        if (enableInstancing && instanceMesh != null)
        {
            RenderInstances();
        }
    }
    
    private void RenderInstances()
    {
        int instanceCount = Mathf.Min(instancePositions.Count, maxInstances);
        
        for (int i = 0; i < instanceCount; i++)
        {
            instanceMatrices[i] = Matrix4x4.TRS(instancePositions[i], Quaternion.identity, Vector3.one);
        }
        
        Graphics.DrawMeshInstanced(
            instanceMesh, 
            0, 
            instancedMaterial, 
            instanceMatrices, 
            instanceCount, 
            propertyBlock
        );
    }
    
    public void AddInstance(Vector3 position)
    {
        if (instancePositions.Count < maxInstances)
        {
            instancePositions.Add(position);
        }
    }
    
    public void RemoveInstance(Vector3 position)
    {
        instancePositions.Remove(position);
    }
    
    public void ClearInstances()
    {
        instancePositions.Clear();
    }
}
```

### 2. 텍스처 아틀라스 관리

```c#
using UnityEngine;
using System.Collections.Generic;

[CreateAssetMenu(fileName = "TextureAtlasConfig", menuName = "Performance/Texture Atlas Config")]
public class TextureAtlasConfig : ScriptableObject
{
    [System.Serializable]
    public class AtlasEntry
    {
        public string name;
        public Texture2D texture;
        public Rect uvRect;
    }
    
    [Header("아틀라스 설정")]
    public Texture2D atlasTexture;
    public List<AtlasEntry> entries = new List<AtlasEntry>();
    public int atlasSize = 2048;
    
    private Dictionary<string, Rect> uvLookup;
    
    public void Initialize()
    {
        uvLookup = new Dictionary<string, Rect>();
        foreach (var entry in entries)
        {
            uvLookup[entry.name] = entry.uvRect;
        }
    }
    
    public Rect GetUVRect(string textureName)
    {
        if (uvLookup == null) Initialize();
        
        return uvLookup.TryGetValue(textureName, out Rect rect) ? rect : new Rect(0, 0, 1, 1);
    }
}

public class TextureAtlasManager : MonoBehaviour
{
    [Header("아틀라스 설정")]
    public TextureAtlasConfig atlasConfig;
    public Material atlasMaterial;
    
    private void Start()
    {
        if (atlasConfig != null)
        {
            atlasConfig.Initialize();
            ApplyAtlasToMaterials();
        }
    }
    
    private void ApplyAtlasToMaterials()
    {
        // 씬의 모든 렌더러에 아틀라스 적용
        MeshRenderer[] renderers = FindObjectsOfType<MeshRenderer>();
        
        foreach (var renderer in renderers)
        {
            if (renderer.material.name.Contains("Atlasable"))
            {
                renderer.material = atlasMaterial;
                
                // UV 좌표 조정
                string textureName = renderer.name; // 또는 다른 식별 방법
                Rect uvRect = atlasConfig.GetUVRect(textureName);
                renderer.material.SetVector("_MainTex_ST", new Vector4(uvRect.width, uvRect.height, uvRect.x, uvRect.y));
            }
        }
    }
}
```

***

## AppsInToss 플랫폼 연동

### 1. 성능 모니터링 시스템

```tsx

interface PerformanceMetrics {
    frameRate: number;
    drawCalls: number;
    triangles: number;
    vertices: number;
    memoryUsage: number;
    loadTime: number;
}

class PerformanceMonitor {
    private static instance: PerformanceMonitor;
    private metrics: PerformanceMetrics = {
        frameRate: 0,
        drawCalls: 0,
        triangles: 0,
        vertices: 0,
        memoryUsage: 0,
        loadTime: 0
    };
    
    private frameCount = 0;
    private lastTime = 0;
    
    public static getInstance(): PerformanceMonitor {
        if (!PerformanceMonitor.instance) {
            PerformanceMonitor.instance = new PerformanceMonitor();
        }
        return PerformanceMonitor.instance;
    }
    
    public startMonitoring(): void {
        this.lastTime = performance.now();
        this.monitoringLoop();
    }
    
    private monitoringLoop(): void {
        const currentTime = performance.now();
        this.frameCount++;
        
        // FPS 계산 (1초마다)
        if (currentTime - this.lastTime >= 1000) {
            this.metrics.frameRate = this.frameCount;
            this.frameCount = 0;
            this.lastTime = currentTime;
            
            this.collectMetrics();
        }
        
        requestAnimationFrame(() => this.monitoringLoop());
    }
    
    private collectMetrics(): void {
        // Unity에서 성능 메트릭 수집
        const unityInstance = (window as any).unityInstance;
        if (unityInstance) {
            // Unity에서 렌더링 통계 요청
            unityInstance.SendMessage('PerformanceManager', 'CollectRenderingStats', '');
        }
        
        // 메모리 사용량 수집
        const memInfo = (performance as any).memory;
        if (memInfo) {
            this.metrics.memoryUsage = memInfo.usedJSHeapSize;
        }
    }
    
    public updateMetrics(data: Partial<PerformanceMetrics>): void {
        Object.assign(this.metrics, data);
    }
    
    public getMetrics(): PerformanceMetrics {
        return { ...this.metrics };
    }
    
    // 성능 경고 시스템
    public checkPerformanceWarnings(): void {
        const warnings = [];
        
        if (this.metrics.frameRate < 30) {
            warnings.push('낮은 프레임률 감지');
        }
        
        if (this.metrics.drawCalls > 200) {
            warnings.push('과도한 드로우 콜');
        }
        
        if (this.metrics.memoryUsage > 100 * 1024 * 1024) { // 100MB
            warnings.push('높은 메모리 사용량');
        }
        
    }
}

// Unity에서 호출할 함수들
(window as any).UpdatePerformanceMetrics = (data: string) => {
    const metrics = JSON.parse(data);
    PerformanceMonitor.getInstance().updateMetrics(metrics);
};

(window as any).OnUnityLoaded = () => {
    PerformanceMonitor.getInstance().startMonitoring();
};
```

### 2. 동적 품질 조정

```c#
using UnityEngine;
using System.Runtime.InteropServices;

public class DynamicQualityManager : MonoBehaviour
{
    [Header("품질 설정")]
    public QualityProfile[] qualityProfiles;
    
    [System.Serializable]
    public class QualityProfile
    {
        public string name;
        public int textureQuality;
        public ShadowQuality shadowQuality;
        public int particleBudget;
        public float renderScale;
        public bool enablePostProcessing;
    }
    
    [DllImport("__Internal")]
    private static extern void SendQualityChangeToAppsInToss(string qualityData);
    
    private int currentQualityIndex = 1; // 보통 품질로 시작
    private float lastFrameTime;
    private int lowFrameCount = 0;
    
    private void Start()
    {
        if (qualityProfiles.Length > 0)
        {
            ApplyQualityProfile(currentQualityIndex);
        }
    }
    
    private void Update()
    {
        MonitorPerformance();
    }
    
    private void MonitorPerformance()
    {
        float currentFrameTime = Time.unscaledDeltaTime;
        
        // 프레임 시간이 33ms(30fps) 이상인 경우
        if (currentFrameTime > 1f / 30f)
        {
            lowFrameCount++;
        }
        else
        {
            lowFrameCount = Mathf.Max(0, lowFrameCount - 1);
        }
        
        // 연속으로 저성능이 감지되면 품질 낮추기
        if (lowFrameCount > 10 && currentQualityIndex > 0)
        {
            ChangeQuality(currentQualityIndex - 1);
            lowFrameCount = 0;
        }
        // 성능이 개선되면 품질 올리기
        else if (lowFrameCount == 0 && currentFrameTime < 1f / 50f && currentQualityIndex < qualityProfiles.Length - 1)
        {
            ChangeQuality(currentQualityIndex + 1);
        }
        
        lastFrameTime = currentFrameTime;
    }
    
    public void ChangeQuality(int qualityIndex)
    {
        if (qualityIndex < 0 || qualityIndex >= qualityProfiles.Length) return;
        
        currentQualityIndex = qualityIndex;
        ApplyQualityProfile(qualityIndex);
        
        // AppsInToss 플랫폼에 품질 변경 알림
        NotifyQualityChange();
    }
    
    private void ApplyQualityProfile(int index)
    {
        QualityProfile profile = qualityProfiles[index];
        
        // 텍스처 품질
        QualitySettings.masterTextureLimit = profile.textureQuality;
        
        // 그림자 품질
        QualitySettings.shadows = profile.shadowQuality;
        
        // 파티클 예산
        QualitySettings.particleRaycastBudget = profile.particleBudget;
        
        // 렌더 스케일 (가능한 경우)
        if (profile.renderScale != 1f)
        {
            Camera.main.pixelRect = new Rect(0, 0, 
                Screen.width * profile.renderScale, 
                Screen.height * profile.renderScale);
        }
        
        // 포스트 프로세싱
        var postProcessVolume = FindObjectOfType<UnityEngine.Rendering.PostProcessing.PostProcessVolume>();
        if (postProcessVolume != null)
        {
            postProcessVolume.enabled = profile.enablePostProcessing;
        }
        
        Debug.Log($"품질 프로필 적용됨: {profile.name}");
    }
    
    private void NotifyQualityChange()
    {
        QualityProfile currentProfile = qualityProfiles[currentQualityIndex];
        
        string qualityData = JsonUtility.ToJson(new {
            qualityLevel = currentQualityIndex,
            qualityName = currentProfile.name,
            timestamp = Time.time
        });
        
        SendQualityChangeToAppsInToss(qualityData);
    }
    
    // 외부에서 품질 강제 변경 (AppsInToss에서 호출)
    public void ForceQualityChange(string qualityData)
    {
        var data = JsonUtility.FromJson<QualityChangeData>(qualityData);
        ChangeQuality(data.qualityLevel);
    }
    
    [System.Serializable]
    private class QualityChangeData
    {
        public int qualityLevel;
    }
}
```

***

## 렌더링 최적화

### 1. LOD (Level of Detail) 시스템

```c#
using UnityEngine;

public class DynamicLODManager : MonoBehaviour
{
    [Header("LOD 설정")]
    public float[] lodDistances = { 50f, 100f, 200f };
    public float cullDistance = 300f;
    public Transform playerTransform;
    
    [Header("성능 기반 LOD")]
    public bool enablePerformanceLOD = true;
    public float performanceThreshold = 45f; // FPS
    
    private LODGroup[] allLODGroups;
    private Camera mainCamera;
    private float performanceLODBias = 1f;
    
    private void Start()
    {
        mainCamera = Camera.main;
        allLODGroups = FindObjectsOfType<LODGroup>();
        
        if (enablePerformanceLOD)
        {
            InvokeRepeating(nameof(UpdatePerformanceLOD), 1f, 2f);
        }
    }
    
    private void Update()
    {
        UpdateLODs();
    }
    
    private void UpdateLODs()
    {
        if (playerTransform == null) return;
        
        foreach (LODGroup lodGroup in allLODGroups)
        {
            if (lodGroup == null) continue;
            
            float distance = Vector3.Distance(playerTransform.position, lodGroup.transform.position);
            
            // 컬링 거리 확인
            if (distance > cullDistance)
            {
                lodGroup.gameObject.SetActive(false);
                continue;
            }
            else if (!lodGroup.gameObject.activeInHierarchy)
            {
                lodGroup.gameObject.SetActive(true);
            }
            
            // 성능 기반 LOD 바이어스 적용
            float adjustedDistance = distance * performanceLODBias;
            
            // LOD 레벨 결정
            int lodLevel = GetLODLevel(adjustedDistance);
            lodGroup.ForceLOD(lodLevel);
        }
    }
    
    private int GetLODLevel(float distance)
    {
        for (int i = 0; i < lodDistances.Length; i++)
        {
            if (distance < lodDistances[i])
                return i;
        }
        return lodDistances.Length; // 가장 낮은 품질 또는 컬링
    }
    
    private void UpdatePerformanceLOD()
    {
        float currentFPS = 1.0f / Time.smoothDeltaTime;
        
        if (currentFPS < performanceThreshold)
        {
            // 성능이 낮으면 LOD 바이어스를 줄여서 더 낮은 품질 사용
            performanceLODBias = Mathf.Max(0.5f, performanceLODBias - 0.1f);
        }
        else if (currentFPS > performanceThreshold + 10f)
        {
            // 성능이 좋으면 LOD 바이어스를 높여서 더 높은 품질 사용
            performanceLODBias = Mathf.Min(1f, performanceLODBias + 0.1f);
        }
        
        QualitySettings.lodBias = performanceLODBias;
    }
}
```

### 2. 오클루전 컬링

```c#
using UnityEngine;
using System.Collections.Generic;

public class CustomOcclusionCulling : MonoBehaviour
{
    [Header("오클루전 설정")]
    public LayerMask occluderLayers = -1;
    public float raycastDistance = 100f;
    public int raysPerObject = 9; // 3x3 그리드
    
    [Header("성능 설정")]
    public int objectsPerFrame = 10;
    public float updateInterval = 0.1f;
    
    private List<Renderer> allRenderers = new List<Renderer>();
    private Queue<Renderer> renderersToCheck = new Queue<Renderer>();
    private Camera mainCamera;
    
    private void Start()
    {
        mainCamera = Camera.main;
        CollectRenderers();
        InvokeRepeating(nameof(ProcessOcclusion), 0f, updateInterval);
    }
    
    private void CollectRenderers()
    {
        Renderer[] renderers = FindObjectsOfType<Renderer>();
        
        foreach (Renderer renderer in renderers)
        {
            // 스킨드 메시나 파티클은 제외
            if (renderer is MeshRenderer || renderer is SpriteRenderer)
            {
                allRenderers.Add(renderer);
                renderersToCheck.Enqueue(renderer);
            }
        }
    }
    
    private void ProcessOcclusion()
    {
        int processedCount = 0;
        
        while (renderersToCheck.Count > 0 && processedCount < objectsPerFrame)
        {
            Renderer renderer = renderersToCheck.Dequeue();
            
            if (renderer != null && renderer.gameObject.activeInHierarchy)
            {
                bool isVisible = CheckVisibility(renderer);
                renderer.enabled = isVisible;
                
                // 다음 프레임에 다시 검사하도록 큐에 추가
                renderersToCheck.Enqueue(renderer);
            }
            
            processedCount++;
        }
    }
    
    private bool CheckVisibility(Renderer renderer)
    {
        Bounds bounds = renderer.bounds;
        Vector3 cameraPosition = mainCamera.transform.position;
        
        // 카메라 프러스텀 내부에 있는지 확인
        if (!GeometryUtility.TestPlanesAABB(GeometryUtility.CalculateFrustumPlanes(mainCamera), bounds))
        {
            return false;
        }
        
        // 레이캐스트를 통한 오클루전 테스트
        Vector3 boundsCenter = bounds.center;
        Vector3 boundsSize = bounds.size;
        
        int visibleRays = 0;
        
        // 3x3 그리드로 레이 발사
        for (int x = -1; x <= 1; x++)
        {
            for (int y = -1; y <= 1; y++)
            {
                Vector3 testPoint = boundsCenter + new Vector3(
                    x * boundsSize.x * 0.25f,
                    y * boundsSize.y * 0.25f,
                    0
                );
                
                Vector3 direction = (testPoint - cameraPosition).normalized;
                float distance = Vector3.Distance(cameraPosition, testPoint);
                
                if (!Physics.Raycast(cameraPosition, direction, distance, occluderLayers))
                {
                    visibleRays++;
                    if (visibleRays > raysPerObject / 3) // 1/3 이상 보이면 렌더링
                    {
                        return true;
                    }
                }
            }
        }
        
        return visibleRays > 0;
    }
}
```

***

## 물리 최적화

### 1. 물리 업데이트 관리

```c#
using UnityEngine;
using System.Collections.Generic;

public class PhysicsOptimizer : MonoBehaviour
{
    [Header("물리 설정")]
    public float physicsTimeStep = 0.02f; // 50Hz
    public int maxSubSteps = 8;
    public float sleepThreshold = 0.005f;
    
    [Header("성능 기반 조정")]
    public bool enableAdaptivePhysics = true;
    public float targetFrameRate = 60f;
    
    private List<Rigidbody> managedRigidbodies = new List<Rigidbody>();
    private float originalFixedDeltaTime;
    
    private void Start()
    {
        originalFixedDeltaTime = Time.fixedDeltaTime;
        Time.fixedDeltaTime = physicsTimeStep;
        
        Physics.sleepThreshold = sleepThreshold;
        
        CollectRigidbodies();
        
        if (enableAdaptivePhysics)
        {
            InvokeRepeating(nameof(AdaptPhysicsSettings), 1f, 2f);
        }
    }
    
    private void CollectRigidbodies()
    {
        Rigidbody[] rigidbodies = FindObjectsOfType<Rigidbody>();
        
        foreach (Rigidbody rb in rigidbodies)
        {
            managedRigidbodies.Add(rb);
            OptimizeRigidbody(rb);
        }
    }
    
    private void OptimizeRigidbody(Rigidbody rb)
    {
        // 잠자기 설정 최적화
        rb.sleepThreshold = sleepThreshold;
        
        // 불필요한 물리 연산 비활성화
        if (rb.GetComponent<Collider>() == null)
        {
            rb.detectCollisions = false;
        }
        
        // 정적 오브젝트는 키네마틱으로 설정
        if (rb.GetComponent<Collider>() != null && rb.GetComponent<Collider>().isTrigger)
        {
            rb.isKinematic = true;
        }
    }
    
    private void AdaptPhysicsSettings()
    {
        float currentFrameRate = 1.0f / Time.smoothDeltaTime;
        
        if (currentFrameRate < targetFrameRate - 10f)
        {
            // 성능이 낮으면 물리 업데이트 빈도 감소
            Time.fixedDeltaTime = Mathf.Min(0.033f, Time.fixedDeltaTime + 0.002f);
            
            // 일부 리지드바디를 잠자기 상태로 전환
            SleepDistantRigidbodies();
        }
        else if (currentFrameRate > targetFrameRate + 5f)
        {
            // 성능이 좋으면 물리 업데이트 빈도 증가
            Time.fixedDeltaTime = Mathf.Max(physicsTimeStep, Time.fixedDeltaTime - 0.002f);
        }
    }
    
    private void SleepDistantRigidbodies()
    {
        Vector3 playerPosition = Camera.main.transform.position;
        float maxActiveDistance = 50f;
        
        foreach (Rigidbody rb in managedRigidbodies)
        {
            if (rb == null) continue;
            
            float distance = Vector3.Distance(rb.transform.position, playerPosition);
            
            if (distance > maxActiveDistance && !rb.IsSleeping())
            {
                rb.Sleep();
            }
            else if (distance <= maxActiveDistance && rb.IsSleeping())
            {
                rb.WakeUp();
            }
        }
    }
}
```

***

## 프로파일링 및 디버깅

### 1. 성능 분석 도구

```c#
using UnityEngine;
using System.Text;
using System.Collections.Generic;

public class PerformanceProfiler : MonoBehaviour
{
    [Header("프로파일링 설정")]
    public bool enableProfiling = true;
    public KeyCode toggleKey = KeyCode.F1;
    public float updateInterval = 1f;
    
    private Dictionary<string, float> performanceData = new Dictionary<string, float>();
    private StringBuilder displayText = new StringBuilder();
    private bool showGUI = false;
    
    private void Update()
    {
        if (Input.GetKeyDown(toggleKey))
        {
            showGUI = !showGUI;
        }
        
        if (enableProfiling)
        {
            CollectPerformanceData();
        }
    }
    
    private void CollectPerformanceData()
    {
        // FPS
        performanceData["FPS"] = 1.0f / Time.smoothDeltaTime;
        
        // 메모리 사용량
        performanceData["Memory (MB)"] = System.GC.GetTotalMemory(false) / 1024f / 1024f;
        
        // 렌더링 통계
        performanceData["SetPass Calls"] = UnityEngine.Rendering.FrameDebugger.enabled ? 
            UnityEngine.Rendering.FrameDebugger.GetFrameEventCount() : 0;
            
        // 활성 오브젝트 수
        performanceData["Active GameObjects"] = FindObjectsOfType<GameObject>().Length;
        
        // 활성 렌더러 수
        performanceData["Active Renderers"] = FindObjectsOfType<Renderer>().Length;
    }
    
    private void OnGUI()
    {
        if (!showGUI) return;
        
        displayText.Clear();
        displayText.AppendLine("=== 성능 분석 ===");
        
        foreach (var kvp in performanceData)
        {
            displayText.AppendFormat("{0}: {1:F2}\n", kvp.Key, kvp.Value);
        }
        
        GUI.Box(new Rect(10, 10, 300, 200), displayText.ToString());
    }
    
    public void LogPerformanceData()
    {
        StringBuilder log = new StringBuilder();
        log.AppendLine("Performance Report:");
        
        foreach (var kvp in performanceData)
        {
            log.AppendFormat("{0}: {1:F2}\n", kvp.Key, kvp.Value);
        }
        
        Debug.Log(log.ToString());
        
        // AppsInToss 플랫폼에 전송
        Application.ExternalCall("SendPerformanceReport", log.ToString());
    }
}
```

***

## 베스트 프랙티스

* 적응형 성능 관리 - 실시간으로 성능을 모니터링하고 품질을 조정
* 효율적인 업데이트 - Update 함수 대신 이벤트 기반 시스템 사용
* 배칭 최적화 - 드로우 콜 수 최소화
* 메모리 관리 - 불필요한 할당과 가비지 생성 방지
* AppsInToss 플랫폼 활용 - 네이티브 성능 모니터링 기능 활용

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/runtime/memory.md'
---
# Unity WebGL 메모리 최적화 가이드

Unity WebGL에서 메모리 최적화는 성능과 안정성을 지키는 핵심이에요.\
앱인토스 미니앱에서는 제한된 메모리 안에서 게임을 효율적으로 실행하는 게 특히 중요해요.

***

## 메모리 관리 기본 원칙

### 1. 힙 메모리 관리

Unity WebGL은 고정 크기 힙을 사용합니다.

```c#
using UnityEngine;
using System.Collections;

public class MemoryManager : MonoBehaviour
{
    [Header("메모리 모니터링")]
    public bool enableMemoryMonitoring = true;
    private long lastGCMemory = 0;
    
    private void Start()
    {
        if (enableMemoryMonitoring)
        {
            StartCoroutine(MonitorMemory());
        }
    }
    
    private IEnumerator MonitorMemory()
    {
        while (true)
        {
            long currentMemory = System.GC.GetTotalMemory(false);
            
            if (currentMemory > lastGCMemory * 1.2f)
            {
                System.GC.Collect();
                Resources.UnloadUnusedAssets();
                lastGCMemory = System.GC.GetTotalMemory(true);
            }
            
            yield return new WaitForSeconds(5f);
        }
    }
    
    public void ForceCleanup()
    {
        Resources.UnloadUnusedAssets();
        System.GC.Collect();
        System.GC.WaitForPendingFinalizers();
        System.GC.Collect();
    }
}
```

### 2. 텍스처 메모리 최적화

```c#
using UnityEngine;

[System.Serializable]
public class TextureSettings
{
    [Header("품질 설정")]
    public int maxTextureSize = 512;
    public TextureFormat preferredFormat = TextureFormat.ASTC_4x4;
    public bool generateMipmaps = false;
    
    [Header("압축 설정")]
    public bool useTextureStreaming = true;
    public int memoryBudget = 64; // MB
}

public class TextureOptimizer : MonoBehaviour
{
    public TextureSettings settings;
    
    private void Start()
    {
        OptimizeTextures();
        SetupTextureStreaming();
    }
    
    private void OptimizeTextures()
    {
        QualitySettings.masterTextureLimit = 1; // 절반 해상도
        QualitySettings.globalTextureMipmapLimit = 1;
    }
    
    private void SetupTextureStreaming()
    {
        if (settings.useTextureStreaming)
        {
            QualitySettings.streamingMipmapsActive = true;
            QualitySettings.streamingMipmapsMemoryBudget = settings.memoryBudget;
        }
    }
}
```

***

## AppsInToss 플랫폼 통합

### 1. 메모리 상태 모니터링

```tsx

interface MemoryInfo {
    usedJSHeapSize: number;
    totalJSHeapSize: number;
    jsHeapSizeLimit: number;
}

class MemoryMonitor {
    private static instance: MemoryMonitor;
    private memoryThreshold: number = 0.8;
    
    public static getInstance(): MemoryMonitor {
        if (!MemoryMonitor.instance) {
            MemoryMonitor.instance = new MemoryMonitor();
        }
        return MemoryMonitor.instance;
    }
    
    public startMonitoring(): void {
        setInterval(() => {
            this.checkMemoryUsage();
        }, 3000);
    }
    
    private checkMemoryUsage(): void {
        const memInfo = this.getMemoryInfo();
        const usage = memInfo.usedJSHeapSize / memInfo.jsHeapSizeLimit;
        
        if (usage > this.memoryThreshold) {
            this.requestMemoryCleanup();
        }
    }
    
    private getMemoryInfo(): MemoryInfo {
        const performance = (window as any).performance;
        return performance.memory || {
            usedJSHeapSize: 0,
            totalJSHeapSize: 0,
            jsHeapSizeLimit: 0
        };
    }
    
    private requestMemoryCleanup(): void {
        // Unity에 메모리 정리 요청
        const unityInstance = (window as any).unityInstance;
        if (unityInstance) {
            unityInstance.SendMessage('MemoryManager', 'ForceCleanup', '');
        }
    }
}
```

### 2. Unity와 JavaScript 간 메모리 공유 최적화

```c#
using UnityEngine;
using System.Runtime.InteropServices;
using System.Text;

public class MemoryBridge : MonoBehaviour
{
    [DllImport("__Internal")]
    private static extern void SendMemoryData(string data);
    
    [DllImport("__Internal")]
    private static extern string GetMemoryInfo();
    
    private StringBuilder stringBuilder = new StringBuilder(1024);
    
    public void SendLargeData(byte[] data)
    {
        // 큰 데이터를 청크로 분할하여 전송
        int chunkSize = 1024;
        for (int i = 0; i < data.Length; i += chunkSize)
        {
            int currentChunkSize = Mathf.Min(chunkSize, data.Length - i);
            byte[] chunk = new byte[currentChunkSize];
            System.Array.Copy(data, i, chunk, 0, currentChunkSize);
            
            string base64Chunk = System.Convert.ToBase64String(chunk);
            SendMemoryData($"{{\"chunk\": \"{base64Chunk}\", \"index\": {i / chunkSize}}}");
        }
    }
    
    public void OptimizeStringOperations(string[] strings)
    {
        stringBuilder.Clear();
        
        foreach (string str in strings)
        {
            stringBuilder.Append(str);
            stringBuilder.Append(",");
        }
        
        if (stringBuilder.Length > 0)
        {
            stringBuilder.Length--; // 마지막 콤마 제거
        }
        
        SendMemoryData(stringBuilder.ToString());
    }
}
```

***

## 오브젝트 풀링

### 1. 범용 오브젝트 풀

```c#
using UnityEngine;
using System.Collections.Generic;

public class ObjectPool<T> : MonoBehaviour where T : MonoBehaviour
{
    [Header("풀 설정")]
    public T prefab;
    public int initialSize = 10;
    public int maxSize = 50;
    public bool allowGrowth = true;
    
    private Queue<T> pool = new Queue<T>();
    private HashSet<T> activeObjects = new HashSet<T>();
    
    private void Start()
    {
        InitializePool();
    }
    
    private void InitializePool()
    {
        for (int i = 0; i < initialSize; i++)
        {
            T obj = CreateNewObject();
            obj.gameObject.SetActive(false);
            pool.Enqueue(obj);
        }
    }
    
    private T CreateNewObject()
    {
        T obj = Instantiate(prefab, transform);
        return obj;
    }
    
    public T GetObject()
    {
        T obj;
        
        if (pool.Count > 0)
        {
            obj = pool.Dequeue();
        }
        else if (allowGrowth && activeObjects.Count < maxSize)
        {
            obj = CreateNewObject();
        }
        else
        {
            return null; // 풀이 가득 참
        }
        
        obj.gameObject.SetActive(true);
        activeObjects.Add(obj);
        return obj;
    }
    
    public void ReturnObject(T obj)
    {
        if (activeObjects.Contains(obj))
        {
            obj.gameObject.SetActive(false);
            activeObjects.Remove(obj);
            pool.Enqueue(obj);
        }
    }
    
    public void ClearPool()
    {
        while (pool.Count > 0)
        {
            T obj = pool.Dequeue();
            if (obj != null)
            {
                DestroyImmediate(obj.gameObject);
            }
        }
        
        foreach (T obj in activeObjects)
        {
            if (obj != null)
            {
                DestroyImmediate(obj.gameObject);
            }
        }
        
        activeObjects.Clear();
    }
}

// 사용 예제
public class BulletPoolManager : MonoBehaviour
{
    public ObjectPool<Bullet> bulletPool;
    
    public void FireBullet(Vector3 position, Vector3 direction)
    {
        Bullet bullet = bulletPool.GetObject();
        if (bullet != null)
        {
            bullet.Initialize(position, direction, () => {
                bulletPool.ReturnObject(bullet);
            });
        }
    }
}
```

### 2. 파티클 시스템 풀링

```c#
using UnityEngine;
using System.Collections;

public class ParticlePool : MonoBehaviour
{
    [Header("파티클 설정")]
    public ParticleSystem particlePrefab;
    public int poolSize = 20;
    
    private ParticleSystem[] particles;
    private int currentIndex = 0;
    
    private void Start()
    {
        InitializeParticlePool();
    }
    
    private void InitializeParticlePool()
    {
        particles = new ParticleSystem[poolSize];
        
        for (int i = 0; i < poolSize; i++)
        {
            particles[i] = Instantiate(particlePrefab, transform);
            particles[i].gameObject.SetActive(false);
        }
    }
    
    public ParticleSystem GetParticle()
    {
        ParticleSystem particle = particles[currentIndex];
        currentIndex = (currentIndex + 1) % poolSize;
        
        if (particle.isPlaying)
        {
            particle.Stop();
            particle.Clear();
        }
        
        particle.gameObject.SetActive(true);
        return particle;
    }
    
    public void PlayEffect(Vector3 position, ParticleSystem.MainModule mainSettings = default)
    {
        ParticleSystem particle = GetParticle();
        particle.transform.position = position;
        
        if (mainSettings.startColor.color != Color.clear)
        {
            var main = particle.main;
            main.startColor = mainSettings.startColor;
        }
        
        particle.Play();
        StartCoroutine(ReturnToPool(particle));
    }
    
    private IEnumerator ReturnToPool(ParticleSystem particle)
    {
        yield return new WaitUntil(() => !particle.isPlaying);
        particle.gameObject.SetActive(false);
    }
}
```

***

## 스마트 가비지 컬렉션

### 1. 적응형 GC 관리

```c#
using UnityEngine;
using System.Collections;

public class SmartGarbageCollector : MonoBehaviour
{
    [Header("GC 설정")]
    public float gcInterval = 10f;
    public float memoryThreshold = 0.75f;
    public bool adaptiveGC = true;
    
    private float lastGCTime;
    private long baselineMemory;
    private int framesSinceLastGC;
    
    private void Start()
    {
        baselineMemory = System.GC.GetTotalMemory(true);
        lastGCTime = Time.time;
        
        if (adaptiveGC)
        {
            StartCoroutine(AdaptiveGCRoutine());
        }
        else
        {
            StartCoroutine(RegularGCRoutine());
        }
    }
    
    private IEnumerator AdaptiveGCRoutine()
    {
        while (true)
        {
            framesSinceLastGC++;
            
            if (ShouldRunGC())
            {
                RunGarbageCollection();
            }
            
            yield return new WaitForEndOfFrame();
        }
    }
    
    private IEnumerator RegularGCRoutine()
    {
        while (true)
        {
            yield return new WaitForSeconds(gcInterval);
            RunGarbageCollection();
        }
    }
    
    private bool ShouldRunGC()
    {
        // 시간 기반 조건
        if (Time.time - lastGCTime > gcInterval)
            return true;
            
        // 메모리 사용량 기반 조건
        long currentMemory = System.GC.GetTotalMemory(false);
        float memoryGrowth = (float)currentMemory / baselineMemory;
        
        if (memoryGrowth > 1f + memoryThreshold)
            return true;
            
        // 프레임 드롭 기반 조건
        if (Time.deltaTime > 1f / 30f && framesSinceLastGC > 300)
            return true;
            
        return false;
    }
    
    private void RunGarbageCollection()
    {
        long memoryBefore = System.GC.GetTotalMemory(false);
        
        Resources.UnloadUnusedAssets();
        System.GC.Collect();
        System.GC.WaitForPendingFinalizers();
        System.GC.Collect();
        
        long memoryAfter = System.GC.GetTotalMemory(true);
        
        Debug.Log($"GC 실행: {(memoryBefore - memoryAfter) / 1024 / 1024}MB 해제됨");
        
        lastGCTime = Time.time;
        framesSinceLastGC = 0;
        
        if (baselineMemory == 0 || memoryAfter < baselineMemory)
        {
            baselineMemory = memoryAfter;
        }
    }
}
```

***

## 메모리 프로파일링 도구

### 1. 실시간 메모리 분석기

```c#
using UnityEngine;
using System.Collections.Generic;
using System.Text;

public class MemoryProfiler : MonoBehaviour
{
    [Header("프로파일링 설정")]
    public bool enableProfiling = true;
    public float updateInterval = 1f;
    public int maxSamples = 60;
    
    private Queue<MemorySample> samples = new Queue<MemorySample>();
    private StringBuilder logBuilder = new StringBuilder();
    
    [System.Serializable]
    public struct MemorySample
    {
        public float timestamp;
        public long totalMemory;
        public long textureMemory;
        public long meshMemory;
        public long audioMemory;
    }
    
    private void Start()
    {
        if (enableProfiling)
        {
            InvokeRepeating(nameof(TakeSample), 0f, updateInterval);
        }
    }
    
    private void TakeSample()
    {
        MemorySample sample = new MemorySample
        {
            timestamp = Time.time,
            totalMemory = System.GC.GetTotalMemory(false),
            textureMemory = GetTextureMemoryUsage(),
            meshMemory = GetMeshMemoryUsage(),
            audioMemory = GetAudioMemoryUsage()
        };
        
        samples.Enqueue(sample);
        
        if (samples.Count > maxSamples)
        {
            samples.Dequeue();
        }
        
        // AppsInToss 플랫폼에 메모리 정보 전송
        SendMemoryDataToAppsInToss(sample);
    }
    
    private long GetTextureMemoryUsage()
    {
        long totalMemory = 0;
        Texture[] textures = Resources.FindObjectsOfTypeAll<Texture>();
        
        foreach (Texture texture in textures)
        {
            if (texture is Texture2D tex2D)
            {
                totalMemory += UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(tex2D);
            }
        }
        
        return totalMemory;
    }
    
    private long GetMeshMemoryUsage()
    {
        long totalMemory = 0;
        Mesh[] meshes = Resources.FindObjectsOfTypeAll<Mesh>();
        
        foreach (Mesh mesh in meshes)
        {
            totalMemory += UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(mesh);
        }
        
        return totalMemory;
    }
    
    private long GetAudioMemoryUsage()
    {
        long totalMemory = 0;
        AudioClip[] clips = Resources.FindObjectsOfTypeAll<AudioClip>();
        
        foreach (AudioClip clip in clips)
        {
            totalMemory += UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(clip);
        }
        
        return totalMemory;
    }
    
    private void SendMemoryDataToAppsInToss(MemorySample sample)
    {
        logBuilder.Clear();
        logBuilder.Append("{");
        logBuilder.AppendFormat("\"timestamp\":{0},", sample.timestamp);
        logBuilder.AppendFormat("\"totalMemory\":{0},", sample.totalMemory);
        logBuilder.AppendFormat("\"textureMemory\":{0},", sample.textureMemory);
        logBuilder.AppendFormat("\"meshMemory\":{0},", sample.meshMemory);
        logBuilder.AppendFormat("\"audioMemory\":{0}", sample.audioMemory);
        logBuilder.Append("}");
        
        Application.ExternalCall("SendMemoryDataToAppsInToss", logBuilder.ToString());
    }
    
    public string GetMemoryReport()
    {
        if (samples.Count == 0) return "메모리 샘플이 없습니다.";
        
        logBuilder.Clear();
        logBuilder.AppendLine("=== 메모리 사용량 보고서 ===");
        
        MemorySample latest = samples.ToArray()[samples.Count - 1];
        logBuilder.AppendFormat("총 메모리: {0:F2} MB\n", latest.totalMemory / 1024f / 1024f);
        logBuilder.AppendFormat("텍스처 메모리: {0:F2} MB\n", latest.textureMemory / 1024f / 1024f);
        logBuilder.AppendFormat("메시 메모리: {0:F2} MB\n", latest.meshMemory / 1024f / 1024f);
        logBuilder.AppendFormat("오디오 메모리: {0:F2} MB\n", latest.audioMemory / 1024f / 1024f);
        
        return logBuilder.ToString();
    }
}
```

***

## 트러블 슈팅

### 일반적인 메모리 문제들

1. 메모리 누수

* 이벤트 핸들러 해제 누락
* 코루틴 정리 누락
* 순환 참조

2. 과도한 메모리 할당

* string concatenation
* 불필요한 new 연산
* 큰 배열 생성

3. 텍스처 메모리 문제

* 압축되지 않은 텍스처
* 불필요한 밉맵
* 잘못된 텍스처 포맷

### 해결 방법

```c#
// 메모리 누수 방지
public class ProperCleanup : MonoBehaviour
{
    private System.Action<int> scoreChanged;
    
    private void OnEnable()
    {
        GameManager.OnScoreChanged += HandleScoreChanged;
    }
    
    private void OnDisable()
    {
        GameManager.OnScoreChanged -= HandleScoreChanged; // 중요!
    }
    
    private void HandleScoreChanged(int newScore)
    {
        // 처리 로직
    }
}

// 효율적인 문자열 처리
public class StringOptimization : MonoBehaviour
{
    private StringBuilder stringBuilder = new StringBuilder(256);
    
    public string CreateFormattedString(int value1, float value2)
    {
        stringBuilder.Clear();
        stringBuilder.AppendFormat("값1: {0}, 값2: {1:F2}", value1, value2);
        return stringBuilder.ToString();
    }
}
```

***

## 베스트 프랙티스

1. 정기적인 메모리 모니터링
2. 적절한 오브젝트 풀링 사용
3. 불필요한 할당 최소화
4. 리소스 해제 자동화
5. AppsInToss 플랫폼 특성 고려

이 가이드를 통해 Unity WebGL 게임의 메모리 효율성을 크게 향상시킬 수 있어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/api/refreshOauth2Token.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/generateOauth2Token.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/removeByUserKey.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/removeByAccessToken.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/getExecutionResult.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/executePromotion.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/getKey.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/refundPayment.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/makePayment.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/getPaymentStatus.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/executePayment.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/getIapOrderStatus.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/sendTestMessage.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/sendMessage.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/api/loginMe.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/bedrock/overview.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/design/overview.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/development/overview.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/intro/_caution-sensitive.md'
description: >-
  앱인토스의 민감 콘텐츠 주의사항입니다. 앱인토스는 성인 사용자의 다양한 콘텐츠 이용을 지원해요. 불법·유해 콘텐츠를 예방하고 토스의 신뢰성과
  브랜드 가치를 지키기 위해 민감 콘텐츠 주의사항을 확인하세요.
---

## 민감 콘텐츠 주의사항 {#sensitive}

앱인토스는 성인 사용자의 다양한 콘텐츠 이용을 지원하면서도, 불법·유해 콘텐츠를 예방하고 토스의 신뢰성과 브랜드 가치를 지키기 위해 민감 콘텐츠 주의사항을 안내드려요.

### 민감 콘텐츠가 무엇인가요?

민감 콘텐츠는 사용자에게 불쾌감·불안감·불편함을 줄 수 있는 표현이나 장면이 포함된 콘텐츠를 말해요.\
법적으로 불법은 아니더라도, 사회적 통념상 논란이 될 수 있는 소재나 연출이 들어간 경우를 포함해요.


민감 콘텐츠의 카테고리는 크게 선정성, 폭력성, 불법·범죄 조장으로 나뉘어요.

**(1) 선정성**

* 신체 특정 부위 노출, 성행위 묘사, 자극적 카메라 워킹, 음란 행위 암시 등은 제한돼요.
* 성행위를 직접적으로 연출하거나, 성적 대상화를 주요 포인트로 하는 콘텐츠는 등록할 수 없어요.
* 음란 유행어나, 불쾌한 성적 표현도 사용하지 말아주세요.

**(2) 폭력성**

* 단순 액션이나 코믹한 격투 장면은 괜찮지만, 잔혹한 유혈·학대·고문 장면은 제한돼요.
* 폭력을 미화하거나 성적 ·혐오 맥락과 결합된 경우는 즉시 삭제돼요.

**(3) 불법·범죄 조장**

* 마약, 불법 도박, 불법 촬영, 성매매, 미성년자 등장 등은 즉시 삭제 및 신고돼요.
* 불법 행위를 미화하거나 조장하는 콘텐츠는 경고 없이 제한될 수 있어요.

::: tip 확인해 주세요
[민감 콘텐츠 등급](/intro/caution.md#민감-콘텐츠-등급-기준표)에서 경미 또는 주의 단계에 해당하더라도, 내부 심의 결과 수위가 높다고 판단되면 앱 출시가 제한될 수 있어요.

민감 콘텐츠로 분류되어도, 아래와 같은 내용은 포함할 수 없어요.

* 과한 신체 노출, 성행위 묘사, 성적 대상화, 성상품화
* 폭력·학대·혐오·차별·불법 조장 장면 포함
* 허위 정보, 극단적 발언, 사회적 논란을 유발할 수 있는 장면
  :::

### 민감 콘텐츠에 해당하는지 어떻게 알 수 있나요?

앱 출시 검토 요청과 함께, 검수가 진행되면서 민감 콘텐츠 여부가 결정돼요.\
민감 콘텐츠로 분류되면 워크스페이스의 멤버에게 메일로 안내드려요.

### 민감 콘텐츠로 분류되면 어떻게 되나요?

미니앱 서비스가 민감 콘텐츠로 분류되면, 미니앱에 진입하기 직전에 안내해요.\
동의한 사용자는 민감 콘텐츠로 분류된 모든 미니앱을 안내 UI 없이 접속할 수 있어요.

![](/assets/caution_sensitive_alert.BJymrOGy.png)

### 민감 콘텐츠 등급 기준표

---

---
url: 'https://developers-apps-in-toss.toss.im/intro/_caution-social.md'
description: >-
  앱인토스의 데이팅, 만남, 소셜 서비스 운영 주의사항입니다. 법적 규제 준수, 청소년 보호, 개인정보 보호, 안전 관리 및 모니터링
  요구사항을 확인하세요.
---

## 데이팅, 만남 서비스 등 주의사항 {#social}

앱인토스 미니앱에서 데이팅, 만남, 소셜 등의 서비스를 제공하기 위해서는 사용자에게 **안전하고 건전한 만남 경험**을 제공해야 해요.

데이팅, 소개팅, 만남 서비스는 **이용자 간의 교류나 인연 형성을 목적으로 연결해주는 서비스이며,** 프로필 기반 매칭, 채팅, 추천 알고리즘 등을 통해 이용자들이 서로를 알아갈 수 있게 **온라인 상에서 사람과 사람을 연결해 새로운 관계를 만드는 소셜 매칭 플랫폼**이에요.

데이팅·소개팅·만남을 목적으로 하는 서비스를 운영하는 파트너사는 아래 사항을 반드시 준수해 주세요.

::: tip  확인해 주세요.
데이팅, 만남, 소개팅 등의 서비스는 앱인토스 콘솔에서 앱 정보 등록 시, ‘소셜’ 카테고리로 등록이 필요해요.

* 소셜 카테고리 선택 시 안내 되는 체크리스트를 꼼꼼히 확인해 주세요.
  :::

### 1. 법적·규제 준수

#### 1) 청소년 보호

* 만 19세 미만 이용자는 가입 및 이용할 수 없어요.
* 서비스 진입 전에 **본인인증(성인 인증) 절차**를 반드시 거쳐야 해요.
* 청소년 접근이 확인되면 서비스는 즉시 퇴출될 수 있어요.

#### 2) 개인정보 및 위치정보 보호

* 서비스 목적과 직접 관련된 **최소한의 정보만 수집**해야 해요.
* **성적 지향, 위치 등 민감정보**는 이용자 **명시적 동의** 후에만 수집할 수 있어요.
* 수집한 정보는 **암호화해서 안전하게 저장**하고, **탈퇴 시 즉시 삭제**해야 해요.

#### 3) 불법 행위 방지

* 조건만남, 성매매, 보이스피싱, 사기, 스토킹 등 **불법 행위와 연루되지 않도록 관리**해야 해요.
* 신고나 모니터링 체계를 갖추고, 불법 행위가 발생하면 즉시 신고하고 차단할 수 있어야 해요.
* 이용약관에는 **‘불법 행위 방조 금지 및 사용자 책임’ 조항**을 포함해야 해요.

#### 4) 결제 및 소비자 보호

* 유료 결제 서비스는 **환불 및 자동결제 해지 정책**을 명확히 안내해야 해요.
* **전자상거래법 등 관련 법률을 준수**하고, 이용자 민원이 발생하면 신속히 대응해야 해요.

***

### 2. 서비스 출시 기준

서비스 출시를 할 경우 최소한의 정보를 확인하고 있어요.\
앱인토스 콘솔에서 앱 정보 등록 시, 안내되는 체크리스트를 하나씩 꼭 확인한 후 등록해 주세요.

::: details 체크리스트 보기
□ 법인 등록이 완료됐어요.

□ 허위 프로필·도용 사진을 차단하기 위한 AI·운영·수동 검증 프로세스를 갖추고 있어요.

□ 앱 내 불법 광고(조건 만남, 성매매 등)를 탐지·차단하는 시스템이 있어요.

□ 사용자 신고 기능(원클릭 신고, 차단)을 제공하고 있어요.

□ 신고 접수 후 24시간 이내 대응 프로세스를 운영하고 있어요.

□ 반복 위반자를 영구 차단하는 정책이 있어요.

□ 대화 내용을 저장할 수 있는 시스템이 있어요.

□ 민감정보(성적 지향, 위치 등)는 최소한으로 수집하고 있어요.

□ 청소년 보호법, 개인정보보호법 등 관련 법령을 준수하고 있어요.

□ 불법 행위 발생 시 수사기관에 협조할 수 있는 체계를 갖추고 있어요.

□ 유료 결제 환불 및 분쟁 해결 절차가 있어요.

□ 위반 사항이 발생하면 토스로 신속하게 공유할 수 있어요.
:::

***

### 3. 운영 요구사항

#### 1) 연령 제한

* 서비스는 **만 19세 이상만 이용**할 수 있어요.
* 청소년 접근이 확인되면 즉시 차단되며, 서비스가 퇴출될 수 있어요.

#### 2) 신뢰성 확보

* **실명 기반 본인인증**을 반드시 적용해요.
* 허위·도용 프로필을 막기 위한 검증 절차를 운영해요.
* 검증 절차에는 연령, 직업, 지역 등의 기본 정보는 입력값을 기준으로 수집하고, 직업·소득 등 특정 정보는 증빙 자료로 선택 검증할 수 있어요.

#### 3) 안전 관리 및 모니터링

* **인력 모니터링 및 AI 모니터링 시스템**을 함께 운영해요.
* 조건만남 등 불법 키워드는 자동으로 필터링해요.
* 신고가 접수되면 **24시간 이내에 처리**해요.
* 관련 대화 내용을 저장하고 검증할 수 있는 시스템을 권장해요.

#### 4) 개인정보 보호

* 개인정보는 최소한으로 수집하고, 암호화해서 저장해요.
* 이용자가 탈퇴하면 정보를 즉시 삭제해요.
* 민감정보는 별도 동의 후에만 사용할 수 있어요.

#### 5) 법적 대응 체계

* 불법 행위가 발생하면 **즉시 수사기관에 협조**해요.
* 피해자 보호를 위해 긴급 차단 프로세스를 운영해요.

***

### 4. 계약 및 제재 정책

#### **1) 필수 약관 조항**

* 불법 행위는 전적으로 사용자의 책임이에요.
* 토스는 신고 및 조치 범위 내에서만 책임을 져요.

#### **2) 운영 위반 시 조치**

* 위반이 누적되면 단계별로 제재되며, 아래의 사유의 경우 서비스 운영이 중단될 수 있어요.
  * 청소년 접근 허용
  * 성매매 광고나 불법 행위 방치
  * 대규모 개인정보 유출 등 중대한 위반 발생

---

---
url: 'https://developers-apps-in-toss.toss.im/intro/_caution-web-board.md'
description: >-
  앱인토스의 웹보드 게임 서비스 출시 주의사항입니다. 게임물 등급분류, 사행성 방지, 청소년 보호, 과몰입 방지 등 법적 규제 준수 요건과
  운영 정책을 확인하세요.
---

## 웹보드 게임 주의사항 {#web-board}

앱인토스는 건전하고 공정한 게임 환경 조성을 위해, 웹보드 게임 서비스 출시 유의사항을 안내 드려요.

웹보드 게임은 온라인에서 즐기는 보드·카드·전략형 게임(예: 포커, 고스톱, 맞고, 체스, 장기 등)을 말하며,\
게임머니로 베팅하고 상대와 승패를 겨루는 구조를 가지지만, 실제 현금 거래는 엄격히 금지돼요.

또한, **「게임산업진흥에 관한 법률」에 따라 사행성 방지 규제(베팅 한도·시간·결제 제한 등) 및 아래 주의사항을 반드시 준수**해 주세요.

이를 충족하지 못할 경우 심사 및 모니터링 과정에서 서비스 오픈이 제한되거나 제재를 받을 수 있어요.

::: tip  꼭 확인해 주세요.

* 앱인토스 콘솔에서 앱 정보 등록 시 **‘웹보드’ 여부를 꼭 체크**해 주세요.
* 게임물관리위원회의 등급분류가 반드시 필요해요.
* 성인 인증 기능 연동이 필요해요.
* 미니앱에 등급 표기 시, 청소년 유해 매체물 및 등급분류 시 위원회에서 전달 받은 내용(선정성, 폭력성 등) 도 함께 표기가 되어야 해요.
* 확률형 아이템의 경우 사용자가 확인할 수 있도록 자체적으로 확률 공개가 필요해요.
* 이용 시간 경고, 결제 한도 알림 등 과몰입을 방지하기 위한 기능을 제공해야 해요.
  :::

### 1. 법적 · 규제 준수 요건

웹보드 게임은 **관련 법령에 따른 규제 준수**가 필수이며, 아래 요건을 충족하지 않으면 출시가 제한되거나 서비스가 중단될 수 있어요.

#### 1) 게임물관리위원회 등급분류 필수

모든 게임은 **「게임산업진흥에 관한 법률」 제21조**에 따라 **게임물관리위원회(GRAC)의 등급분류를 반드시 받아야 해요.**

* 앱스토어·구글플레이의 IARC 등급은 국내 효력이 없어요.

#### 2) 사행성 방지 기준 충족

게임 내 베팅, 도박, 재산상 이익을 유도하는 기능은 금지돼요.

* 문화체육관광부 고시 **「게임제공업자의 준수사항」** 과 **「게임산업진흥법」제 32조**를 준수해야 해요.

#### 3) 청소년 보호 의무

청소년 이용불가 게임물은 **청소년유해매체물 표시**를 적용하고, 본인인증·이용 제한 기능을 포함해야 해요.

* 관련 근거 :**「청소년 보호법」제 26조**, **「게임산업진흥법」제 24조**를 준수해야 해요.

#### 4) 개인정보 보호

이용자의 개인정보는 **「개인정보보호법」제 28조** 및 **「정보통신망법」제 28조**에 따른 안전성 확보조치를 이행해야 해요.

***

### 2. 서비스 품질 기준

출시된 미니앱은 안정적으로 운영되어야 하며, 보안·접근성·장애 대응 체계가 확보되어야 해요.

#### 1) 서버 안정성 및 장애 대응

**「정보통신망법」제 45조**에 따라, 서비스 장애 발생 시 신속히 대응하고 장애 이력을 관리해야 해요.

#### 2) 보안성 강화 및 부정행위 방지

봇, 매크로, 계정 공유, 부정 결제 등 비정상 이용 행위를 탐지하고 방지해야 합니다.

* 관련근거 :**「게임산업진흥법」제 32조,「정보통신망법」제 28조**를 준수해 주세요.

#### 3) 접근성 및 최적화

모든 이용자가 접근 가능한 UI/UX를 제공해야 하며, 필요 시 **「장애인차별금지법」제 21조**에 따른 접근성 기준을 준용할 수 있어요.

***

### 3. 운영 및 정책

#### 1) 과몰입 방지 기능

게임 내 **이용시간 경고, 결제 한도 알림**을 제공해야 해요.

* 관련근거 :**「게임산업진흥법」제 24조의 2항**을 준수해 주세요.

#### 2) 고객센터 운영 및 분쟁 해결

이용자 불만 및 분쟁 발생 시, 고객센터를 통해 처리 절차를 제공해야 해요.

* 관련근거 :**「전자상거래 등에서의 소비자보호법」 제 20조**를 준수해 주세요.

#### 3) 확률형 아이템 정보 공개

확률형 아이템은 구성 및 확률 정보를 명확히 공개해야 해요.

* 관련근거 :**「게임산업진흥법」 제32조의 3항**을 준수해 주세요.

#### 4) 성인 인증 기능 연동 (본인 확인 연동)

웹보드 게임은 만 19세 이상부터 이용이 가능하므로, 본인 인증 기능 연동을 해주세요.

* [본인 인증 연동 방법 보러가기](/tossauth/contract.md)

***

### 4. 결제·정산 관련

결제 과정은 안전해야 하며, 이용자에게 명확히 고지되어야 해요.

#### 1) 결제 안전성

**「전자금융거래법」제 6조**에 따라, 결제 서비스 제공 시 보안성 및 이용자 보호조치를 이행해야 해요

#### 2) 환불 및 취소 정책

청약철회, 취소, 환불 절차를 명시하고 이용자가 쉽게 확인할 수 있어야 해요.

* 관련 근거 :**「전자상거래법」 제 17조 및 제 18조**를 준수해 주세요.

#### 3) 매출 보고 및 정산 투명성

매출 내역, 세금계산서 발급 등 거래 내역을 투명하게 관리해야 해요.

* **「부가가치세법」제 32조**를 준수해 주세요.

#### 4) 결제 한도 관리 시스템

이용자별 결제 한도(일/월 기준)를 설정하고 관리 기능을 갖춰야 해요.

* **「게임산업진흥법」 제 24조의 2항**을 준수해 주세요.

***

### 5. UX/UI 및 브랜드 적합성

앱인토스 미니앱으로 출시되는 웹보드 게임은 일관된 사용자 경험을 유지하고, 광고·홍보 콘텐츠는 공정하게 운영되어야 해요.

#### 1) 건전성 확보

게임 내 표현과 구성은 **청소년 보호법, 게임산업진흥법**에 따라 사회적 통념을 해치지 않도록 구성해야 해요.

#### 2) UI/UX 일관성

앱인토스 미니앱의 디자인 가이드 및 인터랙션 규칙을 따라야 해요.

* [**UI/UX 가이드라인 보러가기**](/design/miniapp-branding-guide.html#frontmatter-title)

#### 3) 광고 및 홍보 제한

서비스 본질과 무관한 과도한 광고, 외부 유도형 홍보, 오해를 불러일으킬 수 있는 문구는 금지돼요.

* 관련 근거 :**「표시·광고의 공정화에 관한 법률」제 3조**를 준수해 주세요.

***

### 6. 심사·사후 모니터링

앱인토스는 웹보드 게임에 대해 **출시 검토 → 서비스 운영 → 사후 점검**의 3단계 관리 프로세스로 운영해요.

#### 1) 출시 검토

게임물 등급, 서비스 품질, 과몰입 방지, 보안성 등을 검토해요.

* [**게임 출시 가이드 보러가기**](/checklist/app-game.html)

#### 2) 사후 모니터링

출시 이후에도 주기적으로 다음 항목을 점검해요.

* 법령 위반 여부
* 과몰입 방지 시스템 작동 여부
* 결제 한도 및 확률 공개 준수 여부

위반 사항이 확인되면 **콘텐츠 수정 요청, 비노출 등의 조치**가 이뤄질 수 있어요.

* 관련 근거:**「게임산업진흥법」제 24조의 2항, 제 32조 /「전자상거래법」제 20조**

---

---
url: 'https://developers-apps-in-toss.toss.im/markdown-examples.md'
---
hello

---

---
url: 'https://developers-apps-in-toss.toss.im/marketing/overview.md'
---


---

---
url: 'https://developers-apps-in-toss.toss.im/overview-card.md'
description: >-
  앱인토스 개발자센터 오버뷰 페이지. 게임 또는 비게임 서비스를 선택하고, React Native 또는 WebView 기반 개발 방식을
  선택하여 시작할 수 있습니다.
---


---

---
url: 'https://developers-apps-in-toss.toss.im/revenue/overview.md'
---


---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/memory-profiling.md
---


---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/custom-urp.md
---
# URP 파이프라인 커스터마이징

앱인토스 Unity 게임에서 Universal Render Pipeline(URP)을 활용하여 최적화된 렌더링 파이프라인을 구축하는 방법을 다뤄요.

***

## 1. AppsInToss URP 설정

### 커스텀 URP 에셋 설정

```c#
using UnityEngine;
using UnityEngine.Rendering.Universal;

[CreateAssetMenu(fileName = "AppsInTossURPAsset", menuName = "Rendering/AppsInToss URP Asset")]
public class AppsInTossURPAsset : UniversalRenderPipelineAsset
{
    [Header("AppsInToss 최적화")]
    public bool enableMobileOptimizations = true;
    public bool enableBatteryOptimizations = true;
    public RenderScale renderScale = RenderScale.Half;
    
    public enum RenderScale
    {
        Quarter = 4,
        Half = 2,
        Full = 1
    }
    
    protected override ScriptableRenderer Create()
    {
        return new AppsInTossURPRenderer(this);
    }
}
```

### 커스텀 렌더러

```c#
using UnityEngine;
using UnityEngine.Rendering.Universal;

public class AppsInTossURPRenderer : UniversalRenderer
{
    private AppsInTossRenderFeature tossBrandingFeature;
    private PerformanceOptimizerFeature performanceFeature;
    
    public AppsInTossURPRenderer(AppsInTossURPAsset data) : base(data)
    {
        // AppsInToss 특화 렌더링 기능 추가
        tossBrandingFeature = new AppsInTossRenderFeature();
        performanceFeature = new PerformanceOptimizerFeature();
        
        // 렌더링 기능 등록
        rendererFeatures.Add(tossBrandingFeature);
        rendererFeatures.Add(performanceFeature);
    }
}
```

### 앱인토스 브랜딩 렌더 기능

```c#
using UnityEngine;
using UnityEngine.Rendering;
using UnityEngine.Rendering.Universal;

public class AppsInTossRenderFeature : ScriptableRendererFeature
{
    [System.Serializable]
    public class Settings
    {
        public bool enableTossWatermark = true;
        public Texture2D tossLogo;
        public Vector2 logoPosition = new Vector2(0.9f, 0.1f);
        public float logoScale = 0.1f;
    }
    
    public Settings settings = new Settings();
    private AppsInTossRenderPass renderPass;
    
    public override void Create()
    {
        renderPass = new AppsInTossRenderPass(settings);
        renderPass.renderPassEvent = RenderPassEvent.AfterRenderingPostProcessing;
    }
    
    public override void AddRenderPasses(ScriptableRenderer renderer, ref RenderingData renderingData)
    {
        if (settings.enableTossWatermark && settings.tossLogo != null)
        {
            renderer.EnqueuePass(renderPass);
        }
    }
    
    private class AppsInTossRenderPass : ScriptableRenderPass
    {
        private Settings settings;
        private Material blitMaterial;
        
        public AppsInTossRenderPass(Settings settings)
        {
            this.settings = settings;
            
            // 워터마크 셰이더 머티리얼 생성
            blitMaterial = new Material(Shader.Find("AppsInToss/TossWatermark"));
        }
        
        public override void Execute(ScriptableRenderContext context, ref RenderingData renderingData)
        {
            if (blitMaterial == null) return;
            
            CommandBuffer cmd = CommandBufferPool.Get("AppsInToss Branding");
            
            // 토스 로고 렌더링
            blitMaterial.SetTexture("_TossLogo", settings.tossLogo);
            blitMaterial.SetVector("_LogoPosition", settings.logoPosition);
            blitMaterial.SetFloat("_LogoScale", settings.logoScale);
            
            // 화면에 워터마크 렌더링
            cmd.Blit(null, BuiltinRenderTextureType.CurrentActive, blitMaterial);
            
            context.ExecuteCommandBuffer(cmd);
            CommandBufferPool.Release(cmd);
        }
    }
}
```

URP를 사용하면 모바일에 맞게 최적화하면서도 앱인토스의 브랜딩 스타일을 함께 구현할 수 있어요.\
커스텀 렌더링 기능을 활용해 성능과 시각적 품질의 균형을 맞춰보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/design/ux-writing.md'
description: >-
  토스 보이스톤을 적용한 UX 라이팅 가이드입니다. 해요체, 능동적 말하기, 한 줄로 말하기, 버튼 작성법 등 일관된 사용자 경험을 위한 문구
  작성 원칙을 확인하세요.
---

# {{ $frontmatter.title }}

본 가이드라인은 토스의 보이스톤을 적용한 문구를 쓸 수 있도록 제공된 지침입니다.
아래 가이드라인을 지켜주세요.

## 1. 해요체

제품 안의 모든 문구는 ‘해요체’로 써요.

일관성 있는 사용자 경험을 만들 수 있도록 **상황, 맥락을 불문하고 모든 문구에 해요체를 적용해주세요.**

![합쇼체가 아닌, 해요체를 써주세요.](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fd13c8446-177d-4aef-977a-d6133215a246%2Fhaeyo1.png?table=block\&id=17d714bb-fde7-8082-87bc-d9889336576d\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1420\&userId=\&cache=v2)

## 2. 능동적 말하기

제품 안에서 최대한 **능동형 문장**을 써주세요.

### 됐어요 → 했어요

불필요하게 동사 끝을 ‘됐어요’로 쓰지 않아요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fb972cb10-930d-47d2-ae7c-906ed265bcec%2Fsudong3.png?table=block\&id=17d714bb-fde7-80ca-9387-c7db14b3c36e\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1860\&userId=\&cache=v2)

### ‘~었’ 빼기

동사에 ‘-었’을 빼면 문장을 더 짧게 만들 수 있어요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fc02c38fa-a84d-4547-bc87-c0a46bd4cd19%2Fsudong5.png?table=block\&id=17d714bb-fde7-80c7-a048-fd6ef6a455bd\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 동사 바꿔쓰기

동사를 바꿔서 쓰면 의미를 더 명확하게 쓸 수 있어요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2F8352604b-7c4b-403c-a930-a0ebb22833dc%2Fsudong4.png?table=block\&id=17d714bb-fde7-8009-84ee-c0a428d28ed7\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 수동형 → 능동형, 고쳤을 때 어색한 경우

수동형 문장을 기계적으로 능동형으로 바꿨을 때 문장이 어색해지거나, 전달하는 내용이 더 어려워질 때도 있어요. 그럴 때는 처음부터 문장을 다시 써보면 좋아요.

::: details 밸류 강조하기

* Don't 28개 금융사에서 대출이 승인됐어요.
* Do 28개의 금융사에서 대출받을 수 있어요.
* '대출'을 주어로 써서 사용자가 얻는 가치가 모소하게 느껴져요. 사용자를 주어로 표현하면 사용자가 얻는 가치가 더 뚜렷해져요.
  :::

::: details **행동 강조하기**

* Don't 비밀번호를 바꾸면 토스인증서가 삭제돼요.
* Do 비밀번호를 바꾸면 토스인증서를 다시 받아야 해요.
* 인증서를 삭제했을 때 사용자가 해야 하는 행동을 더 명확하게 설명할 수 있어요.
  :::

### 수동형 문장을 써도 되는 경우

수동형 문장이 더 명확 하고 간결한 커뮤니케이션을 만드는 때도 있어요. 수동형으로 더 좋은 문장을 쓸 수 있는 사례를 알려드릴게요.

::: details **⚠️ 서비스 종료, 기간 만료**

* Do 자산 조회 기간이 곧 만료돼요.
* 주어(종료 서비스, 기간 등)를 강조할 수 있어요.
* ‘종료, 만료’ 를 한국어로 풀어썼을 때 뉘앙스를 정확히 전달하지 못해요. (끝나요 vs. 만료돼요.)
  :::

:::details **⚠️ 사용자에게 미치는 영향을 알려줄 때**

* Do 토스뱅크 대출로 갈아타면 원래 대출이 해지돼요.
* **인과 관계**를 명확하게 설명해요. ‘사용자의 행동에 의해 따라오는 결과’라는 점을 알려줄 수 있어요.
* 주요 동사 : 연체, 해지, 적용 등
  :::

:::details **⚠️ 사용자 안심**

* Do 이제부터 김토스님의 개인정보 이용 내역이 기록돼요.
* '정보 수집 안내’ 등의 민감한 상황에서 사용자를 안심하게 할 수 있어요.
  :::

:::details **⚠️ 되어요 (X) → 돼요 (O)**

* 모바일 화면의 좁은 공간을 고려, ‘되어요’는 모두 ‘돼요’로 통일해서 써주세요.
  :::

## 3. 긍정적 말하기

제품 안에서 부정적 커뮤니케이션을 최대한 줄이고 긍정형 문장을 써주세요.

### 없어요 → 있어요

‘할 수 없다’보다는 어떻게 해야 ‘할 수 있는지’ 알려주세요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2F8e18b606-d1c9-4ed7-a265-575d4eef012c%2Fpositive1.png?table=block\&id=17d714bb-fde7-80bd-8c49-c1e26e0e0bcf\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 에러 메시지

사용자가 스스로 해결할 수 있는 에러라면 부정형 문장을 쓰지 않아요. 사용자가 기능을 쓸 수 있는 방법을 안내해주세요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fb873c576-648f-43c3-b6ec-60ce03bfc158%2Fpositive2.png?table=block\&id=17d714bb-fde7-809d-9c41-d230d317ce00\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 혜택을 받을 수 없을 때

혜택을 받을 수 없을 때, 부정형 문장을 쓰면 사용자의 감정을 상하게 할 수 있어요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2F0c9550c0-68b1-4ec1-b97a-76af00275242%2Fpositive3.png?table=block\&id=17d714bb-fde7-80db-ba51-cc88b9667092\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 혜택 대상 안내

비스는 쓸 수 있지만, 특정 혜택은 받을 수 없을 때 → 긍정형 문장. 사용자는 스킴하기 때문에 제품 전체를 쓸 수 없다고 이해하기 쉬워요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fd9280050-9714-4721-8fa2-2098c7c33a16%2Fpositive1.png?table=block\&id=17d714bb-fde7-80f6-89b6-dcce6c27a1fa\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 부정형 문장을 써도 되는 경우

사용자에게 명확하게 부정적인 내용을 알려줘야 할 때는 부정형 문장을 써도 좋아요.

:::details **⚠️ 서비스를 정책 상 쓸 수 없을 때**

* Do 지금은 가입할 수 없어요. 청소년을 위한 서비스는 아직 준비 중이에요.
* Do 공무원은 후원금을 보낼 수 없어요. 구각공무원법에 따라, 특정 정당이나 정치인을 후원하는 것은 금지돼요.
* 사용자에게 상황을 명확하게 인지시킬 수 있어요. 쓸 수 없는 이유를 함께 안내해주세요.
  :::

:::details **⚠️ 일부 기능만 쓸 수 없을 때**

* Do 한 번 바꾸면 주식캐시백은 다시 받을 수 없어요.
* 사용자가 어떤 기능을 쓸 수 없는지 명확하게 인지 할 수 있어요.
* 사용자 선택의 결과를 명확하게 안내할 수 있어요.
  :::

:::details **⚠️ 사용자 안심**

* Do 상담이 끝나면 보험 전문가도 김토스님의 정보를 볼 수 없어요.
* ‘정보 수집 안내’ 등의 민감한 상황에서 사용자를 안심하게 할 수 있어요.
  :::

## 4. 캐주얼한 경어

제품 안에서 ‘~시겠어요?’, ‘시나요?’, ‘~께’ 같은 과도한 경어를 쓰지 않아요. 최대한 캐주얼하고 친근한 말투를 쓰는 게 좋아요.

### 동사에서 ‘~시’ 빼기

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fa78e04b4-740a-4640-83d3-99b034c09c1d%2Frespect2.png?table=block\&id=17d714bb-fde7-80f5-bb39-ee7d3c04f0d5\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### ‘계시다' → ‘있다’

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fc2aed8e3-4b15-4533-a7f6-c5c1574d894c%2Frespect4.png?table=block\&id=17d714bb-fde7-80bb-b122-d329866a8190\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### ‘여쭈다’ → ‘확인하다, 묻다’

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fb94583f1-7785-489e-bc71-9fe3b87bfbe3%2Frespect5.png?table=block\&id=17d714bb-fde7-8026-883e-dc7f1b5d4486\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### ‘께’ → ‘에게’

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2F7c6b5d55-3fcd-4ad7-8f5a-815308cba351%2Frespect6.png?table=block\&id=17d714bb-fde7-8079-b550-ff2d7051679d\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 경어를 뺐을 때 어색한 경우

사용자의 정보를 받는 질문에서 기계적으로 ‘~시’를 뺐을 때 문장이 어색할 수 있어요.
파악하고 싶은 정보를 ‘주어’로 써서 문장을 새롭게 써보세요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2F31d31873-f5b0-41e8-957d-6b3a394ea3ed%2Frespect4.png?table=block\&id=17d714bb-fde7-80b2-887b-e367a2c6d6f4\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 경어를 써도 되는 경우

:::details ⚠️ 사용자의 맥락을 활용해서 질문할 때
‘시나요?’, ‘셨나요?’ 형태의 경어를 활용해서 사용자의 당황스러움을 줄일 수 있어요.

:::details ⚠️ 사용자의 상황을 추정할 때
토스에 명확한 정보가 없어서 사용자에게 직접 판단하게 해야 할 때 ‘경어’로 정중하게 질문할 수 있어요.

:::details ⚠️ 사용자의 선의가 필요할 때
설문조사처럼 사용자의 선의를 기대해야 할 때 경어로 정중하게 질문해요.

## 5. ‘{명사} + {명사}’ 쓰지 않기

### 한자어 풀어쓰기

한자어 명사를 풀어서 동사 형태로 쓸 수 있어요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2F0513c260-ad59-4f08-a6b4-26782bbdf63f%2Fnoun2.png?table=block\&id=17d714bb-fde7-8040-a6ab-f6fdf0fd3e34\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### **한자어를 풀어쓰기 어려울 경우**

’{명사}가 {명사}해서’ 형태로만 풀어줘도 더 캐주얼하게 쓸 수 있어요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2F6d89dedb-d287-4657-876d-aff3972dca09%2Fnoun3.png?table=block\&id=17d714bb-fde7-805f-96d2-d464e6b1662a\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

### 기능 이름 + 동명사

토스 제품의 네이밍은 대부분 ‘~하기’ 형태로 끝나요.
’~하기’가 어색하게 반복되지 않게 기능 이름은 빼고 ‘동사’만 쓰거나, 기능 이름을 문장으로 풀어서 쓰면 좋아요.

![](https://tosspublic.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F5ce36d31-78ba-49d0-aeaf-0919cf07d3f4%2Fdb651e92-b2c5-4988-97c8-c389fa52cc87%2Fnoun4.png?table=block\&id=17d714bb-fde7-807f-a5da-f936abe676bc\&spaceId=5ce36d31-78ba-49d0-aeaf-0919cf07d3f4\&width=1040\&userId=\&cache=v2)

## 더 알아보기

* [토스의 8가지 라이팅 원칙들](https://toss.tech/article/8-writing-principles-of-toss)
* [좋은 에러 메시지를 만드는 6가지 원칙](https://toss.tech/article/21021)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/Video.md
---

# Video

`Video` 컴포넌트는 앱 내에서 비디오를 재생할 수 있는 컴포넌트예요.\
앱이 백그라운드로 전환되면 자동으로 일시 정지되고,\
다른 앱에서 음악이 재생 중일 때 오디오 포커스를 적절히 제어해\
토스 앱이 그 음악을 중지시키지 않아요.

::: tip 참고하세요
`Video` 컴포넌트는 [`react-native-video` v6.0.0-alpha.6](https://github.com/TheWidlarzGroup/react-native-video/tree/v6.0.0-alpha.6)을 기반으로 동작해요.\
일부 타입이나 기능은 최신 버전과 호환되지 않을 수 있어요.
:::

## 시그니처

```typescript
Video: import("react").ForwardRefExoticComponent<Props & import("react").RefAttributes<VideoRef>>
```

### 파라미터

### 프로퍼티

### 반환 값

## 예제

### 비디오 자동 재생하기

아래 예시는 비디오를 자동 재생하는 간단한 예시예요.\
`muted`를 `true`로 설정하면 무음 상태에서 재생할 수 있어요.

```tsx
import { useRef } from 'react';
import { View } from 'react-native';
import { Video } from '@granite-js/react-native';

function VideoExample() {
  const videoRef = useRef(null);

  return (
    <View>
      <Video
        ref={videoRef}
        source={{ uri: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4' }}
        muted={true}
        paused={false}
        resizeMode="cover"
        style={{ width: 300, height: 200, borderWidth: 1 }}
      />
    </View>
  );
}
```

## 참고

* [react-native-video](https://github.com/react-native-video/react-native-video)\
  비디오 속성 및 이벤트에 대한 자세한 정보는 공식 문서를 참고해 주세요.
* [react-native-video-6.0.0-alpha.6](https://github.com/TheWidlarzGroup/react-native-video/releases/tag/v6.0.0-alpha.6)\
  현재 토스앱에 설치되어있는 버전의 소스코드에요.

---

---
url: 'https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/View.md'
description: Bedrock 프레임워크 레퍼런스 문서입니다.
---

# View

`View` 컴포넌트를 사용해서 요소를 적절한 위치에 배치할 수 있어요. 예를 들어, 자식 요소들을 가로 방향으로 배치하고 싶은 경우 `flexDirection` 값을 `row`로 설정해야 해요.

아래 코드는 '안녕하세요, Bedrock이에요.' 라는 글자를 화면에 가로로 배치하는 예제에요.\
`flexDirection` 의 기본값은 `column`이기 때문에 가로로 배치하려면 `row`로 설정해야 해요.

```tsx
import { Text, View } from "react-native";

export default function TextPage() {
  return (
    <View style={{ flexDirection: "row" }}>
      <Text>안녕하세요</Text>
      <Text>Bedrock이에요.</Text>
    </View>
  );
}
```

## 요소 꾸미기

`View` 컴포넌트, `Text`의 `style` 속성에 값을 전달해서 요소를 꾸밀 수 있어요.\
예를 들어, 배경색을 지정하거나 글자 크기를 키우거나 테두리를 설정할 수 있어요.

아래 코드는 `Text` 컴포넌트에 배경색(`backgroundColor`)을 지정하고, 글자 크기(`fontSize`)를 30으로 설정해요.\
그리고 두 개의 `Text` 컴포넌트를 자식으로 갖는 `View` 컴포넌트의 테두리(`border`)를 검정색으로 설정하는 예제에요.

```tsx
import { Text, View } from "react-native";

export default function TextPage() {
  return (
    <View
      style={{ flexDirection: "row", borderColor: "black", borderWidth: 1 }}
    >
      <Text
        style={{
          backgroundColor: "red",
          fontSize: 30,
        }}
      >
        안녕하세요
      </Text>
      <Text
        style={{
          backgroundColor: "blue",
          fontSize: 30,
        }}
      >
        Bedrock이에요.
      </Text>
    </View>
  );
}
```

## 같이 보기

* [요소 레이아웃 쉽게 적용하기](/bedrock/reference/framework/UI/Layout.html)

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/porting-tutorials/vite-unity.md'
description: >-
  Vite와 Unity를 활용한 앱인토스 미니앱 개발 가이드입니다. Vite 기반 프로젝트에서 Unity WebGL을 통합하는 방법을
  확인하세요.
---

# Vite로 Unity WebGL 빌드 감싸기

이 가이드는 Unity에서 빌드한 WebGL 파일을 Vite(React 기반) 프로젝트로 감싸는 방법을 안내해요.\
앱인토스에 배포하려면 `@apps-in-toss/web-framework`도 함께 설치해야 해요.

## 1. Vite 프로젝트 생성

아래 명령어 중 사용하는 패키지 매니저에 맞게 선택해 주세요.\
React + TypeScript 템플릿으로 프로젝트가 생성돼요.

::: code-group

```sh [npm]
npm create vite@latest unity-webgl-wrapper -- --template react-ts
cd unity-webgl-wrapper
npm install
```

```sh [pnpm]
pnpm create vite unity-webgl-wrapper --template react-ts
cd unity-webgl-wrapper
pnpm install
```

```sh [yarn]
yarn create vite unity-webgl-wrapper --template react-ts
cd unity-webgl-wrapper
yarn install
```

:::

## 2. 앱인토스 SDK 설치

프로젝트 루트에서 앱인토스 SDK를 설치해 주세요.\
앱인토스 환경에 배포하기 위해서 이 SDK가 꼭 필요해요.

```bash
npm install @apps-in-toss/web-framework
```

## 3. Unity WebGL 빌드 결과물 복사

Unity에서 WebGL 빌드를 완료한 후, 출력 폴더의 구조는 보통 다음과 같아요.

```bash
Build/
├── index.html
├── Build/
└── TemplateData/
```

`Build/` 안의 파일들을 vite 프로젝트의 `public/unity` 폴더로 복사해주세요.

```bash
mkdir -p public/unity
cp -r [UnityBuildPath]/Build/* public/unity/
```

그 다음 `index.html`, `TemplateData` 파일도 `public/unity` 폴더로 복사해주세요.

복사 후 구조 예시는 다음과 같아요.

```bash
public/
└── unity/
    ├── index.html
    ├── {YourProject}.data.br
    ├── {YourProject}.framework.js.br
    ├── {YourProject}.loader.js
    ├── {YourProject}.wasm.br
    └── TemplateData/
```

::: tip
`public` 폴더에 들어 있는 파일들은 Vite dev 서버에서 정적 파일로 서빙돼요.
즉, `/unity/index.html`로 접근할 수 있어요.
:::

## 4. Unity 게임을 보여주는 컴포넌트 만들기

Unity WebGL 빌드 파일을 직접 로드해서 `<canvas>`에 그리는 컴포넌트를 작성해요.\
iframe은 사용할 수 없고, Unity의 `createUnityInstance()`를 통해 DOM에 직접 렌더링해야 해요.

::: tip iframe은 사용할 수 없어요
Unity WebGL을 iframe으로 삽입하면 앱인토스 기능(API, SDK 등)이 정상 동작하지 않아요.\
또한 보안 심사에서도 반려될 수 있기 때문에, **iframe 방식**은 지원하지 않습니다.

React 환경에서 Unity WebGL을 동작시키려면, Unity에서 빌드된 JavaScript 런타임을 직접 불러와서 DOM에 렌더링해 주세요.
:::

```tsx
// src/UnityCanvas.tsx
import React, { useEffect, useRef, useState } from "react";

/**
 * Props
 * - basePath: public 폴더 내 unity 빌드가 위치한 경로 (ex: /unity)
 * - loaderFile: loader 스크립트 파일명 (ex: "test.loader.js")
 * - fileBasename: Unity 빌드 파일의 기본 이름 (ex: "test" -> test.data.br, test.wasm.br 등)
 */
type Props = {
  basePath?: string;
  loaderFile?: string;
  fileBasename?: string;
  onProgress?: (p: number) => void;
  onLoaded?: () => void;
  onError?: (e: Error) => void;
  style?: React.CSSProperties;
};

export default function UnityCanvas({
  basePath = "/unity",
  loaderFile = "test.loader.js", 
  fileBasename = "test", 
  onProgress,
  onLoaded,
  onError,
  style,
}: Props) {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const canvasRef = useRef<HTMLCanvasElement | null>(null);
  const unityInstanceRef = useRef<any | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    let mounted = true;
    const scriptUrl = `${basePath}/${loaderFile}`;

    // 동적 스크립트 추가
    const script = document.createElement("script");
    script.src = scriptUrl;
    script.async = true;
    script.onload = () => {
      if (!mounted) return;
      // 캔버스 준비
      const container = containerRef.current!;
      const canvas = document.createElement("canvas");
      canvasRef.current = canvas;
      canvas.id = "unity-canvas";
      canvas.style.width = "100%";
      canvas.style.height = "100%";
      canvas.style.display = "block";
      container.appendChild(canvas);

      const createOpts = {
        dataUrl: `${basePath}/${fileBasename}.data.br`,
        frameworkUrl: `${basePath}/${fileBasename}.framework.js.br`,
        codeUrl: `${basePath}/${fileBasename}.wasm.br`,
        streamingAssetsUrl: "",
        companyName: "YourCompany",
        productName: fileBasename,
        productVersion: "1.0",
      };

      if (typeof (window as any).createUnityInstance !== "function") {
        const err = new Error("createUnityInstance is not available on window. Loader script may have failed to load.");
        console.error(err);
        onError?.(err);
        setLoading(false);
        return;
      }

      (window as any).createUnityInstance(canvas, createOpts, (progress: number) => {
        if (!mounted) return;
        onProgress?.(progress);
        // optional internal state
      }).then((inst: any) => {
        if (!mounted) {
          // 컴포넌트가 언마운트 되었으면 즉시 종료
          if (inst && inst.Quit) inst.Quit();
          return;
        }
        unityInstanceRef.current = inst;
        setLoading(false);
        onLoaded?.();
      }).catch((e: any) => {
        console.error("createUnityInstance error:", e);
        onError?.(e instanceof Error ? e : new Error(String(e)));
        setLoading(false);
      });
    };

    script.onerror = (e) => {
      const err = new Error("Failed to load Unity loader script: " + scriptUrl);
      console.error(err, e);
      onError?.(err);
      setLoading(false);
    };

    document.body.appendChild(script);

    return () => {
      mounted = false;
      // Unity 인스턴스 종료
      const inst = unityInstanceRef.current;
      if (inst && typeof inst.Quit === "function") {
        inst.Quit().catch((err: any) => {
          // ignore
          console.warn("UnityQuit error", err);
        });
      }
      // 캔버스/스크립트 정리
      if (canvasRef.current && containerRef.current?.contains(canvasRef.current)) {
        containerRef.current.removeChild(canvasRef.current);
      }
      try {
        document.body.removeChild(script);
      } catch {}
    };
  }, [basePath, loaderFile, fileBasename]);

  // SendMessage helper
  const sendMessage = (gameObject: string, method: string, value?: string | number | boolean) => {
    const inst = unityInstanceRef.current;
    if (inst && typeof inst.SendMessage === "function") {
      inst.SendMessage(gameObject, method, value);
    } else {
      console.warn("Unity instance not ready or SendMessage missing");
    }
  };

  return (
    <div style={{ width: "100vw", height: "100vh", position: "relative", ...style }}>
      {loading && (
        <div style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center", pointerEvents: "none" }}>
          <div>Loading Unity...</div>
        </div>
      )}
      <div ref={containerRef} style={{ width: "100%", height: "100%" }} />
      {/* 필요 시 외부에서 sendMessage 사용 가능하게 ref 전달 로직 추가 */}
    </div>
  );
}

```

src/App.tsx에서 해당 컴포넌트를 불러와 사용해요.

```tsx
// src/App.tsx
import UnityCanvas from './UnityCanvas';

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <UnityCanvas />
    </div>
  );
}

export default App;


```

## 5. 개발 서버 실행

아래 명령어로 Vite 개발 서버를 실행해 보세요.

```bash
npm run dev
```

브라우저에서 Vite 개발 서버 주소(`http://localhost:5173` 등)로 접속하면 React 앱 안에서 Unity 게임이 정상적으로 렌더링되는지 확인할 수 있어요.

## 6. 앱인토스 배포환경 구성

개발 서버가 정상적으로 실행되는 것을 확인했다면, 다음 명령어로 프로젝트를 앱인토스 배포환경으로 구성해주세요.

```bash
npx ait init
```

명령어 실행 후, 아래와 같은 질문에 순서대로 응답해 주세요.

1. `web-framework` 를 선택하세요.
2. 앱 이름(`appName`)을 입력하세요.
   * 이 이름은 앱인토스 콘솔에서 앱을 만들 때 사용한 이름과 같아야 해요.
   * 앱 이름은 각 앱을 식별하는 **고유한 키**로 사용돼요.
   * appName은 `intoss://{appName}/path` 형태의 딥링크 경로나 테스트·배포 시 사용하는 앱 전용 주소 등에서도 사용돼요.
   * 샌드박스 앱에서 테스트할 때도 `intoss://{appName}`으로 접근해요.\
     단, 출시하기 메뉴의 QR 코드로 테스트할 때는 `intoss-private://{appName}`이 사용돼요.
3. 웹 번들러의 dev 명령어를 입력해주세요.

```bash
vite
```

4. 웹 번들러의 build 명령어를 입력해주세요.

```bash
tsc -b && vite build
```

5. 사용할 포트 번호를 입력하세요.

```bash
5173
```

초기화가 완료되면 granite.config.ts 파일이 생성돼요. 배포하려는 서비스에 맞게 수정해주세요.

## 7. 정적 사이트 빌드 및 배포

```bash
npm run build
```

빌드가 완료되면 `.ait` 파일이 생성돼요.
이 파일을 콘솔에 업로드하면 미니앱을 배포할 수 있어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/runtime/webgl2.md'
---
# WebGL 2.0 렌더링

앱인토스 Unity 게임에서 WebGL 2.0의 고급 기능을 활용하여 성능과 품질을 크게 향상시키는 방법을 제공해요.

***

## 1. WebGL 2.0 vs WebGL 1.0

### 주요 개선사항

```
🚀 WebGL 2.0 고급 기능
├── 렌더링 향상
│   ├── Multiple Render Targets (MRT)
│   ├── Instanced Rendering
│   ├── Uniform Buffer Objects (UBO)
│   └── Transform Feedback
├── 텍스처 기능
│   ├── 3D Textures
│   ├── Texture Arrays
│   ├── Integer Textures
│   └── Compressed Texture Formats
├── 컴퓨팅 기능
│   ├── Vertex Array Objects (VAO)
│   ├── Sampler Objects
│   ├── Sync Objects
│   └── Query Objects
└── 셰이더 향상
    ├── GLSL ES 3.0
    ├── Fragment Shader 고급 기능
    ├── Vertex Shader 확장
    └── 조건부 렌더링
```

### WebGL 2.0 지원 감지

```c#
public class WebGL2Detector : MonoBehaviour
{
    public static bool IsWebGL2Supported()
    {
        #if UNITY_WEBGL && !UNITY_EDITOR
        return Application.platform == RuntimePlatform.WebGLPlayer && 
               SystemInfo.graphicsDeviceVersion.Contains("WebGL 2.0");
        #else
        return false;
        #endif
    }
    
    public static WebGLCapabilities GetWebGLCapabilities()
    {
        var capabilities = new WebGLCapabilities();
        
        #if UNITY_WEBGL && !UNITY_EDITOR
        // WebGL 버전 확인
        capabilities.isWebGL2 = IsWebGL2Supported();
        
        // 최대 텍스처 크기
        capabilities.maxTextureSize = SystemInfo.maxTextureSize;
        
        // 렌더 타겟 지원
        capabilities.supportsMultipleRenderTargets = SystemInfo.supportedRenderTargetCount > 1;
        
        // 인스턴싱 지원
        capabilities.supportsInstancing = SystemInfo.supportsInstancing;
        
        // 컴퓨트 셰이더 지원 (WebGL 2.0에서는 제한적)
        capabilities.supportsComputeShaders = SystemInfo.supportsComputeShaders;
        
        // 압축 텍스처 포맷
        capabilities.supportsASTC = SystemInfo.SupportsTextureFormat(TextureFormat.ASTC_4x4);
        capabilities.supportsETC2 = SystemInfo.SupportsTextureFormat(TextureFormat.ETC2_RGBA8);
        capabilities.supportsDXT = SystemInfo.SupportsTextureFormat(TextureFormat.DXT5);
        
        Debug.Log($"WebGL 능력: {capabilities}");
        #endif
        
        return capabilities;
    }
}

[System.Serializable]
public class WebGLCapabilities
{
    public bool isWebGL2;
    public int maxTextureSize;
    public bool supportsMultipleRenderTargets;
    public bool supportsInstancing;
    public bool supportsComputeShaders;
    public bool supportsASTC;
    public bool supportsETC2;
    public bool supportsDXT;
    
    public override string ToString()
    {
        return $"WebGL2: {isWebGL2}, MaxTexSize: {maxTextureSize}, MRT: {supportsMultipleRenderTargets}, " +
               $"Instancing: {supportsInstancing}, ASTC: {supportsASTC}, ETC2: {supportsETC2}";
    }
}
```

***

## 2. WebGL 2.0 렌더링 최적화

### Multiple Render Targets (MRT) 활용

```c#
public class WebGL2MRTRenderer : MonoBehaviour
{
    [Header("MRT 설정")]
    public bool enableMRT = true;
    public int renderTargetCount = 4;
    public RenderTextureFormat[] rtFormats = {
        RenderTextureFormat.ARGB32,    // 알베도
        RenderTextureFormat.ARGB32,    // 노멀
        RenderTextureFormat.RG16,      // 깊이/거칠기
        RenderTextureFormat.ARGB32     // 이미시브/AO
    };
    
    [Header("앱인토스 최적화")]
    public bool adaptToDevicePerformance = true;
    public bool enableQualityScaling = true;
    
    private RenderTexture[] renderTargets;
    private Camera targetCamera;
    private Material deferredMaterial;
    
    void Start()
    {
        #if UNITY_WEBGL
        if (WebGL2Detector.IsWebGL2Supported() && enableMRT)
        {
            SetupMultipleRenderTargets();
        }
        else
        {
            SetupFallbackRendering();
        }
        #endif
    }
    
    void SetupMultipleRenderTargets()
    {
        targetCamera = GetComponent<Camera>();
        
        // 기기 성능에 따른 렌더 타겟 수 조정
        if (adaptToDevicePerformance)
        {
            AdjustRenderTargetCount();
        }
        
        // 렌더 타겟 생성
        CreateRenderTargets();
        
        // MRT 셰이더 설정
        SetupMRTShader();
        
        Debug.Log($"WebGL 2.0 MRT 렌더링 설정 완료: {renderTargetCount}개 타겟");
    }
    
    void AdjustRenderTargetCount()
    {
        // 앱인토스 환경에서 성능에 따른 MRT 개수 조정
        int memoryMB = SystemInfo.systemMemorySize / 1024;
        
        if (memoryMB < 2048) // 2GB 미만
        {
            renderTargetCount = 2; // 기본 + 노멀
        }
        else if (memoryMB < 4096) // 4GB 미만  
        {
            renderTargetCount = 3; // + 깊이/거칠기
        }
        // 4GB 이상은 기본값 4개 유지
        
        Debug.Log($"기기 메모리 ({memoryMB}MB)에 따른 MRT 타겟 수 조정: {renderTargetCount}");
    }
    
    void CreateRenderTargets()
    {
        renderTargets = new RenderTexture[renderTargetCount];
        
        int width = Screen.width;
        int height = Screen.height;
        
        // 앱인토스 환경에 따른 해상도 스케일링
        if (enableQualityScaling)
        {
            float qualityScale = GetQualityScale();
            width = Mathf.RoundToInt(width * qualityScale);
            height = Mathf.RoundToInt(height * qualityScale);
        }
        
        for (int i = 0; i < renderTargetCount; i++)
        {
            renderTargets[i] = new RenderTexture(width, height, 0, rtFormats[i])
            {
                name = $"MRT_Target_{i}",
                enableRandomWrite = false,
                useMipMap = false,
                antiAliasing = 1
            };
            renderTargets[i].Create();
        }
        
        // 카메라에 렌더 타겟 설정
        targetCamera.SetTargetBuffers(
            renderTargets.Select(rt => rt.colorBuffer).ToArray(),
            renderTargets[0].depthBuffer
        );
    }
    
    float GetQualityScale()
    {
        // 앱인토스 성능 분석을 통한 품질 스케일 결정
        var perfMonitor = AppsInTossPerformanceMonitor.Instance;
        
        if (perfMonitor != null)
        {
            var currentPerf = perfMonitor.GetCurrentPerformance();
            if (currentPerf != null)
            {
                if (currentPerf.fps < 20) return 0.7f;
                else if (currentPerf.fps < 30) return 0.85f;
                else return 1.0f;
            }
        }
        
        return 1.0f; // 기본값
    }
    
    void SetupMRTShader()
    {
        // MRT용 셰이더 로드 및 설정
        deferredMaterial = Resources.Load<Material>("Shaders/AppsInToss_WebGL2_MRT");
        
        if (deferredMaterial != null)
        {
            // 셰이더 키워드 설정
            deferredMaterial.EnableKeyword("WEBGL2_MRT");
            deferredMaterial.SetInt("_RenderTargetCount", renderTargetCount);
            
            // 앱인토스 특화 설정
            deferredMaterial.EnableKeyword("APPS_IN_TOSS_OPTIMIZED");
        }
    }
    
    void SetupFallbackRendering()
    {
        Debug.Log("WebGL 2.0 미지원 - 전통적 렌더링 사용");
        
        // WebGL 1.0 호환 렌더링 설정
        targetCamera = GetComponent<Camera>();
        targetCamera.renderingPath = RenderingPath.Forward;
    }
    
    // 디퍼드 셰이딩을 위한 G-Buffer 합성
    void OnRenderImage(RenderTexture source, RenderTexture destination)
    {
        if (renderTargets == null || deferredMaterial == null)
        {
            Graphics.Blit(source, destination);
            return;
        }
        
        // G-Buffer를 사용한 디퍼드 셰이딩
        deferredMaterial.SetTexture("_GBuffer0", renderTargets[0]); // 알베도
        deferredMaterial.SetTexture("_GBuffer1", renderTargets[1]); // 노멀
        
        if (renderTargetCount > 2)
        {
            deferredMaterial.SetTexture("_GBuffer2", renderTargets[2]); // 깊이/거칠기
        }
        
        if (renderTargetCount > 3)
        {
            deferredMaterial.SetTexture("_GBuffer3", renderTargets[3]); // 이미시브/AO
        }
        
        // 최종 렌더링
        Graphics.Blit(source, destination, deferredMaterial);
    }
    
    void OnDestroy()
    {
        if (renderTargets != null)
        {
            foreach (var rt in renderTargets)
            {
                if (rt != null)
                {
                    rt.Release();
                }
            }
        }
    }
}
```

***

## 3. 인스턴스드 렌더링

### GPU 인스턴싱으로 드로우콜 최적화

```c#
public class WebGL2InstancedRenderer : MonoBehaviour
{
    [Header("인스턴싱 설정")]
    public Mesh instanceMesh;
    public Material instanceMaterial;
    public int maxInstanceCount = 1000;
    
    [Header("앱인토스 최적화")]
    public bool enableAdaptiveInstancing = true;
    public bool enableFrustumCulling = true;
    public bool enableLODInstancing = true;
    
    // 인스턴스 데이터
    private Matrix4x4[] instanceMatrices;
    private Vector4[] instanceColors;
    private float[] instanceLODs;
    private MaterialPropertyBlock propertyBlock;
    
    // WebGL 2.0 전용 버퍼
    private ComputeBuffer matrixBuffer;
    private ComputeBuffer colorBuffer;
    private ComputeBuffer argsBuffer;
    
    void Start()
    {
        #if UNITY_WEBGL
        if (WebGL2Detector.IsWebGL2Supported())
        {
            SetupInstancedRendering();
        }
        else
        {
            SetupFallbackInstancing();
        }
        #endif
    }
    
    void SetupInstancedRendering()
    {
        // 앱인토스 환경에 맞는 인스턴스 수 조정
        if (enableAdaptiveInstancing)
        {
            AdjustInstanceCountForDevice();
        }
        
        // 데이터 배열 초기화
        InitializeInstanceData();
        
        // WebGL 2.0 버퍼 생성
        CreateInstanceBuffers();
        
        // 머티리얼 설정
        SetupInstanceMaterial();
        
        Debug.Log($"WebGL 2.0 인스턴스드 렌더링 설정: {maxInstanceCount}개 인스턴스");
    }
    
    void AdjustInstanceCountForDevice()
    {
        var capabilities = WebGL2Detector.GetWebGLCapabilities();
        
        // GPU 메모리 기반 인스턴스 수 조정
        int gpuMemoryMB = SystemInfo.graphicsMemorySize;
        
        if (gpuMemoryMB < 512) // 저사양 GPU
        {
            maxInstanceCount = 250;
        }
        else if (gpuMemoryMB < 1024) // 중사양 GPU
        {
            maxInstanceCount = 500;
        }
        // 고사양은 기본값 1000 유지
        
        Debug.Log($"GPU 메모리 ({gpuMemoryMB}MB)에 따른 인스턴스 수 조정: {maxInstanceCount}");
    }
    
    void InitializeInstanceData()
    {
        instanceMatrices = new Matrix4x4[maxInstanceCount];
        instanceColors = new Vector4[maxInstanceCount];
        instanceLODs = new float[maxInstanceCount];
        
        // 초기 인스턴스 위치 및 속성 설정
        for (int i = 0; i < maxInstanceCount; i++)
        {
            // 랜덤 위치 생성
            Vector3 position = new Vector3(
                UnityEngine.Random.Range(-50f, 50f),
                0,
                UnityEngine.Random.Range(-50f, 50f)
            );
            
            instanceMatrices[i] = Matrix4x4.TRS(position, Quaternion.identity, Vector3.one);
            instanceColors[i] = new Vector4(
                UnityEngine.Random.value,
                UnityEngine.Random.value,
                UnityEngine.Random.value,
                1.0f
            );
            instanceLODs[i] = CalculateLODLevel(position);
        }
        
        propertyBlock = new MaterialPropertyBlock();
    }
    
    float CalculateLODLevel(Vector3 position)
    {
        if (!enableLODInstancing) return 1.0f;
        
        Camera cam = Camera.main;
        if (cam == null) return 1.0f;
        
        float distance = Vector3.Distance(cam.transform.position, position);
        
        if (distance < 20f) return 1.0f;      // 고품질
        else if (distance < 50f) return 0.7f; // 중품질
        else return 0.4f;                     // 저품질
    }
    
    void CreateInstanceBuffers()
    {
        // 변환 행렬 버퍼
        matrixBuffer = new ComputeBuffer(maxInstanceCount, 16 * sizeof(float)); // Matrix4x4
        matrixBuffer.SetData(instanceMatrices);
        
        // 색상 버퍼  
        colorBuffer = new ComputeBuffer(maxInstanceCount, 4 * sizeof(float)); // Vector4
        colorBuffer.SetData(instanceColors);
        
        // 간접 렌더링 인수 버퍼
        uint[] args = new uint[5] { 0, 0, 0, 0, 0 };
        args[0] = (uint)instanceMesh.GetIndexCount(0); // 인덱스 수
        args[1] = (uint)maxInstanceCount;              // 인스턴스 수
        args[2] = (uint)instanceMesh.GetIndexStart(0); // 시작 인덱스
        args[3] = (uint)instanceMesh.GetBaseVertex(0); // 기본 버텍스
        
        argsBuffer = new ComputeBuffer(1, args.Length * sizeof(uint), ComputeBufferType.IndirectArguments);
        argsBuffer.SetData(args);
    }
    
    void SetupInstanceMaterial()
    {
        if (instanceMaterial != null)
        {
            // WebGL 2.0 인스턴싱 키워드 활성화
            instanceMaterial.EnableKeyword("WEBGL2_INSTANCING");
            instanceMaterial.EnableKeyword("APPS_IN_TOSS_OPTIMIZED");
            
            // 버퍼를 머티리얼에 바인딩
            instanceMaterial.SetBuffer("_InstanceMatrices", matrixBuffer);
            instanceMaterial.SetBuffer("_InstanceColors", colorBuffer);
            
            // 앱인토스 특화 설정
            instanceMaterial.SetFloat("_AppsInTossQuality", GetCurrentQualityLevel());
        }
    }
    
    float GetCurrentQualityLevel()
    {
        // 현재 앱인토스 성능에 따른 품질 레벨 반환
        var perfMonitor = AppsInTossPerformanceMonitor.Instance;
        
        if (perfMonitor != null)
        {
            var currentPerf = perfMonitor.GetCurrentPerformance();
            if (currentPerf != null)
            {
                if (currentPerf.fps >= 45) return 1.0f;      // 고품질
                else if (currentPerf.fps >= 25) return 0.7f; // 중품질
                else return 0.4f;                            // 저품질
            }
        }
        
        return 0.7f; // 기본값
    }
    
    void Update()
    {
        if (instanceMaterial == null || argsBuffer == null) return;
        
        // 프러스텀 컬링 (옵션)
        if (enableFrustumCulling)
        {
            UpdateVisibleInstances();
        }
        
        // 인스턴스 데이터 업데이트
        UpdateInstanceData();
        
        // GPU 인스턴스드 렌더링 실행
        Graphics.DrawMeshInstancedIndirect(
            instanceMesh,
            0,
            instanceMaterial,
            new Bounds(Vector3.zero, new Vector3(100, 100, 100)),
            argsBuffer,
            0,
            propertyBlock
        );
    }
    
    void UpdateVisibleInstances()
    {
        Camera cam = Camera.main;
        if (cam == null) return;
        
        Plane[] frustumPlanes = GeometryUtility.CalculateFrustumPlanes(cam);
        int visibleCount = 0;
        
        for (int i = 0; i < maxInstanceCount; i++)
        {
            Vector3 position = instanceMatrices[i].GetColumn(3);
            
            if (GeometryUtility.TestPlanesAABB(frustumPlanes, new Bounds(position, Vector3.one)))
            {
                // 보이는 인스턴스만 렌더링 배열 앞쪽으로 이동
                if (visibleCount != i)
                {
                    instanceMatrices[visibleCount] = instanceMatrices[i];
                    instanceColors[visibleCount] = instanceColors[i];
                }
                visibleCount++;
            }
        }
        
        // 렌더링할 인스턴스 수 업데이트
        uint[] args = new uint[5];
        argsBuffer.GetData(args);
        args[1] = (uint)visibleCount;
        argsBuffer.SetData(args);
    }
    
    void UpdateInstanceData()
    {
        // 동적 인스턴스 데이터 업데이트 (필요한 경우)
        bool needsUpdate = false;
        
        // LOD 레벨 업데이트
        if (enableLODInstancing)
        {
            for (int i = 0; i < maxInstanceCount; i++)
            {
                Vector3 position = instanceMatrices[i].GetColumn(3);
                float newLOD = CalculateLODLevel(position);
                
                if (Mathf.Abs(instanceLODs[i] - newLOD) > 0.1f)
                {
                    instanceLODs[i] = newLOD;
                    needsUpdate = true;
                }
            }
        }
        
        // 버퍼 업데이트 (필요한 경우만)
        if (needsUpdate)
        {
            matrixBuffer.SetData(instanceMatrices);
            colorBuffer.SetData(instanceColors);
        }
    }
    
    void SetupFallbackInstancing()
    {
        Debug.Log("WebGL 2.0 미지원 - 기본 인스턴싱 사용");
        
        // WebGL 1.0 호환 인스턴싱 (제한적)
        maxInstanceCount = 100; // 성능상 제한
        InitializeInstanceData();
    }
    
    void OnDestroy()
    {
        // 버퍼 정리
        matrixBuffer?.Release();
        colorBuffer?.Release();
        argsBuffer?.Release();
    }
    
    // 성능 통계
    void OnGUI()
    {
        if (Application.isEditor)
        {
            GUILayout.BeginArea(new Rect(10, 100, 300, 100));
            GUILayout.Label($"WebGL 2.0 인스턴싱 통계:");
            GUILayout.Label($"인스턴스 수: {maxInstanceCount}");
            GUILayout.Label($"메시: {instanceMesh?.name}");
            GUILayout.Label($"GPU 메모리: {SystemInfo.graphicsMemorySize}MB");
            GUILayout.EndArea();
        }
    }
}
```

***

## 4. 고급 셰이더 기능

### GLSL ES 3.0 활용

```hlsl
// AppsInToss_WebGL2_Advanced.shader
Shader "AppsInToss/WebGL2/Advanced"
{
    Properties
    {
        _MainTex ("Texture", 2D) = "white" {}
        _Color ("Color", Color) = (1,1,1,1)
        _Metallic ("Metallic", Range(0,1)) = 0.0
        _Smoothness ("Smoothness", Range(0,1)) = 0.5
        
        [Header(Apps In Toss Optimization)]
        _QualityLevel ("Quality Level", Range(0,1)) = 1.0
        _PerformanceMode ("Performance Mode", Float) = 0
    }
    
    SubShader
    {
        Tags { "RenderType"="Opaque" "Queue"="Geometry" }
        LOD 300
        
        Pass
        {
            Name "FORWARD"
            Tags { "LightMode"="ForwardBase" }
            
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            
            // WebGL 2.0 전용 기능 활성화
            #pragma target 3.0
            #pragma require webgl2
            
            // 앱인토스 최적화 키워드
            #pragma shader_feature APPS_IN_TOSS_OPTIMIZED
            #pragma shader_feature WEBGL2_MRT
            #pragma shader_feature WEBGL2_INSTANCING
            #pragma shader_feature MOBILE_OPTIMIZED
            
            // 인스턴싱 지원
            #pragma multi_compile_instancing
            
            #include "UnityCG.cginc"
            #include "Lighting.cginc"
            #include "AutoLight.cginc"
            
            struct appdata
            {
                float4 vertex : POSITION;
                float3 normal : NORMAL;
                float2 uv : TEXCOORD0;
                UNITY_VERTEX_INPUT_INSTANCE_ID
            };
            
            struct v2f
            {
                float4 pos : SV_POSITION;
                float2 uv : TEXCOORD0;
                float3 worldNormal : TEXCOORD1;
                float3 worldPos : TEXCOORD2;
                SHADOW_COORDS(3)
                UNITY_VERTEX_OUTPUT_STEREO
            };
            
            sampler2D _MainTex;
            float4 _MainTex_ST;
            fixed4 _Color;
            half _Metallic;
            half _Smoothness;
            
            // 앱인토스 최적화 변수
            half _QualityLevel;
            half _PerformanceMode;
            
            // WebGL 2.0 전용 Uniform Buffer Object
            #ifdef WEBGL2_UBO
            layout(std140) uniform AppsInTossSettings
            {
                float4 globalTint;
                float4 lightingSettings;
                float2 screenParams;
                float qualityScale;
                float performanceLevel;
            };
            #endif
            
            v2f vert(appdata v)
            {
                v2f o;
                UNITY_SETUP_INSTANCE_ID(v);
                UNITY_INITIALIZE_VERTEX_OUTPUT_STEREO(o);
                
                o.pos = UnityObjectToClipPos(v.vertex);
                o.uv = TRANSFORM_TEX(v.uv, _MainTex);
                o.worldNormal = UnityObjectToWorldNormal(v.normal);
                o.worldPos = mul(unity_ObjectToWorld, v.vertex).xyz;
                
                TRANSFER_SHADOW(o);
                
                return o;
            }
            
            fixed4 frag(v2f i) : SV_Target
            {
                // 앱인토스 성능 모드에 따른 적응적 품질
                half qualityFactor = lerp(0.5, 1.0, _QualityLevel);
                
                // 기본 텍스처 샘플링
                fixed4 albedo = tex2D(_MainTex, i.uv) * _Color;
                
                #ifdef APPS_IN_TOSS_OPTIMIZED
                // 앱인토스 최적화: 거리 기반 품질 조정
                float3 viewDir = normalize(_WorldSpaceCameraPos - i.worldPos);
                float distance = length(_WorldSpaceCameraPos - i.worldPos);
                
                // 거리에 따른 디테일 감소
                half distanceFactor = saturate(1.0 - distance / 100.0);
                qualityFactor *= distanceFactor;
                
                // 성능 모드가 활성화된 경우 간소화된 라이팅
                if (_PerformanceMode > 0.5)
                {
                    // 간단한 Lambert 라이팅
                    half NdotL = dot(i.worldNormal, _WorldSpaceLightPos0.xyz);
                    half lambert = saturate(NdotL);
                    
                    fixed3 lighting = lambert * _LightColor0.rgb;
                    albedo.rgb *= lighting;
                    
                    return albedo;
                }
                #endif
                
                // 고품질 PBR 라이팅 (품질에 따라 조정)
                half3 worldNormal = normalize(i.worldNormal);
                half3 worldView = normalize(_WorldSpaceCameraPos - i.worldPos);
                half3 worldLight = normalize(_WorldSpaceLightPos0.xyz);
                
                // 정반사
                half3 specular = pow(saturate(dot(reflect(-worldLight, worldNormal), worldView)), 
                                    lerp(8, 32, _Smoothness * qualityFactor)) * _Metallic;
                
                // 그림자
                UNITY_LIGHT_ATTENUATION(atten, i, i.worldPos);
                
                // 최종 색상 계산
                fixed3 lighting = saturate(dot(worldNormal, worldLight)) * _LightColor0.rgb * atten;
                lighting += specular * qualityFactor;
                
                albedo.rgb *= lighting;
                
                #ifdef WEBGL2_MRT
                // Multiple Render Targets 출력 (WebGL 2.0 전용)
                // 이 부분은 MRT 패스에서만 사용됨
                #endif
                
                return albedo;
            }
            ENDCG
        }
        
        // 그림자 패스
        Pass
        {
            Name "ShadowCaster"
            Tags { "LightMode"="ShadowCaster" }
            
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #pragma target 3.0
            #pragma multi_compile_shadowcaster
            #pragma multi_compile_instancing
            
            #include "UnityCG.cginc"
            
            struct appdata
            {
                float4 vertex : POSITION;
                float3 normal : NORMAL;
                UNITY_VERTEX_INPUT_INSTANCE_ID
            };
            
            struct v2f
            {
                V2F_SHADOW_CASTER;
                UNITY_VERTEX_OUTPUT_STEREO
            };
            
            v2f vert(appdata v)
            {
                v2f o;
                UNITY_SETUP_INSTANCE_ID(v);
                UNITY_INITIALIZE_VERTEX_OUTPUT_STEREO(o);
                TRANSFER_SHADOW_CASTER_NORMALOFFSET(o)
                return o;
            }
            
            fixed4 frag(v2f i) : SV_Target
            {
                SHADOW_CASTER_FRAGMENT(i)
            }
            ENDCG
        }
    }
    
    // WebGL 1.0 호환성을 위한 폴백
    FallBack "Mobile/Diffuse"
}
```

WebGL 2.0의 고급 기능을 활용하면 앱인토스 미니앱의 렌더링 성능과 품질을 크게 높일 수 있어요.\
MRT, 인스턴싱, 고급 셰이더 기능을 통해 한층 더 완성도 높은 웹 게임 경험을 만들어보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/tutorials/webview.md'
description: 앱인토스 미니앱을 WebView로 개발 시작할 때 사용하는 튜토리얼입니다. WebView로 프로젝트를 스캐폴딩하는 방법들을 담고 있습니다.
---

# WebView

::: details 새 웹 프로젝트를 시작하시나요?
이 가이드에서는 이해를 돕기 위해 **Vite(React + TypeScript)** 기준으로 설명합니다.\
다른 빌드 환경을 사용하셔도 괜찮아요.

:::code-group

```bash[npm]
npm create vite@latest {project명} -- --template react-ts
cd {project명}
npm install
npm run dev
```

```bash[yarn]
yarn create vite {project명} --template react-ts
cd {project명}
yarn
yarn dev
```

```bash[pnpm]
pnpm create vite@latest {project명} --template react-ts
cd {project명}
pnpm install
pnpm dev
```

기존 웹 서비스가 이미 있으시다면, 아래 가이드에 따라 `@apps-in-toss/web-framework`를 설치해주세요.

:::

기존 웹 프로젝트에 `@apps-in-toss/web-framework`를 설치하면 앱인토스 샌드박스에서 바로 개발하고 배포할 수 있어요.

## 설치하기

기존 웹 프로젝트에 아래 명령어 중 사용하는 패키지 매니저에 맞는 명령어를 실행하세요.

::: code-group

```sh [npm]
npm install @apps-in-toss/web-framework
```

```sh [pnpm]
pnpm install @apps-in-toss/web-framework
```

```sh [yarn]
yarn add @apps-in-toss/web-framework
```

:::

## 환경 구성하기

`ait init` 명령어를 실행해 환경을 구성할 수 있어요.

1. `ait init` 명령어를 실행하세요.

::: code-group

```sh [npm]
npx ait init
```

```sh [pnpm]
pnpm ait init
```

```sh [yarn]
yarn ait init
```

:::

::: tip Cannot set properties of undefined (setting 'dev') 오류가 발생한다면?

package.json scripts 필드의 dev 필드에, 원래 사용하던 번들러의 개발 모드를 띄우는 커맨드를 입력 후 다시 시도해주세요.

:::

2. `web-framework`를 선택하세요.
3. 앱 이름(`appName`)을 입력하세요.

::: tip appName 입력 시 주의하세요

* 이 이름은 앱인토스 콘솔에서 앱을 만들 때 사용한 이름과 같아야 해요.
* 앱 이름은 각 앱을 식별하는 **고유한 키**로 사용돼요.
* appName은 `intoss://{appName}/path` 형태의 딥링크 경로나 테스트·배포 시 사용하는 앱 전용 주소 등에서도 사용돼요.
* 샌드박스 앱에서 테스트할 때도 `intoss://{appName}`으로 접근해요.\
  단, 출시하기 메뉴의 QR 코드로 테스트할 때는 `intoss-private://{appName}`이 사용돼요.
  :::

4. 웹 번들러의 dev 명령어를 입력해주세요.
5. 웹 번들러의 build 명령어를 입력해주세요.
6. 웹 개발 서버에서 사용할 포트 번호를 입력하세요.

### 설정 파일 확인하기

설정을 완료하면 설정 파일인 `granite.config.ts` 파일이 생성돼요.\
자세한 설정 방법은 [공통 설정](/bedrock/reference/framework/UI/Config.html) 문서를 확인해 주세요.

::: code-group

```ts [granite.config.ts]
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'ping-pong', // 앱인토스 콘솔에서 설정한 앱 이름
  brand: {
    displayName: '%%appName%%', // 화면에 노출될 앱의 한글 이름으로 바꿔주세요.
    primaryColor: '#3182F6', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
    icon: null, // 화면에 노출될 앱의 아이콘 이미지 주소로 바꿔주세요.
  },
  web: {
    host: 'localhost', // 앱 내 웹뷰에 사용될 host
    port: 5173,
    commands: {
      dev: 'vite', // 개발 모드 실행 (webpack serve도 가능)
      build: 'vite build', // 빌드 명령어 (webpack도 가능)
    },
  },
  permissions: [],
});
```

:::

* `brand`: 앱 브랜드와 관련된 구성이에요.
  * `displayName`: 브릿지 뷰에 표시할 앱 이름이에요.
  * `icon`: 앱 아이콘 이미지 주소예요. 사용자에게 앱 브랜드를 전달해요.
  * `primaryColor`: Toss 디자인 시스템(TDS) 컴포넌트에서 사용할 대표 색상이에요. RGB HEX 형식(eg. `#3182F6`)으로 지정해요.
* `web.commands.dev` 필드는 `granite dev` 명령어 실행 시 함께 실행할 명령어예요. 번들러의 개발 모드를 시작하는 명령어를 입력해주세요.
* `web.commands.build` 필드는 `granite build` 명령어 실행 시 함께 실행할 명령어예요. 번들러의 빌드 명령어를 입력해주세요.
* `webViewProps.type` 옵션에는 아래 세 가지 값 중 하나를 설정할 수 있어요.
  * `partner`: 파트너사 콘텐츠에 사용하는 기본 웹뷰예요. 다른 값을 설정하지 않으면 이 값이 기본으로 사용돼요.
  - `game`: 전체 화면을 사용하는 게임 콘텐츠처럼, 가득 찬 영역이 필요한 경우 사용해요.

::: tip 웹 빌드 시 주의사항

`granite build`를 실행하면 `web.commands.build`가 실행되고, 이 과정에서 생성된 결과물을 바탕으로 `.ait` 파일을 만들어요. `web.commands.build`의 결과물은 `granite.config.ts`의 `outdir` 경로와 같아야 해요.

`outdir`의 기본값은 프로젝트 경로의 `dist` 폴더지만, 필요하면 `granite.config.ts`에서 수정할 수 있어요. 만약 빌드 결과물이 `outdir`과 다른 경로에 저장되면 배포가 정상적으로 이루어지지 않을 수 있으니 주의하세요.

:::

### WebView TDS 패키지 설치하기

**TDS (Toss Design System)** 패키지는 웹뷰 기반 미니앱이 일관된 UI/UX를 유지하도록 돕는 토스의 디자인 시스템이에요.\
`@apps-in-toss/web-framework`를 사용하려면 TDS WebView 패키지를 추가로 설치해야 해요.\
모든 비게임 WebView 미니앱은 TDS 사용이 필수이며, 검수 승인 기준에도 포함돼요.

| @apps-in-toss/web-framework 버전 | 사용할 패키지              |
| -------------------------------- | -------------------------- |
| < 1.0.0                          | @toss-design-system/mobile |
| >= 1.0.0                         | @toss/tds-mobile           |

TDS에 대한 자세한 가이드는 [WebView TDS](https://tossmini-docs.toss.im/tds-mobile/)를 참고해주세요.

## 서버 실행하기

### 로컬 개발 서버 실행하기

로컬 개발 서버를 실행하면 웹 개발 서버와 React Native 개발 서버가 함께 실행돼요.
웹 개발 서버는 `granite.config.ts` 파일의 `web.commands.dev` 필드에 설정한 명령어를 사용해 실행돼요.

또, HMR(Hot Module Replacement)을 지원해서 코드 변경 사항을 실시간으로 반영할 수 있어요.

다음은 개발 서버를 실행하는 명령어에요.

Granite으로 스캐폴딩된 서비스는 `dev` 스크립트를 사용해서 로컬 서버를 실행할 수 있어요. 서비스의 루트 디렉터리에서 아래 명령어를 실행해 주세요.

::: code-group

```sh [npm]
npm run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [yarn]
yarn dev
```

명령어를 실행하면 아래와 같은 화면이 표시돼요.
![Metro 실행 예시](/assets/local-develop-js-1.B_LK2Zlw.png)

::: tip 실행 혹은 빌드시 '\[Apps In Toss Plugin] 플러그인 옵션이 올바르지 않습니다' 에러가 발생한다면?
'\[Apps In Toss Plugin] 플러그인 옵션이 올바르지 않습니다. granite.config.ts 구성을 확인해주세요.'\
라는 메시지가 보인다면, `granite.config.ts`의 `icon` 설정을 확인해주세요.\
아이콘을 아직 정하지 않았다면 ''(빈 문자열)로 비워둔 상태로도 테스트할 수 있어요.

```ts
...
displayName: 'test-app', // 화면에 노출될 앱의 한글 이름으로 바꿔주세요.
primaryColor: '#3182F6', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
icon: '',// 화면에 노출될 앱의 아이콘 이미지 주소로 바꿔주세요.
...
```

:::

### 개발 서버를 실기기에서 접근 가능하게 설정하기

실기기에서 테스트하려면 번들러를 실행할 때 `--host` 옵션을 활성화하고, `web.host`를 실 기기에서 접근할 수 있는 네트워크 주소로 설정해야 해요.

```ts [granite.config.ts]
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'ping-pong',
  web: {
    host: '192.168.0.100', // 실 기기에서 접근할 수 있는 IP 주소로 변경
    port: 5173,
    commands: {
      dev: 'vite --host', // --host 옵션 활성화
      build: 'vite build',
    },
  },
  permissions: [],
});
```

## 미니앱 실행하기(시뮬레이터·실기기)

:::info 준비가 필요해요
미니앱은 샌드박스 앱을 통해서만 실행되기때문에 **샌드박스 앱(테스트앱)** 설치가 필수입니다.\
개발 및 테스트를 위해 [샌드박스앱](/development/test/sandbox)을 설치해주세요.
:::

### iOS 시뮬레이터(샌드박스앱)에서 실행하기

1. **앱인토스 샌드박스 앱**을 실행해요.
2. 샌드박스 앱에서 스킴을 실행해요. 예를 들어 서비스 이름이 `kingtoss`라면, `intoss://kingtoss`를 입력하고 "스키마 열기" 버튼을 눌러주세요.

아래는 로컬 서버를 실행한 후, iOS 시뮬레이터의 샌드박스앱에서 서버에 연결하는 예시예요.

### iOS 실기기에서 실행하기

### 서버 주소 입력하기

아이폰에서 **앱인토스 샌드박스 앱**을 실행하려면 로컬 서버와 같은 와이파이에 연결되어 있어야 해요. 아래 단계를 따라 설정하세요.

1. **샌드박스 앱**을 실행하면 **"로컬 네트워크" 권한 요청 메시지**가 표시돼요. 이때 **"허용"** 버튼을 눌러주세요.

2) **샌드박스 앱**에서 서버 주소를 입력하는 화면이 나타나요.

3) 컴퓨터에서 로컬 서버 IP 주소를 확인하고, 해당 주소를 입력한 뒤 저장해주세요.
   * IP 주소는 한 번 저장하면 앱을 다시 실행해도 변경되지 않아요.
   * macOS를 사용하는 경우, 터미널에서 `ipconfig getifaddr en0` 명령어로 로컬 서버의 IP 주소를 확인할 수 있어요.

4) **"스키마 열기"** 버튼을 눌러주세요.

5) 화면 상단에 `Bundling {n}%...` 텍스트가 표시되면 로컬 서버에 성공적으로 연결된 거예요.

::: details "로컬 네트워크"를 수동으로 허용하는 방법
**"로컬 네트워크" 권한을 허용하지 못한 경우, 아래 방법으로 수동 설정이 가능해요.**

1. 아이폰의 \[설정] 앱에서 **"앱인토스"** 를 검색해 이동해요.
2. **"로컬 네트워크"** 옵션을 찾아 켜주세요.

:::

***

### Android 실기기 또는 에뮬레이터 연결하기

1. Android 실기기(휴대폰 또는 태블릿)를 컴퓨터와 USB로 연결하세요. ([USB 연결 가이드](/development/client/android.html#기기-연결하기))

2. `adb` 명령어를 사용해서 `8081` 포트와 `5173`포트를 연결하고 연결 상태를 확인해요.

   **8081 포트, 5173 포트 연결하기**

   기기가 하나만 연결되어 있다면 아래 명령어만 실행해도 돼요.

   ```shell
   adb reverse tcp:8081 tcp:8081
   adb reverse tcp:5173 tcp:5173
   ```

   특정 기기를 연결하려면 `-s` 옵션과 디바이스 아이디를 추가해요.

   ```shell
   adb -s {디바이스아이디} reverse tcp:8081 tcp:8081
   # 예시: adb -s R3CX30039GZ reverse tcp:8081 tcp:8081
   adb -s {디바이스아이디} reverse tcp:5173 tcp:5173
   # 예시: adb -s R3CX30039GZ reverse tcp:5173 tcp:5173
   ```

   **연결 상태 확인하기**

   연결된 기기와 포트를 확인하려면 아래 명령어를 사용하세요.

   ```shell
   adb reverse --list
   # 연결된 경우 예시: UsbFfs tcp:8081 tcp:8081

   ```

   특정 기기를 확인하려면 `-s` 옵션을 추가해요.

   ```shell
   adb -s {디바이스아이디} reverse --list
   # 예시: adb -s R3CX30039GZ reverse --list

   # 연결된 경우 예시: UsbFfs tcp:8081 tcp:8081
   ```

3. **앱인토스 샌드박스 앱**에서 스킴을 실행하세요. 예를 들어, 서비스 이름이 `kingtoss`라면 `intoss://kingtoss`를 입력하고 실행 버튼을 누르세요.

   아래는 Android 시뮬레이터에서 로컬 서버를 연결한 후 서비스를 표시하는 예시예요.

### 자주 쓰는 `adb` 명령어 (Android)

개발 중에 자주 쓰는 `adb` 명령어를 정리했어요.

#### 연결 끊기

```shell
adb kill-server
```

#### 8081 포트 연결하기

```shell
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173
# 특정 기기 연결: adb -s {디바이스아이디} reverse tcp:8081 tcp:8081
```

#### 연결 상태 확인하기

```shell
adb reverse --list
# 특정 기기 확인: adb -s {디바이스아이디} reverse --list
```

### 트러블슈팅

::: details Q. `서버에 연결할 수 없습니다` 에러가 발생해요.

`granite.config.ts` 의 `web.commands`에 '--host'를 추가 후, 서비스를 실행하여 어떤 호스트 주소로 서비스가 실행되는지 확인해요

```tsx
// granite.config.ts
  web: {
    ...
    commands: {
      dev: 'vite --host', // --host를 추가해요.
      build: 'tsc -b && vite build',
    },
    ...
  },
```

'--host' 추가 후, 서비스를 실행하여 주소를 확인해요

```tsx
// granite.config.ts
  web: {
     host: 'x.x.x.x', // 서비스가 실행되는 호스트 주소를 입력해요.
     ...
  },
```

샌드박스 앱에서 서비스 실행 전, metro 서버 주소도 호스트 주소로 변경해주세요.
:::

::: details Q. Metro 개발 서버가 열려 있는데 `잠시 문제가 생겼어요`라는 메시지가 표시돼요.

개발 서버에 제대로 연결되지 않은 문제일 수 있어요. `adb` 연결을 끊고 다시 `8081` 포트를 연결하세요.
:::

::: details Q. PC웹에서 Not Found 오류가 발생해요.

8081 포트는 샌드박스 내에서 인식하기 위한 포트예요.\
PC웹에서 8081 포트는 Not Found 오류가 발생해요.
:::

## 토스앱에서 테스트하기

토스앱에서 테스트하는 방법은 [토스앱](/development/test/toss) 문서를 참고하세요.

## 출시하기

출시하는 방법은 [미니앱 출시](/development/deploy) 문서를 참고하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/속성
  제어/webview-props.md
---

# WebView의 속성 제어하기

웹으로 개발한 서비스는 내부적으로 WebView가 사용돼요.

WebView의 설정을 변경하려면 `granite.config.ts` 파일에서 `webViewProps` 속성을 설정하면 돼요. 이를 활용하면 WebView의 동작을 조정하고 사용자 경험을 원하는 방식으로 제어할 수 있어요.

## 사용 가능한 WebView 속성

`webViewProps`에서 설정할 수 있는 주요 속성은 다음과 같아요.

### `allowsInlineMediaPlayback`

HTML5 동영상을 WebView 내에서 전체 화면이 아니라 인라인으로 재생할지 설정해요. iOS 전용 속성이에요. 이 값을 `true`로 설정하고 HTML 문서 내 `<video>` 태그에 `webkit-playsinline` 속성이 있으면 인라인 재생이 가능해요.

* **타입**: `boolean`
* **기본값**: `false`
* **플랫폼**: iOS

### `bounces`

WebView의 스크롤에서 콘텐츠 끝에 도달했을 때 튕기는 효과(바운스 효과)가 발생할지 설정해요. iOS 전용 속성이고, 기본값은 `true`에요.

* **타입**: `boolean`
* **기본값**: `true`
* **플랫폼**: iOS

### `pullToRefreshEnabled`

WebView에서 아래로 당겨서 새로고침하는 기능을 활성화할지 설정해요. iOS 전용 옵션이고, 기본값은 `true`에요. 이 값을 `true`로 설정하면 [`bounces`](#bounces) 옵션도 자동으로 `true`로 설정돼요.

* **타입**: `boolean`
* **기본값**: `true`
* **플랫폼**: iOS

### `overScrollMode`

WebView가 스크롤 콘텐츠 끝에 도달했을 때 Android에서 오버스크롤(over-scroll) 효과를 어떻게 처리할지 설정해요. Android 전용 옵션이고, 기본값은 `always`에요.

* **타입**: `'never'` | `'always'` | `'auto'`
* **기본값**: `'always'`
* **플랫폼**: Android
* **참고 문서**: [Android 공식 문서](https://developer.android.com/reference/android/view/View#OVER_SCROLL_NEVER)

### `mediaPlaybackRequiresUserAction`

오디오나 비디오가 자동으로 재생되지 않도록 설정할 수 있는 값이에요. 이 값을 `true`로 설정하면,\
콘텐츠는 자동으로 재생되지 않고 사용자가 직접 탭해야 재생돼요. 기본값은 `true`예요.

안드로이드에서는 버전 17 이상에서만 이 설정을 적용할 수 있어요.

* **타입**: `boolean`
* **기본값**: `true`
* **플랫폼**: iOS, Android
* **참고 문서**: [react-native-webview mediaPlaybackRequiresUserAction](https://github.com/react-native-webview/react-native-webview/blob/v13.6.2/docs/Reference.md#mediaplaybackrequiresuseraction)

### `allowsBackForwardNavigationGestures`

WebView에서 좌우 스와이프 제스처를 사용해 뒤로 가기 및 앞으로 가기 탐색을 할 수 있게 설정해요. 이 값을 `false`로 설정하면 사용자가 화면을 좌우로 스와이프해서 이전 페이지나 다음 페이지로 탐색할 수 없어요. 기본값은 `true`이고, 스와이프 제스처로 탐색할 수 있어요.

* **타입**: `boolean`
* **기본값**: `true`
* **플랫폼**: iOS
* **참고 문서**: [react-native-webview allowsBackForwardNavigationGestures](https://github.com/react-native-webview/react-native-webview/blob/v13.6.2/docs/Reference.md#allowsBackForwardNavigationGestures)

## 설정 예시

```tsx
import { defineConfig } from "@apps-in-toss/web-framework/config";

export default defineConfig({
  // 기타 설정
  webViewProps: {
    bounces: true,
    pullToRefreshEnabled: true,
    allowsInlineMediaPlayback: false,
    overScrollMode: "never",
  },
});
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/useVisibilityChange.md
---

# 가시성 변경 감지하기

## `useVisibilityChange`

`useVisibilityChange` 훅을 사용하면 페이지나 컴포넌트가 사용자에게 보이는지 여부가 변경될 때 이를 감지할 수 있어요. 화면이 보이는 상태가 바뀌면 전달된 콜백 함수가 호출돼요. 예를 들어, 사용자가 다른 탭으로 이동하거나, 창을 최소화할 때 콜백이 호출돼요.

반환값이 `true`이면 `visible`, `false`이면 `hidden` 문자열이 전달돼요.

::: tip 참고하세요
WebView에서 앱이 백그라운드로 전환되었을 때 콜백 함수를 등록하는 방법은 [visibilitychange](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilitychange_event)를 활용할 수 있어요.\
자세한 내용은 MDN Web Docs를 참고해 주세요.
:::

## 시그니처

```typescript
function useVisibilityChange(callback: VisibilityCallback): void;
```

### 파라미터

## 예제

### 화면의 보이는 상태가 변경될 때 로그를 남기는 예제

아래 코드는 화면의 보이는 상태가 변경될 때 `visibilityState` 값을 `console.log`로 기록하는 예시예요.

* 홈 화면으로 이동하면 `hidden`, 다시 돌아오면 `visible`을 기록해요.
* 외부 링크(`https://toss.im`)로 이동하면 `hidden`을 기록하고, 다시 돌아오면 `visible`을 기록해요.

```tsx{1,5-7}
import { useVisibilityChange } from '@granite-js/react-native';
import { Button, Linking } from 'react-native';

export default function ImagePage() {
  useVisibilityChange((visibilityState) => {
    console.log({ visibilityState });
  });

  return (
    <Button
      onPress={() => {
        Linking.openURL('https://toss.im');
      }}
      title="https://toss.im 이동"
    />
  );
}

/**
 * 출력 예시:
 * { "visibilityState": "hidden" }
 * { "visibilityState": "visible" }
 * { "visibilityState": "hidden" }
 * { "visibilityState": "visible" }
 */
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/저장소/removeItem.md
---

# 값 삭제하기

## `removeItem`

`removeItem` 함수는 모바일 앱의 로컬 저장소에서 특정 키에 해당하는 아이템을 삭제해요.

## 시그니처

```typescript
declare function removeItem(key: string): Promise<void>;
```

### 파라미터

### 반환 값

## 예제

### `my-key`에 저장된 아이템 삭제하기

::: code-group

```js [js]
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleSetStorageItem(value) {
  const storageValue = await Storage.setItem(KEY, value);
}

async function handleGetStorageItem() {
  const storageValue = await Storage.getItem(KEY);
  return storageValue;
}

async function handleRemoveStorageItem() {
  await Storage.removeItem(KEY);
}
```

```tsx [React]
import { Storage } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useState } from 'react';

const KEY = 'my-key';

function StorageClearButton() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onClick={handleSet}>저장하기</Button>
      <Button onClick={handleGet}>가져오기</Button>
      <Button onClick={handleRemove}>삭제하기</Button>
    </>
  );
}
```

```tsx [React Native]
import { Storage } from '@apps-in-toss/framework';
import { Button, Text } from '@toss/tds-react-native';
import { useState } from 'react';

const KEY = 'my-key';

function StorageClearButton() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onPress={handleSet}>저장하기</Button>
      <Button onPress={handleGet}>가져오기</Button>
      <Button onPress={handleRemove}>삭제하기</Button>
    </>
  );
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/저장소/getItem.md
---

# 값 읽기

## `getItem`

`getItem` 함수는 모바일 앱의 로컬 저장소에서 문자열 데이터를 가져와요. 주로 앱이 종료되었다가 다시 시작해도 데이터가 유지되어야 하는 경우에 사용해요.

## 시그니처

```typescript
function getItem(key: string): Promise<string | null>;
```

### 파라미터

### 반환 값

## 예제

### `my-key`에 저장된 아이템 가져오기

::: code-group

```js [js]
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleSetStorageItem(value) {
  const storageValue = await Storage.setItem(KEY, value);
}

async function handleGetStorageItem() {
  const storageValue = await Storage.getItem(KEY);
  return storageValue;
}

async function handleRemoveStorageItem() {
  await Storage.removeItem(KEY);
}
```

```tsx [React]
import { Storage } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useState } from 'react';

const KEY = 'my-key';

function StorageClearButton() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onClick={handleSet}>저장하기</Button>
      <Button onClick={handleGet}>가져오기</Button>
      <Button onClick={handleRemove}>삭제하기</Button>
    </>
  );
}
```

```tsx [React Native]
import { Storage } from '@apps-in-toss/framework';
import { Button, Text } from '@toss/tds-react-native';
import { useState } from 'react';

const KEY = 'my-key';

function StorageClearButton() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onPress={handleSet}>저장하기</Button>
      <Button onPress={handleGet}>가져오기</Button>
      <Button onPress={handleRemove}>삭제하기</Button>
    </>
  );
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/저장소/setItem.md
---

# 값 저장하기

## `setItem`

`setItem` 함수는 모바일 앱의 로컬 저장소에 문자열 데이터를 저장해요. 주로 앱이 종료되었다가 다시 시작해도 데이터가 유지되어야 하는 경우에 사용해요.

## 시그니처

```typescript
function setItem(key: string, value: string): Promise<void>;
```

### 파라미터

### 반환 값

## 예제

### `my-key`에 아이템 저장하기

::: code-group

```js [js]
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleSetStorageItem(value) {
  const storageValue = await Storage.setItem(KEY, value);
}

async function handleGetStorageItem() {
  const storageValue = await Storage.getItem(KEY);
  return storageValue;
}

async function handleRemoveStorageItem() {
  await Storage.removeItem(KEY);
}
```

```tsx [React]
import { Storage } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useState } from 'react';

const KEY = 'my-key';

function StorageClearButton() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onClick={handleSet}>저장하기</Button>
      <Button onClick={handleGet}>가져오기</Button>
      <Button onClick={handleRemove}>삭제하기</Button>
    </>
  );
}
```

```tsx [React Native]
import { Storage } from '@apps-in-toss/framework';
import { Button, Text } from '@toss/tds-react-native';
import { useState } from 'react';

const KEY = 'my-key';

function StorageClearButton() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onPress={handleSet}>저장하기</Button>
      <Button onPress={handleGet}>가져오기</Button>
      <Button onPress={handleRemove}>삭제하기</Button>
    </>
  );
}
```

:::

---

---
url: 'https://developers-apps-in-toss.toss.im/development/local-server.md'
description: >-
  앱인토스 개발 서버를 연결하는 방법을 안내합니다. Metro 서버 실행, iOS/Android 시뮬레이터 및 실기기에서 로컬 서버 연결
  방법을 확인하세요.
---

# 개발 서버 연결하기

::: tip 준비가 필요해요

개발 서버를 연결하려면 **앱인토스 샌드박스 앱**이 필요해요. 아래 가이드를 먼저 확인해주세요.

* [iOS 환경설정 문서 바로가기](/development/client/ios)
* [Android 환경설정 문서 바로가기](/development/client/android)

:::

## Metro 서버 실행하기

Bedrock으로 스캐폴딩된 서비스는 `dev` 스크립트를 사용해서 로컬 서버를 실행할 수 있어요. 서비스의 루트 디렉터리에서 아래 명령어를 실행해 주세요.

::: code-group

```sh [npm]
npm run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [yarn]
yarn dev
```

:::

명령어를 실행하면 아래와 같은 화면이 표시돼요.

![Metro 실행 예시](/assets/local-develop-js-1.B_LK2Zlw.png)

## iOS 시뮬레이터에서 실행하기

1. **앱인토스 샌드박스 앱**을 실행해요.
2. 샌드박스 앱에서 스킴을 실행해요. 예를 들어 서비스 이름이 `kingtoss`라면, `intoss://kingtoss`를 입력하고 "Bedrock 열기" 버튼을 눌러주세요.
3. Metro 서버가 실행 중이라면 시뮬레이터와 자동으로 연결돼요. 화면 상단에 `Bundling {n}%...`가 표시되면 연결이 성공한 거예요.

아래는 iOS 시뮬레이터에서 로컬 서버를 연결한 후 "Hello Bedrock!"을 표시하는 예시예요.

## iOS 실기기에서 실행하기

### 서버 주소 입력하기

아이폰에서 **앱인토스 샌드박스 앱**을 실행하려면 로컬 서버와 같은 와이파이에 연결되어 있어야 해요. 아래 단계를 따라 설정하세요.

1. **샌드박스 앱**을 실행하면 **"로컬 네트워크" 권한 요청 메시지**가 표시돼요. 이때 **"허용"** 버튼을 눌러주세요.

2) **샌드박스 앱**에서 서버 주소를 입력하는 화면이 나타나요.

3) 컴퓨터에서 로컬 서버 IP 주소를 확인하고, 해당 주소를 입력한 뒤 저장해주세요.

   * IP 주소는 한 번 저장하면 앱을 다시 실행해도 변경되지 않아요.
   * macOS를 사용하는 경우, 터미널에서 `ipconfig getifaddr en0` 명령어로 로컬 서버의 IP 주소를 확인할 수 있어요.

4) **"Bedrock 열기"** 버튼을 눌러주세요.

5) 화면 상단에 `Bundling {n}%...` 텍스트가 표시되면 로컬 서버에 성공적으로 연결된 거예요.

::: details "로컬 네트워크"를 수동으로 허용하는 방법
**"로컬 네트워크" 권한을 허용하지 못한 경우, 아래 방법으로 수동 설정이 가능해요.**

1. 아이폰의 \[설정] 앱에서 **"앱인토스"** 를 검색해 이동해요.
2. **"로컬 네트워크"** 옵션을 찾아 켜주세요.

:::

## Android에서 실행하기

### Android 실기기 또는 에뮬레이터 연결하기

1. Android 실기기(휴대폰 또는 태블릿)를 컴퓨터와 USB로 연결하세요. ([USB 연결 가이드](/development/client/android.html#기기-연결하기))

2. `adb` 명령어를 사용해서 `8081` 포트와 `5173`포트를 연결하고 연결 상태를 확인해요.

   **8081 포트, 5173 포트 연결하기**

   기기가 하나만 연결되어 있다면 아래 명령어만 실행해도 돼요.

   ```shell
   adb reverse tcp:8081 tcp:8081
   adb reverse tcp:5173 tcp:5173
   ```

   특정 기기를 연결하려면 `-s` 옵션과 디바이스 아이디를 추가해요.

   ```shell
   adb -s {디바이스아이디} reverse tcp:8081 tcp:8081
   # 예시: adb -s R3CX30039GZ reverse tcp:8081 tcp:8081
   adb -s {디바이스아이디} reverse tcp:5173 tcp:5173
   # 예시: adb -s R3CX30039GZ reverse tcp:5173 tcp:5173
   ```

   **연결 상태 확인하기**

   연결된 기기와 포트를 확인하려면 아래 명령어를 사용하세요.

   ```shell
   adb reverse --list
   # 연결된 경우 예시: UsbFfs tcp:8081 tcp:8081

   ```

   특정 기기를 확인하려면 `-s` 옵션을 추가해요.

   ```shell
   adb -s {디바이스아이디} reverse --list
   # 예시: adb -s R3CX30039GZ reverse --list

   # 연결된 경우 예시: UsbFfs tcp:8081 tcp:8081
   ```

3. **앱인토스 샌드박스 앱**에서 스킴을 실행하세요. 예를 들어, 서비스 이름이 `kingtoss`라면 `intoss://kingtoss`를 입력하고 실행 버튼을 누르세요.

4. Metro 서버가 실행 중이라면 실기기 또는 에뮬레이터와 자동으로 연결돼요. 화면 상단에 번들링 프로세스가 진행 중이면 연결이 완료된 거예요.

   아래는 Android 실기기에서 로컬 서버를 연결한 후 "Hello Bedrock!"을 표시하는 예시예요.

### 자주 쓰는 `adb` 명령어

개발 중에 자주 쓰는 `adb` 명령어를 정리했어요.

#### 연결 끊기

```shell
adb kill-server
```

#### 8081 포트 연결하기

```shell
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173
# 특정 기기 연결: adb -s {디바이스아이디} reverse tcp:8081 tcp:8081
```

#### 연결 상태 확인하기

```shell
adb reverse --list
# 특정 기기 확인: adb -s {디바이스아이디} reverse --list
```

### 트러블슈팅

::: details Q. Metro 개발 서버가 열려 있는데 `잠시 문제가 생겼어요`라는 메시지가 표시돼요.

개발 서버에 제대로 연결되지 않은 문제일 수 있어요. `adb` 연결을 끊고 다시 `8081` 포트를 연결하세요.
:::

::: details Q. PC웹에서 Not Found 오류가 발생해요.

8081 포트는 샌드박스 내에서 인식하기 위한 포트예요.\
PC웹에서 8081 포트는 Not Found 오류가 발생해요.
:::

---

---
url: 'https://developers-apps-in-toss.toss.im/ads/develop.md'
description: 인앱 광고 개발 방법입니다. 앱인토스에서 인앱광고를 개발할 때 참고해주세요.
---

# 개발하기

::: tip 참고하세요
SDK 1.0.3 버전 이상 사용해주세요.
:::

![](/assets/iaa_flow.DFEiXl1Q.png)

## 1. 광고 불러오기

**SDK를 통해 연동해 주세요.**

광고를 미리 불러와, 필요한 시점에 바로 노출할 수 있도록 준비하는 함수예요.\
자세한 내용은 [loadAppsInTossAdMob](/bedrock/reference/framework/광고/loadAppsInTossAdMob.md) 문서를 참고하세요.

::: tip 주의하세요
페이지 별로 광고를 미리 로드해 주세요.\
광고가 로드되지 않은 상태에서 호출하면 오류가 발생해 **fill-rate가 낮아질 수 있어요.**

***

**iOS에서 로드가 되지 않나요?**\
앱 추적 모드가 켜져있을 경우, 광고 로드가 정상적으로 동작하지 않을 수 있어요.\
**앱 추적 모드를 해제한 뒤 다시 시도해 주세요.**
:::

## 2. 광고 보여주기

**SDK를 통해 연동해 주세요.**

미리 불러온 광고를 실제 사용자에게 노출하는 함수예요.
자세한 내용은 [showAppsInTossAdMob](/bedrock/reference/framework/광고/showAppsInTossAdMob) 문서를 참고하세요.

::: tip 광고 로드 완료 후에 show를 호출하세요
`loadAppsInTossAdMob` 호출 후 **event를 받은 후에** `showAppsInTossAdMob` 를 호출해야 해요.\
로드가 로드되지 않은 상태에서 호출하면 오류가 발생해요.

또한 **한 번에 1개의 광고만 로드**되며, `load → show → 다음 광고 로드` 순서로 동작해야 합니다.\
광고를 표시한 뒤에는 다음 광고를 미리 load하여 준비해두는 것을 권장해요.\
즉, **`load → show → (다음 load) → show`** 형태로 구현하시면 안정적으로 운영할 수 있습니다.

:::

## 테스트하기

테스트용 광고 ID를 안내해 드려요.

::: tip 주의하세요
개발 테스트 시에는 **반드시 테스트용 광고 ID**를 사용해주세요.\
실제 광고 ID로 테스트하면 불이익을 받을 수 있어요.
:::

* 전면형 광고 : `ait-ad-test-interstitial-id`
* 리워드 광고 : `ait-ad-test-rewarded-id`

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: "샌드박스에서 인앱 광고 기능이 되지 않아요",
a: \`샌드박스에서는 인앱 광고 기능을 지원하지 않아요.

---

---
url: 'https://developers-apps-in-toss.toss.im/game-center/develop.md'
description: '게임 센터 개발 가이드입니다. SDK 연동, API 사용법, 구현 예제를 확인하세요.'
---

# 개발하기

![](/assets/leaderboard_flow.89s_SZOn.png)

## 1. 게임 리더보드에 점수 제출하기

**SDK를 통해 연동해 주세요.**

게임 종료 시 사용자의 점수를 리더보드에 제출합니다.\
사용자 식별은 앱인토스 SDK에서 자동으로 처리돼요.\
점수 제출이 완료되면 해당 사용자는 리더보드에서 자신의 점수를 확인할 수 있어요.\
[submitGameCenterLeaderBoardScore](../bedrock/reference/framework/게임/submitGameCenterLeaderBoardScore.md) 페이지를 확인해주세요.

::: tip 주의하세요

게임 프로필이 생성되기 전에 점수를 제출하면 오류가 발생할 수 있어요.\
게임에 진입하자마자 바로 점수를 제출하는 것은 피해 주세요.\
보안상의 이유로, 사용자 식별자는 응답에 포함되지 않아요.

:::

## 2. 게임 리더보드 열기

**SDK를 통해 연동해 주세요.**

사용자가 리더보드에서 자신의 순위를 확인할 수 있어요.\
친구 관계를 맺고 친구에게 점수를 공유하거나 자랑할 수도 있어요.\
[openGameCenterLeaderboard](../bedrock/reference/framework/게임/openGameCenterLeaderboard.md) 페이지를 확인해주세요.

::: tip 주의하세요

게임 프로필 WebView와 화면이 겹칠 수 있어요.\
게임 진입 직후 바로 리더보드를 호출하는 것은 피해 주세요.\
보안상의 이유로, 사용자 식별자는 응답에 포함되지 않아요.\
**리더보드를 열면 미니앱은 백그라운드 상태로 전환돼요.**\
리더보드에서 다시 돌아오면 포그라운드로 복귀하니, 게임 상태 관리에 유의하세요.

:::

![](/assets/leaderboard_1.ClRou2kf.png)

![](/assets/leaderboard_2.aVgnyiEG.png)

## 샌드박스 테스트

샌드박스 환경에서도 리더보드 기능을 테스트할 수 있어요.\
샌드박스에서 기록한 점수는 실제 서비스 리더보드에는 반영되지 않아요.

샌드박스 앱 최소 지원 버전을 확인하세요.

* android: 2025-12-16
* ios: 2025-12-07

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: "리더보드 함수 실행 시 LeaderBoard not found 에러가 발생해요.",
a: \`미니앱 정보 승인이 되지 않았는데 호출하면 발생하는 오류에요.

---

---
url: 'https://developers-apps-in-toss.toss.im/game-login/develop.md'
description: '게임 로그인 개발 가이드입니다. SDK 연동, API 사용법, 구현 예제를 확인하세요.'
---

# 개발하기

**SDK를 통해 연동해 주세요.**

`getUserKeyForGame` 함수는 게임 미니앱에서 유저를 식별할 수 있는 **고유 키 값**을 반환합니다.\
이 함수를 사용하면 **서버 연동 없이도 토스 로그인과 동일한 수준의 유저 식별**이 가능해요.

반환되는 유저 식별자(`hash`)는 **미니앱별로 고유**하며, **프로모션(토스 포인트)** 기능에서도 함께 사용할 수 있어요.

자세한 내용은 [getUserKeyForGame](/bedrock/reference/framework/게임/getUserKeyForGame.md) 페이지를 확인해주세요.

::: tip 주의하세요

* 이 함수는 **게임 카테고리 미니앱에서만** 사용할 수 있어요.\
  비게임 카테고리에서 호출하면 오류가 발생해요.
* **SDK 1.4.0 이상 버전, 토스앱 5.232.0 이상 버전**에서 지원돼요.\
  그 이하 버전에서는 `undefined`를 반환해요.
* 모든 유저의 식별자를 안정적으로 확보하기 위해, **토스앱 최소 지원 버전이 5.232.0 버전으로 상향**되었어요.\
  하위 버전에서는 **업데이트 안내 화면**이 표시돼요.
* 게임 유저 식별자는 **게임사 내부 유저 식별용 키**로만 사용되며, 해당 키로 **토스 서버에 직접 요청할 수 없어요.**
* 샌드박스에서는 mock 데이터가 내려가고 있어, QR 코드로 테스트를 부탁드려요.
  :::

---

---
url: 'https://developers-apps-in-toss.toss.im/iap/develop.md'
---
# 개발하기

::: tip 주의하세요

* SDK **1.1.3 버전 이상**을 사용해주세요.
  * SDK 1.1.3 버전부터는 **상품 지급 완료 과정**이 추가되어 함수 인터페이스가 변경되었어요.
* SDK **1.2.2 버전**부터는 **구매 복원 기능**이 추가되었어요.
* **사용자의 기기가 변경되더라도 인앱결제 상품이 지급 유지될 수 있도록 반드시 연동해주세요.**
  * [네이티브 저장소 기능](/bedrock/reference/framework/저장소/Storage.md)을 활용해 주세요.
  * 토스 로그인 연동과 인앱결제 상태 조회 API를 활용해 주세요.
* 인앱결제 상태 조회 API 사용을 위해서는 사전에 필히 [토스 로그인 연동](/login/intro.md)을 진행해 주세요.
  :::

![](/assets/iap_flow_1.KkFppG3t.png)

![](/assets/iap_flow_2.CFRXrQCk.png)

::: tip BaseURL
`https://apps-in-toss-api.toss.im`
:::

## 1. 상품 목록 가져오기

**SDK를 통해 연동해 주세요.**

콘솔에 등록한 인앱결제 상품 목록을 가져와요.\
가져온 상품 목록은 화면에 표시할 때 사용해요.

자세한 내용은 [IapProductListItem](/bedrock/reference/framework/인앱%20결제/getProductItemList.md) 페이지를 확인해 주세요.

## 2. 인앱결제 요청하기

**SDK를 통해 연동해 주세요.**

인앱결제 결제창을 띄우고, 사용자가 결제를 진행해요.\
결제 완료 후 앱인토스 서버가 실제 결제 여부를 검증하며, **구글/애플 영수증까지 확인해요.**\
만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.

**SDK 1.1.3 버전부터는 결제 성공 시 파트너사 상품 지급 로직이 실행돼요**\
파트너사 상품 지급 로직이 정상적으로 완료되면 콜백(`event.type: success`)이 전달돼요.\
지급 실패 시에는 `PRODUCT_NOT_GRANTED_BY_PARTNER` 오류 코드가 전달돼요. (토스앱 5.230.0 이상 지원)

자세한 내용은 인앱 결제 문서의 [createOneTimePurchaseOrder](/bedrock/reference/framework/인앱%20결제/IAP.md#createonetimepurchaseorder) 를 확인해주세요.

::: tip 주의하세요

환불 권한은 **앱마켓**에 있어요.\
앱마켓 환불 요청 및 승인 여부는 앱인토스에서 보장할 수 없으므로,테스트는 반드시 **소액**으로 진행해 주세요.

***

**SDK 1.1.3 버전부터는 지급 완료 과정이 추가되었어요.**\
함수 인터페이스가 변경되어, SDK 업데이트 시 꼭 코드 수정을 해주세요.

:::

## 3. 주문 복원하기

**SDK를 통해 연동해 주세요.**

미결 주문을 조회하여 사용자에게 상품을 지급하고, 해당 주문의 상태를 업데이트합니다.

* `getPendingOrders`
  * 결제는 완료되었지만 상품이 아직 지급되지 않은 주문 목록을 조회해요.
  * 조회된 주문의 `orderId`를 확인하여 사용자에게 상품을 지급하세요.

* `completeProductGrant`
  * 대기 중인 주문의 상품 지급을 완료 처리합니다.
  * 사용자에게 상품을 지급한 뒤, `completeProductGrant` 를 호출하여 지급 상태를 완료로 변경하세요.

앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 undefined를 반환해요.

자세한 내용은 인앱 결제 문서의 [getPendingOrders](/bedrock/reference/framework/인앱%20결제/IAP.md#getPendingOrders) 및 [completeProductGrant](/bedrock/reference/framework/인앱%20결제/IAP.md#completeProductGrant) 를 확인해주세요.

## 4. 주문 조회하기

결제 및 상품 지급이 완료된 주문, 또는 환불된 주문의 상태를 조회할 수 있어요.\
SDK와 API 두 가지 방식 중 상황에 맞게 선택해 사용해 주세요.

### 1) SDK로 조회하기

`getCompletedOrRefundedOrders` 는 인앱결제로 구매한 뒤 결제 및 지급이 완료된 주문과 환불된 주문 목록을 조회해요.\
결제는 완료되었지만 상품이 지급되지 않은 주문은 조회되지 않아요.

앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 undefined를 반환해요.

자세한 내용은 인앱 결제 문서의 [getCompletedOrRefundedOrders](/bedrock/reference/framework/인앱%20결제/IAP.md#getCompletedOrRefundedOrders) 를 확인해주세요.

### 2) API로 조회하기

API를 통해 서버에서 인앱결제 주문 상태를 직접 조회할 수 있어요.\
승인 혹은 환불 응답을 받지 못한 경우에도 사용할 수 있어요.

* Content-type : `application/json`
* Method : `POST`
* URL : `/api-partner/v1/apps-in-toss/order/get-order-status`

::: tip 참고하세요
결제 상태 조회 API 사용을 위해서는 토스 로그인 연동을 먼저 진행해 주세요.
:::

**요청 헤더**

| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string | Y | 토스 로그인을 통해 획득한 userKey 값 |

**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| orderId | String | Y | 결제 생성 후 취득한 주문번호(uuid v7) |

```json
{
    "orderId": "13c9a1ff-2baa-4495-bbfa-a0826ba8c7c0"
}
```

**응답**
| 이름 | 타입 | 설명 |
| --- | --- | --- |
| orderId | String | 요청한 주문번호 |
| sku | String | 주문한 상품 ID |
| statusDeterminedAt | String | 주문 완료 일시 (yyyy-MM-dd'T'HH:mm:ssZ)  `status`가 `REFUNDED`일 경우 환불 완료 일시|
| status | String | 주문에 대한 상태 (enum) |
| reason | String | 상태에 대한 설명 |

**status (enum)**
| **상태** | **설명** | **상세 설명**|
| --- | --- | --- |
| PURCHASED | 주문 완료 | 인앱 결제 및 상품 지급이 모두 완료된 상태 |
| PAYMENT\_COMPLETED | 결제 완료 | SDK 1.1.3 이상에서 결제는 완료되었으나 상품 지급이 실패한 상태 |
| FAILED | 주문 실패 | 결제가 실패한 경우 |
| REFUNDED | 주문 환불됨 | 환불 완료된 경우 |
| ORDER\_IN\_PROGRESS | 주문 진행 중 | 주문이 생성되었지만 결제/지급 처리가 완료되지 않은 경우 |
| NOT\_FOUND | 주문 없음 | 해당 주문번호를 찾을 수 없는 경우 |
| MINIAPP\_MISMATCH | 상품 불일치 | 주문한 상품이 해당 앱의 상품이 아닌 경우 |
| ERROR | 내부 오류 | 시스템 내부 오류 발생 시 |

```json
{
    "resultType": "SUCCESS",
    "success": {
        "orderId": "13c9a1ff-2baa-4495-bbfa-a0826ba8c7c0",
        "sku":"ait.0000010000.af647449.3bd55cfd00.0000000475",
        "statusDeterminedAt":"2025-09-12T16:57:12",
        "status": "PAYMENT_COMPLETED",
        "reason": "결제가 완료되었어요."
    }
}
```

```json
{
    "resultType": "SUCCESS",
    "success": {
        "orderId": "13c9a1ff-2baa-4495-bbfa-0000000000",
        "sku":"ait.0000010000.af647449.00000000000.0000000475",
        "statusDeterminedAt":"2025-09-12T16:57:12",
        "status": "PURCHASED",
        "reason": "완료된 주문이에요."
    }
}
```

***

## 샌드박스 테스트

출시 전에는 반드시 **샌드박스 앱 환경**에서 인앱결제가 정상적으로 동작하는지 테스트해 주세요.\
샌드박스에서는 실제 결제(과금)는 발생하지 않으며, 모든 결제가 테스트 시나리오로 처리돼요.

### 1. 샌드박스에서 상품 목록 조회 시 동작

샌드박스 앱에서 `getProductItemList()` 를 호출하면 콘솔에 등록된 인앱결제 상품 중 **노출 상태가 ON**인 상품만 조회돼요.

* 실제 콘솔에 등록한 상품 목록이 그대로 내려와요.
* 콘솔에서 **노출 OFF**인 상품은 샌드박스 앱에서도 보이지 않아요.

![](/assets/iap_sandbox_getProductItemList.C8nNi-uE.png)

### 2. 필수 테스트 시나리오

샌드박스에서는 아래 3가지 테스트를 반드시 각각 수행해야 해요.\
각 시나리오마다 앱이 올바르게 대응하는지 확인해 주세요.

#### ① 결제 성공 테스트

* 성공 콜백(`event.type: success`)이 정상적으로 전달되는지 확인해요.
* 실제 결제(과금)는 발생하지 않아요.
* SDK 1.1.3 이상에서는 파트너사의 **상품 지급 로직까지 성공해야 최종 성공**으로 처리돼요.

:::tip 확인해야 할 항목

* `orderId`, `amount` 등 `event.data` 정상 반환 여부
* 내부 지급 로직 정상 동작 여부
* 지급 완료 후 화면/UI 업데이트
  :::

#### ② 결제 성공(서버 실패) 테스트

결제는 성공했지만 파트너 서버의 지급 로직이 실패하는 경우를 반드시 테스트해야 해요.

* 앱은 다음 처리를 지원해야 해요:
  * 사용자에게 지급 실패 안내
  * 앱 재실행 시 `getPendingOrders` 로 미결 주문 복원
  * 지급 완료 후 `completeProductGrant` 호출

실서비스에서도 충분히 발생 가능한 시나리오이므로 반드시 테스트해야 해요.

#### ③ 에러 테스트

결제 도중 오류가 발생하는 다양한 상황을 미리 시뮬레이션하세요.

:::tip 테스트해야 할 대표 상황

* 네트워크 오류
* 사용자가 결제 취소
* 내부 오류
* 파트너사 상품 지급 실패
  :::

### 4. 테스트 체크리스트

| 테스트 항목 | 필수 | 확인 포인트 |
|-------------|------|-------------|
| 상품 목록 노출 | ✔️ | 콘솔에서 등록한 상품이 정상적으로 내려오는지 |
| 결제 성공 테스트 | ✔️ | `event.data` 처리, 지급 로직, UI 처리 |
| 결제 성공 + 서버 지급 실패 | ✔️ | 미결 주문 복원 및 재지급 처리 |
| 에러 테스트 | ✔️ | 에러 UI, 오류 처리, 재시도 흐름 |
| 주문 복원 처리 | 권장 | getPendingOrders → completeProductGrant |
| 주문 상태 조회 API | 권장 | 서버 검증 및 정합성 확인 |

## 자주 묻는 질문

---

---
url: 'https://developers-apps-in-toss.toss.im/login/develop.md'
description: '토스 로그인 개발 가이드입니다. SDK 연동, API 사용법, 구현 예제를 확인하세요.'
---

# 개발하기

![](/assets/login_flow.Dq_ZsON9.png)

::: tip BaseURL
`https://apps-in-toss-api.toss.im`
:::

## 1. 인가 코드 받기

**SDK를 통해 연동해주세요.**

사용자의 인증을 요청하고, 사용자가 인증에 성공하면 인가 코드를 메소드 응답으로 전달드려요.\
`appLogin` 함수를 사용해서 인가 코드(`authorizationCode`)와 `referrer`를 받을 수 있어요.\
[appLogin](../bedrock/reference/framework/로그인/appLogin.md)를 확인해 주세요.

* 샌드박스앱에서는 `referrer` 가 `sandbox`가 반환돼요
* 토스앱에서는 `referrer` 가 `DEFAULT` 가 반환돼요

::: tip 참고하세요

인가코드의 유효시간은 10분입니다.

:::

### **토스 로그인을 처음 진행할 때**

`appLogin` 함수를 호출하면 토스 로그인 창이 열리고, 앱인토스 콘솔에서 등록한 약관 동의 화면이 노출돼요.\
사용자가 필수 약관에 동의하면 인가 코드가 반환돼요.

### **토스 로그인을 이미 진행했을 때**

`appLogin` 함수를 호출하면 별도의 로그인 창 없이 바로 인가 코드가 반환돼요.

## 2. AccessToken 받기

사용자 정보 조회 API 호출을 위한 **접근 토큰을 발급해요.**

* Content-Type: `application/json`
* Method: `POST`
* URL: `/api-partner/v1/apps-in-toss/user/oauth2/generate-token`

::: tip 참고하세요
AccessToken의 유효시간은 1시간이에요.
:::

**요청**
| 이름 | 타입 | 필수값 여부 | 설명 |
|------|------|------|------|
|authorizationCode|string|Y|인가코드|
|referrer|string|Y|referrer|

**성공 응답**
| 이름 | 타입 | 필수값 여부 | 설명 |
|------|------|------|------|
|tokenType|string|Y|bearer 로 고정|
|accessToken|string|Y|accessToken|
|refreshToken|string|Y|refreshToken|
|expiresIn|string|Y|만료시간(초)|
|scope|string|Y|인가된 scope(구분)|

```json
{
   "resultType":"SUCCESS",
   "success":{
		    "accessToken":"eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJtMHVmMmhaUmpJTnNEQTdLNHVuVHhMb3IwcWNSa2JNPSIsImF1ZCI6IjNlenQ2ZTF0aDg2b2RheTlwOWN1eTg0dTRvdm5nNnNzIiwibmJmIjoxNzE4MjU0ODM2LCJzY29wZSI6WyJ1c2VyX2NpIiwidXNlcl9iaXJ0aGRheSIsInVzZXJfbmF0aW9uYWxpdHkiLCJ1c2VyX25hbWUiLCJ1c2VyX3Bob25lIiwidXNlcl9nZW5kZXIiXSwiaXNzIjoiaHR0cHM6Ly9jZXJ0LnRvc3MuaW0iLCJleHAiOjE3MTgyNTg0MzYsImlhdCI6MTcxODI1NDgzNiwianRpIjoiMTJkYjYwZjYtMjEzYS00NWQ3LTllOTItODBjMzBdseY2JkMGQ3In0.W1cjoeMN8pd3Jqgh6h8YzSVQ1PUNldulJJgy6bgH1AoDbv5xFTlBLzz9Slb_u52zUpyZbhglwblQmNJs7GT6-us7XtfxSGxTUY3ORqIhF_PPGQ6soi_Qgsi-hmX165CCAilf8cltSTTuTt8xOiEbLuSTY-cecxo7SkPUonQ_0v4_Ik0kwOiOBuYZyuch3KmlYQZTqsJmxlwJAPB8M9tZTtDpLOv9MEPU35YS7CZyN0l7lwn1EKrDHJdzA5CnstqEdz2I0eREmMgZoG9mSEybgD4NtPmVJos6AJerUGgSmzP_TwwlybVATuGpnAUmH1idaZJ-MHZJhUhR82z4zTn3bw",
		    "refreshToken":"xNEYPASwWw0n1AxZUHU9KeGj8BitDyYo4wi8rpfkUcJwByVxpAdUzwtIaWGVL6vHdrXLCxIlHAQRPF9hHnFleTsHkqUXzc-_78sD_r1Uh5Ff9UCYfArx8LTn1Vk99dDb",
		    "scope":"user_ci user_birthday user_nationality user_name user_phone user_gender",
		    "tokenType":"Bearer",
		    "expiresIn":3599
    }
}
```

**실패 응답**\
인가 코드가 만료되었거나 동일한 인가 코드로 AccessToken 을 중복으로 요청할 경우

```json
{
    "error":"invalid_grant"
}
```

```json
{
    "resultType":"FAIL",
    "error":{
        "errorCode":"INTERNAL_ERROR",
        "reason":"요청을 처리하는 도중에 문제가 발생했습니다."
    }
}
```

## 3. AccessToken 재발급 받기

사용자 정보 조회 API를 호출하기 위한 접근 토큰을 재발급해요.

* Content-type : application/json
* Method : `POST`
* URL : `/api-partner/v1/apps-in-toss/user/oauth2/refresh-token`

::: tip 참고하세요

refreshToken 유효시간은 14일이에요.

:::

**요청**
| 이름 | 타입 | 필수값 여부 | 설명 |
|------|------|------|------|
|refreshToken|string|Y|발급받은 RefreshToken|

**성공 응답**
| 이름 | 타입 | 필수값 여부 | 설명 |
|------|------|------|------|
|tokenType|string|Y|bearer 로 고정|
|accessToken|string|Y|accessToken|
|refreshToken|string|Y|refreshToken|
|expiresIn|string|Y|만료시간(초)|
|scope|string|Y|인가된 scope(구분)|

**실패 응답**
| 이름 | 타입 | 필수값 여부 | 설명 |
|------|------|------|------|
|errorCode|string|Y|에러 코드|
|reason|string|Y|에러 메시지|

## 4. 사용자 정보 받기

사용자 정보를 조회해요.\
`DI`는 `null`로 내려오며, 횟수 제한 없이 호출할 수 있어요.\
개인정보 보호를 위해 모든 개인정보는 **암호화된 형태**로 제공돼요.

* Content-type : application/json
* Method : `GET`
* URL : `/api-partner/v1/apps-in-toss/user/oauth2/login-me`

**요청 헤더**
| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| Authorization | string | Y | AccessToken으로 인증 요청  `Authorization: Bearer ${AccessToken}` |

**성공 응답**
| 이름 | 타입 | 필수값 여부 | 암호화 여부 | 설명 |
|--------------|--------|--------------|--------------|--------------------------------------------------------------|
| userKey | number | Y | N | 사용자 식별자 |
| scope | string | Y | N | 인가된 scope(구분) |
| agreedTerms | list | Y | N | 사용자가 동의한 약관 목록 |
| name | string | N | Y | 사용자 이름 |
| phone | string | N | Y | 사용자 휴대전화번호 |
| birthday | string | N | Y | 사용자 생년월일(yyyyMMdd) |
| ci | string | N | Y | 사용자 CI |
| di | string | N | Y | `null` 값 고정 |
| gender | string | N | Y | 사용자 성별(MALE/FEMALE) |
| nationality | string | N | Y | 사용자 내/외국인 여부(LOCAL/FOREIGNER) |
| email | string | N | Y | 사용자 이메일(점유인증 하지 않은 이메일 정보) |

```json
{
    "resultType":"SUCCESS",
    "success":{
        "userKey":443731104,
        "scope":"user_ci,user_birthday,user_nationality,user_name,user_phone,user_gender",
        "agreedTerms":["terms_tag1","terms_tag2"],
        "name":"ENCRYPTED_VALUE",
        "phone":"ENCRYPTED_VALUE",
        "birthday":"ENCRYPTED_VALUE",
        "ci":"ENCRYPTED_VALUE",
        "di":null,
        "gender":"ENCRYPTED_VALUE",
        "nationality":"ENCRYPTED_VALUE",
        "email":null
    }
}
```

**실패 응답**\
유효하지 않은 토큰을 사용할 경우, 현재 사용 중인 access\_token의 유효시간을 확인하고 재발급을 진행해주세요.

```json
{
    "error":"invalid_grant"
}
```

**서버 에러 응답 예시**\
| errorCode | 설명 |
|----------------|---------------------------|
| INTERNAL\_ERROR | 내부 서버 에러 |
| USER\_KEY\_NOT\_FOUND | 로그인 서비스에 접속한 유저 키 값을 찾을 수 없음 |
| USER\_NOT\_FOUND | 토스 유저 정보를 찾을 수 없음 |
| BAD\_REQUEST\_RETRIEVE\_CERT\_RESULT\_EXCEEDED\_LIMIT | 조회 가능 횟수 초과  동일한 토큰으로 `/api/login/user/me/without-di` API 조회하면 정상적으로 조회되나, di 필드는 null 값으로 내려감 |

```json
{
    "resultType":"FAIL",
    "error":{
        "errorCode":"INTERNAL_ERROR",
        "reason":"요청을 처리하는 도중에 문제가 발생했습니다."
    }
}
```

## 5. 사용자 정보 복호화하기

콘솔을 통해 이메일로 받은 `복호화 키`와 `AAD(Additional Authenticated DATA)` 로 진행해주세요.

**암호화 알고리즘**

* AES 대칭키 암호화
* 키 길이 : 256비트
* 모드 : GCM
* AAD : 복호화 키와 함께 이메일로 전달드려요.

**데이터 교환방식**

* 암호화된 데이터의 앞 부분에는 IV(NONCE)가 포함돼 있어요.
* 복호화 시 암호문에서 IV를 추출해 사용해야 정상적으로 복호화돼요.

**복호화 샘플 코드**

::: details Kotlin 예제

```kotlin
import java.util.Base64
import javax.crypto.Cipher
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.SecretKeySpec

class Test {
    fun decrypt(
        encryptedText: String,
        base64EncodedAesKey: String,
        add: String,
    ): String {
        val IV_LENGTH = 12
        val decoded = Base64.getDecoder().decode(encryptedText)
        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
        val keyByteArray = Base64.getDecoder().decode(base64EncodedAesKey)
        val key = SecretKeySpec(keyByteArray, "AES")
        val iv = decoded.copyOfRange(0, IV_LENGTH)
        val nonceSpec = GCMParameterSpec(16 * Byte.SIZE_BITS, iv)

        cipher.init(Cipher.DECRYPT_MODE, key, nonceSpec)
        cipher.updateAAD(add.toByteArray())

        return String(cipher.doFinal(decoded, IV_LENGTH, decoded.size - IV_LENGTH))
    }
}
```

:::

::: details PHP 예제

```php
<?php

class Test {
    public function decrypt($encryptedText, $base64EncodedAesKey, $add) {
        $IV_LENGTH = 12;
        $decoded = base64_decode($encryptedText);
        $keyByteArray = base64_decode($base64EncodedAesKey);
        $iv = substr($decoded, 0, $IV_LENGTH);
        $ciphertext = substr($decoded, $IV_LENGTH);

        $tag = substr($ciphertext, -16);
        $ciphertext = substr($ciphertext, 0, -16);

        $decrypted = openssl_decrypt(
            $ciphertext,
            'aes-256-gcm',
            $keyByteArray,
            OPENSSL_RAW_DATA,
            $iv,
            $tag,
            $add
        );

        return $decrypted;
    }
}


// 사용 예제
$test = new Test();
$encryptedText = "Encrypted Text"; // Encrypted Text 입력
$base64EncodedAesKey = "Key"; // Key 입력
$add = "TOSS";

$result = $test->decrypt($encryptedText, $base64EncodedAesKey, $add);
echo $result;

?>
```

:::

::: details JAVA 예제

```java
public class Test {
    public String decrypt(
        String encryptedText,
        String base64EncodedAesKey,
        String add
    ) throws Exception {
        final int IV_LENGTH = 12;
        byte[] decoded = Base64.getDecoder().decode(encryptedText);
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        byte[] keyByteArray = Base64.getDecoder().decode(base64EncodedAesKey);
        SecretKeySpec key = new SecretKeySpec(keyByteArray, "AES");
        byte[] iv = new byte[IV_LENGTH];
        System.arraycopy(decoded, 0, iv, 0, IV_LENGTH);
        GCMParameterSpec nonceSpec = new GCMParameterSpec(16 * Byte.SIZE, iv);

        cipher.init(Cipher.DECRYPT_MODE, key, nonceSpec);
        cipher.updateAAD(add.getBytes());

        byte[] decrypted = cipher.doFinal(decoded, IV_LENGTH, decoded.length - IV_LENGTH);
        return new String(decrypted);
    }
}
```

:::

## 6. 로그인 끊기

발급받은 AccessToken을 더 이상 사용하지 않거나 사용자의 요청으로 토큰을 만료시켜야 할 경우 토큰을 삭제(만료)해주세요.

* Content-type : application/json
* Method : `POST`
* URL :
  * accessToken 으로 연결 끊기 : `/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-access-token`
  * userKey 로 연결 끊기 : `/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-user-key`

**AccessToken 으로 로그인 연결 끊기**

```
// 포맷
curl --request POST 'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-access-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $access_token'

// 예시
curl --request POST 'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-access-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IizzYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJtMHVmMmhaUmpJTnNEQTdLNHVuVHhMb3IwcWNSa2JNPSIsImF1ZCI6IjNlenQ2ZTF0aDg2b2RheTlwOWN1eTg0dTRvdm5nNnNzIiwibmJmIjoxNzE4MjU0ODM2LCJzY29wZSI6WyJ1c2VyX2NpIiwidXNlcl9iaXJ0aGRheSIsInVzZXJfbmF0aW9uYWxpdHkiLCJ1c2VyX25hbWUiLCJ1c2VyX3Bob25lIiwidXNlcl9nZW5kZXIiXSwiaXNzIjoiaHR0cHM6Ly9jZXJ0LnRvc3MuaW0iLCJleHAiOjE3MTgyNTg0MzYsImlhdCI6MTcxODI1NDgzNiwianRpIjoiMTJkYjYwZjYtMjEzYS00NWQ3LTllOTItODBjMzBmY2JkMGQ3In0.W1cjoeMN8pd3Jqgh6h8YzSVQ1PUNldulJJgy6bgH1AoDbv5xFTlBLwk9Slb_u52zUpyZbhglwblQmNJs7GT6-us7XtfxSGxTUY3ORqIhF_PPGQ6soi_Qgsi-hmX165CCAilf8cltSTTuTt8xOiEbLuSTY-cecxo7SkPUonQ_0v4_Ik0kwOiOBuYZyuch3KmlYQZTqsJmxlwJAPB8M9tZTtDpLOv9MEPU35YS7CZyN0l7lwn1EKrDHJdzA5CnstqEdz2I0eREmMgZoG9mSEybgD4NtPmVJos6AJerUGgSmzP_TwwlybVATuGpnAUmH1idaZJ-MHZJhUhR82z4zTn3bw'
```

**userKey 로 로그인 연결 끊기**

::: tip 참고하세요

하나의 userKey에 연결된 AccessToken이 많을 경우 **readTimeout(3초)** 이 발생할 수 있어요.\
이 경우 요청을 재시도하지 말고, 일정 시간 후 다시 시도해 주세요.

:::

```
// 포맷
curl --request POST 'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-user-key' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $access_token' \
--data '{"userKey": $user_key}'

// 예시
curl --request POST 'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-user-key' \
--header 'Content-Type: application/json' \
--data '{"userKey": 443731103}'
```

```json
{
    "resultType": "SUCCESS",
    "success": {
        "userKey": 443731103
    }
}
```

## 7. 콜백을 통해 로그인 끊기

사용자가 토스앱 내에서 서비스와의 연결을 해제한 경우 가맹점 서버로 알려드려요.\
서비스에서 연결이 끊긴 사용자에 대한 처리가 필요한 경우 활용할 수 있어요.
콜백을 받을 URL과 basic Auth 헤더는 콘솔에서 입력할 수 있어요.

::: tip 꼭 확인해 주세요
서비스에서 직접 로그인 연결 끊기 API를 호출한 경우에는 **콜백이 호출되지 않아요.**
:::

**GET 방식**

* 요청 requestParam에 `userKey`와 `referrer`을 포함합니다.

```
// 포맷
curl --request GET '$callback_url?userKey=$userKey&referrer=$referrer'

// 예시
curl --request GET '$callback_url?userKey=443731103&referrer=UNLINK'
```

**POST 방식**

* 요청 body에 `userKey`와 `referrer`을 포함합니다.

```
// 포맷
curl --request POST '$callback_url' \
--header 'Content-Type: application/json' \
--data '{"userKey": $user_key, "referrer": $referrer}'

// 예시
curl --request POST '$callback_url' \
--header 'Content-Type: application/json' \
--data '{"userKey": 443731103, "referrer": "UNLINK"}'
```

referrer 은 연결 끊기 요청 경로에요.\
| referrer | 설명 |
|----------|------|
| `UNLINK` | 사용자가 토스앱에서 직접 연결을 끊었을 때 호출돼요.&#x20;
(경로: 토스앱 → 설정 → 인증 및 보안 → 토스로 로그인한 서비스 → ‘연결 끊기’) |
| `WITHDRAWAL_TERMS` | 사용자가 로그인 서비스 약관 동의를 철회할 때 호출돼요.&#x20;
(경로: 토스앱 → 설정 → 법적 정보 및 기타 → 약관 및 개인정보 처리 동의 → 서비스별 동의 내용 : "토스 로그인" → ‘동의 철회하기’) |
| `WITHDRAWAL_TOSS` | 사용자가 토스 회원을 탈퇴할 때 호출돼요. |

## 트러블슈팅

### 로컬 개발 중 인증 에러가 발생할 때

로컬에서 개발할 때 인증 에러가 발생하는 원인은 주로 두가지예요.

1. 인증 토큰이 만료됨\
   기존에 발급받은 인증 토큰이 만료되었을 수 있어요. 새로운 토큰을 발급받아 다시 시도해보세요.

2. 개발자 로그인이 되지 않음
   샌드박스 환경에서 개발자 계정으로 로그인하지 않은 상태일 수 있어요. [샌드박스 앱 다운로드](/development/test/sandbox)를 참고해 로그인을 진행한 뒤 다시 시도해보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/promotion/develop.md'
---
# 개발하기

## 게임

**SDK를 통해 연동해 주세요.**

[게임 로그인 `getUserKeyForGame`](/bedrock/reference/framework/%EA%B2%8C%EC%9E%84/getUserKeyForGame.md) 으로부터 받은 **유저 식별자(hash)** 를 사용해 유저에게 프로모션 리워드를 지급할 수 있어요.\
별도의 서버 연동 없이도 **게임 미니앱 내에서 유저에게 토스 포인트를 지급**하고, **혜택탭에 프로모션을 노출**하여 트래픽을 키울 수 있어요.

> **⚠️ 중복 호출 주의**\
> `grantPromotionRewardForGame` 함수를 중복 호출하면 동일한 유저에게 리워드가 중복 지급될 수 있으니, **방어 로직을 반드시 적용**해 주세요.

자세한 내용은 [grantPromotionRewardForGame](/bedrock/reference/framework/%EA%B2%8C%EC%9E%84/grantPromotionRewardForGame.md) 문서를 참고해주세요.

::: tip 주의하세요

* **토스앱 5.232.0 버전 이상에서만 지원**해요.\
  이 버전 미만에서는 `undefined`가 반환돼요.
* 모든 사용자의 식별자를 안정적으로 확보하기 위해 **토스앱 최소 지원 버전을 5.232.0으로 상향**했어요.\
  최소 버전 미만에서는 미니앱 진입 시 **업데이트 안내 화면**이 표시돼요.
* 실제 프로모션을 시작하기 전에, **테스트용 프로모션 코드로 최소 1회 이상 호출**해야 합니다.\
  테스트 호출을 통해 프로모션이 정상적으로 등록 및 승인 상태로 전환돼요.
  :::

***

## 비게임

![](/assets/promotion_flow.BdhSGaIm.png)

::: tip BaseURL
`https://apps-in-toss-api.toss.im`
:::

### ① 프로모션 리워드 지급 Key 생성하기

프로모션 지급을 위한 Key를 발급합니다.\
이 Key를 사용해 유저에게 리워드를 지급할 수 있어요.

::: tip 주의해주세요

* **유저에게 리워드를 지급하는 주체는 파트너사예요.**\
  발급받은 Key로 유저에게 리워드를 지급하면, **프로모션 예산 한도 내에서** 지속적으로 지급돼요.

* **1회 지급만 허용**하려면 파트너사에서 자체적으로 제어해야 해요.

* 이미 사용한 지급 Key로 다시 지급을 시도하면 `4113` 에러가 발생해요.\
  추가 지급이 필요할 경우, **새로운 Key를 발급**해 주세요.

* 발급받은 **Key의 유효시간은 1시간**이에요
  :::

* Content-type : application/json

* Method : `POST`

* URL : `/api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key`

**요청 헤더**\
| 이름          | 타입    | 필수값 여부 | 설명                                                                 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string  | Y            | 토스 로그인을 통해 획득한 userKey 값 |

**응답 파라미터**
| 이름 | 타입 | 설명 |
| --- | --- | --- |
| key | String | 프로모션 지급을 위한 key 값  base64 인코딩된 값 |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}
```

### ② 프로모션 리워드 지급하기

발급받은 key로 **프로모션 리워드 지급을 실행**해요.\
지급 시 프로모션 예산에서 차감되며, 실제 지급까지는 약간의 지연이 발생할 수 있어요.

* Content-type : application/json
* Method : `POST`
* URL : `/api-partner/v1/apps-in-toss/promotion/execute-promotion`

**요청 헤더**\
| 이름          | 타입    | 필수값 여부 | 설명                                                                 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string  | Y            | 토스 로그인을 통해 획득한 userKey 값 |

**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| promotionCode | String | Y | 콘솔에서 생성한 프로모션 코드ID |
| key | String | Y | 프로모션 지급을 위해 발급받은 KEY값 |
| amount | Integer | Y | 프로모션 지급 금액 |

```json
{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
	"key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0=",
  "amount": 10
}
```

**응답**
| 이름 | 타입 | 설명 |
| --- | --- | --- |
| key | String | 프로모션 지급을 위해 발급받은 KEY값 |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}
```

### ③ 프로모션 지급 결과 조회하기

지급 요청 이후의 **프로모션 지급 상태를 조회**해요.

* Content-type : application/json
* Method : `POST`
* URL : `/api-partner/v1/apps-in-toss/promotion/execution-result`

**요청 헤더**\
| 이름          | 타입    | 필수값 여부 | 설명                                                                 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string  | Y            | 토스 로그인을 통해 획득한 userKey 값 |

**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| promotionCode | String | Y | 콘솔에서 생성한 프로모션 코드ID |
| key | String | Y | 프로모션 지급을 위해 발급받은 KEY값 |

```json
{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
	"key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
}
```

**응답**
| 이름 | 타입 | 설명 |
| --- | --- | --- |
| success | String | 프로모션 지급 결과  - SUCCESS  - PENDING   - FAILED |

```json
{
  "resultType": "SUCCESS",
  "success": "PENDING"
}
```

### 에러 코드

프로모션 API 사용 중 발생할 수 있는 에러 코드 목록입니다.\
응답 코드나 메시지를 참고해 **적절한 예외 처리 로직**을 적용해 주세요.

::: tip `4109` 에러가 발생한다면?

* 프로모션 예산의 **80% 소진이 이메일로 안내**가 발송돼요.
* 프로모션을 계속 진행하려면 **콘솔에서 예산을 증액**해 주세요.
* 예산이 부족할 경우, **비즈월렛에서 금액을 충전**해 예산을 늘릴 수 있어요.
* 예산이 모두 소진되면 프로모션이 **자동으로 종료되어 `4109` 에러가 발생**해요.
* 예산 부족으로 인해 포인트 지급이 실패하면 **사용자 CS 이슈로 이어질 수 있으니 주의**해 주세요.
  :::

| 코드 | 메시지 | 발생 원인 / 대응 방법 |
|------|--------|-------------------|
| `4100` | 프로모션 정보를 찾을 수 없어요 | 콘솔에 등록되지 않은 프로모션 키로 호출한 경우|
| `4109` | 프로모션이 실행중이 아니에요 | 콘솔에서 프로모션을 시작하지 않았거나, 예산이 모두 소진되어 자동 종료된 경우|
| `4110` | 리워드를 지급/회수할 수 없어요 | 내부 시스템 오류 발생한 경우로, **재지급 로직**을 적용해 주세요. |
| `4111` | 리워드 지급내역을 찾을 수 없어요 |존재하지 않은 지급 내역을 조회한 경우|
| `4112` | 프로모션 머니가 부족해요 |예산 부족으로 지급이 실패한 경우로, 콘솔에서 예산 증액 또는 비즈월렛 충전 필요|
| `4113` | 이미 지급/회수된 내역이에요 |동일한 Key로 중복 지급할 경우로, 새로운 Key를 발급해 재시도해주세요.|
| `4114` | 1회 지급 금액을 초과했어요 ||
| `4116` | 최대 지급 금액이 예산을 초과했어요 ||

---

---
url: 'https://developers-apps-in-toss.toss.im/push/develop.md'
description: '푸시 알림 개발 가이드입니다. SDK 연동, API 사용법, 구현 예제를 확인하세요.'
---

# 개발하기

![](/assets/push_3.C3w3QjH_.png)

## 테스트 메시지 발송 API

개발 과정에서 실제 사용자에게 메시지를 전송해 동작을 검증하고 싶다면,\
테스트용 메시지 발송 API를 사용할 수 있어요.

::: tip 테스트 메시지 API\
이 API는 파트너 앱이 토스 사용자에게 알림 또는 메시지를 **테스트 발송**할 수 있도록 제공돼요.\
사용자 인증 토큰이 필요하며, 메시지 전송 scope 권한이 포함돼야 해요.

[테스트 메시지 발송 API 보러가기](/api/sendTestMessage.html)
:::

## 메시지 발송 API

::: tip BaseURL
`https://apps-in-toss-api.toss.im`
:::

파트너 앱이 토스 사용자에게 메시지를 발송할 때 사용하는 기본 API예요.

* Content-type : application/json
* Method : `POST`
* Endpoint : `/api-partner/v1/apps-in-toss/messenger/send-message`

**요청 헤더**\
| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string | Y | 토스 로그인을 통해 획득한 userKey 값 |

**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| templateSetCode | String | Y | 발송할 메시지 템플릿 코드값|
| context | object|Y|등록된 템플릿의 내용 중 변수 전달|

```json
{
	"templateSetCode":"test_01", //발송할 메시지 템플릿 코드값
	"context": { // 등록된 템플릿의 내용 중 변수 전달
		"storeName": "토스증권",
		"date": "2025-01-20 15:30"
		// userName 은 발송 시 유저의 이름으로 적용되는 기본 변수이기 때문에 전달할 필요 없음
	}
}
```

**응답**

```json
{
	"resultType": "SUCCESS" // HTTP_TIMEOUT, NETWORK_ERROR, EXECUTION_FAIL, INTERRUPTED, INTERNAL_ERROR, FAIL
	"result":{
		"msgCount": 1, // 발송 성공 카운트
		"sentPushCount": 1, // 발송 성공 푸시 카운트
		"sentInboxCount: 0, // 발송 성공 Inbox(알림) 카운트
		"sentSmsCount": 0, // 발송 성공 문자 카운트
		"sentAlimtalkCount": 0, // 발송 성공 알림톡 카운트
		"sentFriendtalkCount": 0, // 발송 성공 친구톡 카운트
		"detail": {
			"sentPush":[
				{
					"contentId":"toss:PUSH~~~~", // 발송 성공한 푸시의 메시지 키
				}
			],
			"sentInbox":[], // sentPush 와 동일 포맷
			"sentInbox":[], // sentPush 와 동일 포맷
			"sentSms":[], // sentPush 와 동일 포맷
			"sentAlimtalk":[], // sentPush 와 동일 포맷
			"sentFriendtalk":[], // sentPush 와 동일 포맷
		}
		"fail": {
				"sentPush":[
					{
						"contentId":"toss:PUSH~~~~", // 발송 성공한 푸시의 메시지 키
						"reachFailReason: "실패사유", // 실패 사유
					}
				],
				"sentInbox":[], // sentPush 와 동일 포맷
				"sentInbox":[], // sentPush 와 동일 포맷
				"sentSms":[], // sentPush 와 동일 포맷
				"sentAlimtalk":[], // sentPush 와 동일 포맷
				"sentFriendtalk":[], // sentPush 와 동일 포맷
		}
	},
	"error": {
    "errorType": 0,
    "errorCode": "string",
    "reason": "string",
    "data": {
      "additionalProp1": {},
      "additionalProp2": {},
      "additionalProp3": {}
    },
    "title": "string"
  }
}
```

```json
curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/messenger/send-message' \
--header 'Content-Type: application/json' \
--header 'X-Toss-User-Key: {{유저 정보 조회에서 나온 userKey}}'
--data '{
	"templateSetCode":"vivarepublica_hello_world", //발송할 메시지 템플릿 코드값
	"context": { // 등록된 템플릿의 내용 중 변수 전달
		"storeName": "비바리퍼블리카",
		"greetDate": "2025년 01월 20일 15시 30분"
		// userName 은 발송 시 유저의 이름으로 적용되는 기본 변수이기 때문에 전달할 필요 없음
	}
}'
```

---

---
url: 'https://developers-apps-in-toss.toss.im/reward/develop.md'
description: '공유 리워드 개발 가이드입니다. SDK 연동, API 사용법, 구현 예제를 확인하세요.'
---

# 개발하기

**SDK를 통해 연동해 주세요.**

사용자가 친구 초대를 통해 리워드를 획득할 수 있어요.\
콘솔에서 입력한 공유 리워드 화면을 노출하고, 사용자가 친구에게 공유하기를 완료하면 event를 전달드려요.\
[contactsViral](../bedrock/reference/framework/친구초대/contactsViral.md) 페이지를 확인해주세요.

### 게임

![](/assets/reward_flow.DoOU8nLb.png)

### 비게임

![](/assets/reward_flow_nongame.64rEEzg-.png)

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: "샌드박스에서 공유 리워드 기능이 되지 않아요",
a: \`샌드박스에서는 공유 리워드 기능을 지원하지 않아요.

---

---
url: 'https://developers-apps-in-toss.toss.im/tossauth/develop.md'
description: '토스 인증 개발 가이드입니다. SDK 연동, API 사용법, 구현 예제를 확인하세요.'
---

# 개발하기

::: tip 최소 버전을 확인하세요

* **SDK** : 1.2.1 이상
* **토스앱 (본인확인)** : 5.233.0 이상
* **토스앱 (원터치 인증)** : 5.236.0 이상

[getTossAppVersion](/bedrock/reference/framework/환경%20확인/getTossAppVersion) 함수를 사용하여 토스앱 버전을 체크해보세요.
:::

![](/assets/tossauth_flow.DcI87xBa.png)

## 1. AccessToken 받기

토스 본인확인을 위한 **Access Token**을 발급받아요.\
발급된 토큰은 이후 모든 API 호출의 **Authorization** 헤더에 사용돼요.

토큰에는 **만료 시간(`expires_in`)** 이 있어요. 만료 시 새 토큰을 발급해야 하고, **유효한 토큰이 있으면 재발급을 피해서** 불필요한 호출을 줄여 주세요.

* Base URL: `https://oauth2.cert.toss.im`
* Endpoint: `/token`
* Method: `POST`
* Content-Type: `application/x-www-form-urlencoded`

**요청 헤더**

| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|---------------------------------------------|
| Content-Type | string | Y | `application/x-www-form-urlencoded` |

**요청 파라미터**

| 이름 | 타입 | 필수값 여부 | 설명 |
| --- | --- | --- | --- |
| grant\_type | string | Y | 고정 값: `client_credentials` |
| scope | string | Y | 인증 요청 범위 (예: `ca`) |
| client\_id | string | Y | 고객사에 발급된 클라이언트 아이디 |
| client\_secret | string | Y | 고객사에 발급된 클라이언트 시크릿 |

::: code-group

```bash [Shell(curl)]
curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=test_a8e23336d673ca70922b485fe806eb2d' \
--data-urlencode 'client_secret=test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3' \
--data-urlencode 'scope=ca'
```

```java
URL url = new URL("https://oauth2.cert.toss.im/token");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST"); 

httpConn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("grant_type=client_credentials&" +
        "client_id=test_a8e23336d673ca70922b485fe806eb2d&" +
        "client_secret=test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3&" +
        "scope=ca");
writer.flush();
writer.close(); 

httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() == 200
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
```

```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://oauth2.cert.toss.im/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type' : 'application/x-www-form-urlencoded',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'grant_type=client_credentials&client_id=test_a8e23336d673ca70922b485fe806eb2d&client_secret=test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3&scope=ca');

$response = curl_exec($ch);

curl_close($ch);
```

:::

**응답**

| 이름 | 타입 | 설명 |
| --- | --- | --- |
| access\_token | string | Access Token 값 |
| scope | string | 발급된 인증 범위 |
| token\_type | string | 토큰 타입 (항상 `Bearer`) |
| expires\_in | number | 토큰 만료 시간(초 단위) |

```json
{
  "access_token": "eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ",
  "scope": "ca",
  "token_type": "Bearer",
  "expires_in": 31536000
}
```

## 2. 인증 요청하기

토스 인증 서버에서 `txId`를 발급받아 본인확인 절차를 시작해요.

* BaseURL : `https://cert.toss.im`
* Endpoint : `/api/v2/sign/user/auth/id/request`
* Method : `POST`
* Content-type : `application/json`

## 2-1. 개인정보 기반 인증

고객의 **이름·생년월일·전화번호** 를 **암호화 후 전송**하는 방식이에요.\
보안을 위해 [세션키(sessionKey)](/bedrock/reference/framework/인증/tosscertSessionKey.html)는 매 요청마다 새로 생성하세요.

**요청 헤더**

| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|---------------------------------------------|
| Authorization | string | Y | `Bearer {Access Token}` |
| Content-Type | string | Y | `application/json` |

**요청 파라미터**

| 이름 | 타입 | 필수값 여부 | 설명 |
| --- | --- | --- | --- |
| requestUrl | string | Y | 토스 본인확인 사용 시 돌아갈 고객사 앱스킴 |
| requestType | string | Y | `USER_PERSONAL` |
| triggerType | string | Y | `APP_SCHEME` |
| userName | string | Y | [암호화](/bedrock/reference/framework/인증/tosscertEncrypt.html) 필수 |
| userPhone | string | Y | 숫자만, [암호화](/bedrock/reference/framework/인증/tosscertEncrypt.html) 필수 |
| userBirthday | string | Y | `YYYYMMDD`, [암호화](/bedrock/reference/framework/인증/tosscertEncrypt.html) 필수 |
| sessionKey | string | Y | AES 암복호화용, 매 요청마다 신규 생성 필요 [(생성 방법)](/bedrock/reference/framework/인증/tosscertSessionKey.html)|

### 요청 예시

::: code-group

```bash [Shell(curl)]
curl --location --request POST 'https://cert.toss.im/api/v2/sign/user/auth/id/request' --header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' --header 'Content-Type: application/json' # 세션 키는 매 요청 시 새로 생성해야 합니다.
--data-raw '{
       "requestType" : "USER_PERSONAL",
       "requestUrl" : "intoss://my-granite-app",
       "triggerType" : "APP_SCHEME",
       "userName" : "v1$cc575847-f549-4c1e-89c7-eff11743e05e$5AfwdVLSmDoxBERDIV8gDny2QLcOzYOqvgt1l4gqEA==",
       "userPhone" : "v1$cc575847-f549-4c1e-89c7-eff11743e05e$OKtwqMR/RI+N3vx0FNtcx8GAoejDq5lb3wIr",
       "userBirthday" : "v1$cc575847-f549-4c1e-89c7-eff11743e05e$OaNxoMR2RYaPiH7km5yJyZQ472+uWNEy",
       "sessionKey" : "v1$cc575847-f549-4c1e-89c7-eff11743e05e$XTTyBJntTja9NfUaTaO09bQCtEApnn3dd7lN8s+jPA6qn5q5kBbSJEptazpSMqGFyB7P0XhnJSkRwukAuunesbm+e0p5tdQ7wiOkauM44FvZj/IwETTA74iLZTNrwmE3aYXv8b1wbIfQx/oT8k9+XNEPkHA0foCFtjF8MRnyjwpzR4hoi2sFk33xhoJa46kLGxz7d3z6r/KYKMFbwkQFOm81Nk8W+oJkT0AjdlOD075QrJ4zm9VReVvE4fT4Q1jY/5VzROt4GkqVvrziYbWRp9/v1/ETVyi5Lf+MceWHLS1MGicqUXfrfnFdqvOcZZytUkvb0AAyg75Sr5tgja55ma3t5AEu65IrO1Cop4wS/XhIwKpWUrMav5JI5X1iZ1tRznE7VRT/dsRLjgIX/wtZajY2ATG+feld2mmxD/mP/ET3JXsYKfmN3DkO10fQZY9915eUyDYm7NMS/U3l+VP8wMzd5WpWVjfxUvYP5eRwPM83hG9wFhHXV4ykodiX0BLRoERXou416uKDJR61b8xFFX+iDPnOfaeROlFFWj6zbK4tPfjRzyaWVQMmSM8igq7iBglehFo+EyyQnAAcUeda+P/7fQmwFDE1a8bQuXFBCwxNOOyPiJLV2+29pzKELcHa+WCrvcbHkOgG4EwjHHWmd17vUVXZGXOERsRuLQMM3mM="
    }'
```

```java
URL url = new URL("https://cert.toss.im/api/v2/sign/user/auth/id/request");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST");
httpConn.setRequestProperty("Authorization", "Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ");
httpConn.setRequestProperty("Content-Type", "application/json");
// 세션 키는 매 요청 시 새로 생성해야 합니다.
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("{" +
        "\"requestType\" : \"USER_PERSONAL\"," +
        "\"triggerType\" : \"APP_SCHEME\"," +
        "\"userName\" : \"v1$255f8cc3-7d1d-4667-b28b-03f44e09483f$ZUyjGpmb/nL9W7//N1/VUN/F/947biU+1w==\"," +
        "\"userPhone\" : \"v1$255f8cc3-7d1d-4667-b28b-03f44e09483f$v8QTxScwJ/NBA+Gp/TXerMWQp9BrQ45M7xaC\"," +
        "\"userBirthday\" : \"v1$255f8cc3-7d1d-4667-b28b-03f44e09483f$vswaxSEyJf/J7Qndq2E7iOPJOmIWILby\"," +
        "\"sessionKey\" : \"v1$255f8cc3-7d1d-4667-b28b-03f44e09483f$MdeifC7fngWC9qn/qia1Itp6jYulvhTH1JCln0oYp3xg95VpnqN5O5isZ58ZYD1WM03YooETiwQIjtLEMl2HSjxwlXZQ2yoyd/zH3mgCzlVDd/nOO0AI04Rzo/M7mvdfoN/k+DUBAeQ4NBIC9uqMt0JrkpuGvv3O1faYPBCV6OCMIcAOAbQb9fJx1bWFRLMkhd3meTD9wt2px46Kz7kW/FZXefMJr4qdnJEX9pZKz2QMJCMEnu0aW+AkJQUS5VfPSohrFTS8VeWoiNArFSESIxZhX3A+duAIJrYxTvXvOCM9ntO9xIMwTd+hp9L1UAYFOrqh6J2gmN1nI5ScBvtkLwRMFQ1D/eoSL/HD7Xb9cBAxMxPX4dn0OjLkUuO0y+KW4s+Prj9IYesDEkXUQpuQKz+4mLfX88lyplJ7o2x3uoecFlIBT92oY6BI+yxTATnwSIK249OwX2vuG6HLSOXlI3RScHjEDtzz1zPK6kjCGkFBM+5+gMyTIF4C130Uk4rlXpxYOGwPoBKBD2buGbBh7AHIaFgHlYjShdPiHMCF0ZDQnOubk139cRzoCVkKqdpPgVqIy8q6982UXzeoSIxqpSauqaL0IK2PPbMy3s9WH12NrDFDkg4NLAhnEgGNfOPjMl9lRMW+i4cCw0jhaCx1bu5GTEQzDCpc0DFT+/KPkKc=\"" +
        "}");
writer.flush();
writer.close();
httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() == 200
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
```

```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://cert.toss.im/api/v2/sign/user/auth/id/request');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization' : 'Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ',
    'Content-Type' : 'application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
       "requestType" : "USER_PERSONAL",
       "triggerType" : "APP_SCHEME",
       "userName" : "v1$255f8cc3-7d1d-4667-b28b-03f44e09483f$ZUyjGpmb/nL9W7//N1/VUN/F/947biU+1w==",
       "userPhone" : "v1$255f8cc3-7d1d-4667-b28b-03f44e09483f$v8QTxScwJ/NBA+Gp/TXerMWQp9BrQ45M7xaC",
       "userBirthday" : "v1$255f8cc3-7d1d-4667-b28b-03f44e09483f$vswaxSEyJf/J7Qndq2E7iOPJOmIWILby",
       "sessionKey" : "v1$255f8cc3-7d1d-4667-b28b-03f44e09483f$MdeifC7fngWC9qn/qia1Itp6jYulvhTH1JCln0oYp3xg95VpnqN5O5isZ58ZYD1WM03YooETiwQIjtLEMl2HSjxwlXZQ2yoyd/zH3mgCzlVDd/nOO0AI04Rzo/M7mvdfoN/k+DUBAeQ4NBIC9uqMt0JrkpuGvv3O1faYPBCV6OCMIcAOAbQb9fJx1bWFRLMkhd3meTD9wt2px46Kz7kW/FZXefMJr4qdnJEX9pZKz2QMJCMEnu0aW+AkJQUS5VfPSohrFTS8VeWoiNArFSESIxZhX3A+duAIJrYxTvXvOCM9ntO9xIMwTd+hp9L1UAYFOrqh6J2gmN1nI5ScBvtkLwRMFQ1D/eoSL/HD7Xb9cBAxMxPX4dn0OjLkUuO0y+KW4s+Prj9IYesDEkXUQpuQKz+4mLfX88lyplJ7o2x3uoecFlIBT92oY6BI+yxTATnwSIK249OwX2vuG6HLSOXlI3RScHjEDtzz1zPK6kjCGkFBM+5+gMyTIF4C130Uk4rlXpxYOGwPoBKBD2buGbBh7AHIaFgHlYjShdPiHMCF0ZDQnOubk139cRzoCVkKqdpPgVqIy8q6982UXzeoSIxqpSauqaL0IK2PPbMy3s9WH12NrDFDkg4NLAhnEgGNfOPjMl9lRMW+i4cCw0jhaCx1bu5GTEQzDCpc0DFT+/KPkKc="
       }');
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$response = curl_exec($ch);

curl_close($ch);
```

:::

### 응답 예시

**성공 응답**

| 이름 | 타입 | 설명 |
| --- | --- | --- |
| resultType | string | 요청 결과 (성공 : `SUCCESS`, 실패 : `FAIL`) |
| success.txId | string | 인증 요청 트랜잭션 아이디로 거래를 고유할 수 있는 값. 특정 거래를 고유할 수 있는 값이므로 반드시 저장 관리해야 합니다. |
| success.requestedDt | string | 최초 요청 시각(`YYYY-MM-DDThh:mm:ss±hh:mm`) |
| success.appScheme | string | 토스 인증 화면을 띄울 수 있는 앱 스킴 정보  |
| success.androidAppUri | string | 안드로이드 인증 앱 스킴 값으로 appScheme과 같은 역할을 하지만, Chrome Intent를 사용하기 때문에 고객사의 추가 기능 구현없이 토스 앱 설치 유무를 판별할 수 있는 장점이 있습니다.  |
| success.iosAppUri | string |  iOS 인증 앱 스킴 값으로 appScheme과 같은 역할을 하지만, Universal Link를 사용하기 때문에 안드로이드와 마찬가지로 고객사의 추가 기능 구현 없이 토스 앱 설치 유무를 판별할 수 있는 장점이 있습니다.|

```json
{
    "resultType": "SUCCESS",
    "success": {
        "txId": "d7b7273b-407b-46be-a9d8-97d2e895b009",
        "appScheme": "null",
        "androidAppUri": "null",
        "iosAppUri": "null",
        "requestedDt": "2022-02-13T17:52:22+09:00"
    }
}
```

**실패 응답**

| 이름 | 타입 | 설명 |
| --- | --- | --- |
| resultType | string | 실패 시 `FAIL` |
| error.errorType | number | 에러 유형 |
| error.errorCode | string | 에러 코드(예: `CE1000`) |
| error.reason | string | 에러 메시지 |
| error.data | object | 부가 데이터(있을 경우) |
| error.title | string | null | 에러 제목(있을 경우) |

```json
{
  "resultType": "FAIL",
  "error": {
    "errorType": 0,
    "errorCode": "CE1000",
    "reason": "토큰이 유효하지 않습니다.",
    "data": {},
    "title": null
  },
  "success": null
}

```

> 응답의 txId를 사용해 [appsInTossSignTossCert](/bedrock/reference/framework/인증/tosscertRequest.html) 함수를 호출하면 토스앱 인증 화면이 실행됩니다.\
> [인증 화면 호출하기](/tossauth/develop.html#_3-인증-화면-호출하기) 를 참고해주세요

## 2-2. 원터치 인증

클라이언트에서 **개인정보 입력 없이** 토스앱을 호출해 **한 번에 인증을 완료**해요.

| 이름            | 타입     | 필수 | 설명                      |
| ------------- | ------ | -- | ----------------------- |
| Authorization | string | Y  | `Bearer {Access Token}` |
| Content-Type  | string | Y  | `application/json`      |

| 이름          | 타입     | 필수 | 설명                     |
| ----------- | ------ | -- | ---------------------- |
| requestType | string | Y  | `"USER_NONE"`          |
| requestUrl  | string | Y  | 인증 완료 후 돌아올 앱스킴   |

### 요청 예시

::: code-group

```bash [Shell(curl)]
curl --location --request POST 'https://cert.toss.im/api/v2/sign/user/auth/id/request' --header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' --header 'Content-Type: application/json' # 세션 키는 매 요청 시 새로 생성해야 합니다.
--data-raw '{
       "requestType" : "USER_NONE",
       "requestUrl" : "intoss://my-granite-app",
    }'
```

```java
URL url = new URL("https://cert.toss.im/api/v2/sign/user/auth/id/request");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST");
httpConn.setRequestProperty("Authorization", "Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ");
httpConn.setRequestProperty("Content-Type", "application/json");
// 세션 키는 매 요청 시 새로 생성해야 합니다.
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("{" +
        "\"requestType\" : \"USER_NONE\"," +
        "}");
writer.flush();
writer.close();
httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() == 200
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
```

```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://cert.toss.im/api/v2/sign/user/auth/id/request');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ',
    'Content-Type: application/json',
]);


curl_setopt($ch, CURLOPT_POSTFIELDS, '{
    "requestType": "USER_NONE",
    "requestUrl": "intoss://my-granite-app"
}');

curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$response = curl_exec($ch);

curl_close($ch);
```

:::

### 응답 예시

**성공 응답**

| 이름 | 타입 | 설명 |
| --- | --- | --- |
| resultType | string | 요청 결과 (성공 : `SUCCESS`, 실패 : `FAIL`) |
| success.txId | string | 인증 요청 트랜잭션 아이디로 거래를 고유할 수 있는 값. 특정 거래를 고유할 수 있는 값이므로 반드시 저장 관리해야 합니다. |
| success.requestedDt | string | 최초 요청 시각(`YYYY-MM-DDThh:mm:ss±hh:mm`) |

```json
{
    "resultType": "SUCCESS",
    "success": {
        "txId": "d7b7273b-407b-46be-a9d8-97d2e895b009",
        "requestedDt": "2022-02-13T17:52:22+09:00"
    }
}
```

**실패 응답**

| 이름 | 타입 | 설명 |
| --- | --- | --- |
| resultType | string | 실패 시 `FAIL` |
| error.errorType | number | 에러 유형 |
| error.errorCode | string | 에러 코드(예: `CE1000`) |
| error.reason | string | 에러 메시지 |
| error.data | object | 부가 데이터(있을 경우) |
| error.title | string | null | 에러 제목(있을 경우) |

```json
{
  "resultType": "FAIL",
  "error": {
    "errorType": 0,
    "errorCode": "CE1000",
    "reason": "토큰이 유효하지 않습니다.",
    "data": {},
    "title": null
  },
  "success": null
}

```

> 응답의 txId를 사용해 [appsInTossSignTossCert](/bedrock/reference/framework/인증/tosscertRequest.html) 함수를 호출하면 토스앱 인증 화면이 실행됩니다.\
> [인증 화면 호출하기](/tossauth/develop.html#_3-인증-화면-호출하기) 를 참고해주세요

## 3. 인증 화면 호출하기

**SDK를 통해 연동해주세요.**

응답에서 받은 `txId`를 사용해 `appsInTossSignTossCert` 함수를 호출하면, 토스앱 인증 화면이 실행돼요.
[appsInTossSignTossCert](/bedrock/reference/framework/인증/tosscertRequest.md)를 확인해 주세요.

::: tip 토스앱 최소 버전을 확인하세요

* 토스 인증(requestType: USER\_PERSONAL): 토스앱 5.233.0 이상
* 토스 원터치 인증(requestType: USER\_NONE): 토스앱 5.236.0 이상

[getTossAppVersion](/bedrock/reference/framework/환경%20확인/getTossAppVersion) 함수를 사용하여 토스앱 버전을 체크해보세요.
:::

## 4. 본인확인 상태 조회하기

사용자의 현재 인증 **진행 상태**를 조회해요.\
`txId`를 사용해 현재의 인증 단계 (`REQUESTED`, `IN_PROGRESS`, `COMPLETED`, `EXPIRED`)를 확인할 수 있어요.

::: tip 주의하세요
상태조회 API는 **진행 상태 확인용**이에요.\
최종 인증 성공 여부는 **결과조회 API**로 판별해야 해요.
:::

* BaseURL : `https://cert.toss.im`
* Endpoint : `/api/v2/sign/user/auth/id/status`
* Method : `POST`
* Content-type : `application/json`

**요청 헤더**

| 이름 | 타입 | 필수값 여부 | 설명 |
|---|---|---|---|
| Authorization | string | Y | `Bearer {Access Token}` |
| Content-Type | string | Y | `application/json` |

**요청 파라미터**

| 이름 | 타입 | 필수값 여부 | 설명 |
|---|---|---|---|
| txId | string | Y | 상태 확인이 필요한 인증 요청 트랜잭션 아이디 |

**요청 예시**

:::code-group

```bash [Shell(curl)]
curl --location --request POST 'https://cert.toss.im/api/v2/sign/user/auth/id/status' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' \
--header 'Content-Type: application/json' \
--data-raw '{
      "txId": "633f3e1b-1a11-4e7c-9b35-dd391f440be4"
    }'
```

```java
URL url = new URL("https://cert.toss.im/api/v2/sign/user/auth/id/status");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST"); 

httpConn.setRequestProperty("Authorization", "Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ");
httpConn.setRequestProperty("Content-Type", "application/json");
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("{\"txId\": \"633f3e1b-1a11-4e7c-9b35-dd391f440be4\"}");
writer.flush();
writer.close(); 

httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() == 200
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
```

```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://cert.toss.im/api/v2/sign/user/auth/id/status');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization' : 'Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ',
    'Content-Type' : 'application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"txId": "633f3e1b-1a11-4e7c-9b35-dd391f440be4"}');
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$response = curl_exec($ch);

curl_close($ch);
```

:::

**성공 응답**

| 이름 | 타입 | 설명 |
|---|---|---|
| resultType | string | 요청 결과. 성공 시 `SUCCESS` |
| success.txId | string | 조회한 인증 트랜잭션 ID |
| success.status | string | 인증 진행 상태 (아래 “status 값” 표 참고) |
| success.requestedDt | string | 최초 인증 요청 시각 (`YYYY-MM-DDThh:mm:ss±hh:mm`, ISO 8601) |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "633f3e1b-1a11-4e7c-9b35-dd391f440be4",
    "status": "REQUESTED",
    "requestedDt": "2022-02-13T18:00:26+09:00"
  }
}
```

**실패 응답**

| 이름 | 타입 | 설명 |
|---|---|---|
| resultType | string | 실패 시 `FAIL` |
| error.errorType | number | 에러 유형 |
| error.errorCode | string | 에러 코드(예: `CE3100`) |
| error.reason | string | 에러 메시지 |
| error.data | object | 부가 데이터(있을 경우) |
| error.title | string | null | 에러 제목(있을 경우) |

```json
{
  "resultType": "FAIL",
  "error": {
    "errorType": 0,
    "errorCode": "CE3100",
    "reason": "존재하지 않는 요청입니다",
    "data": {},
    "title": null
  },
  "success": null
}
```

**status 값**

| 값 | 설명 |
|---|---|
| REQUESTED | 토스 인증서버에서 사용자의 토스 앱으로 인증이 요청된 상태 |
| IN\_PROGRESS | 사용자가 인증을 진행 중인 상태 |
| COMPLETED | 고객이 인증을 완료한 상태 *(최종 확정은 결과조회 API로 판단 해야해요)* |
| EXPIRED | 유효시간 만료로 인증 진행이 불가한 상태 |

## 5. 본인확인 결과 조회하기

인증이 완료된 사용자의 **결과 정보**를 조회해요.\
조회는 반드시 **서버-서버 통신**으로 진행해 주세요.\
본인확인 결과로 수집한 정보는 서버에 안전하게 저장하고, 이후 전자서명/간편인증 시 해당 정보와 비교·검증 해 주세요.

:::tip 주의하세요
결과조회 API는 성공 기준으로 **최대 2회**까지만 조회가 가능해요.\
사용자 인증을 끝마친 후 **60분(1시간) 이내** 결과 조회를 끝내야 해요.\
60분을 초과하면 결과 조회가 제한되며 인증 요청 API부터 다시 시작해야 해요.
:::

* BaseURL : `https://cert.toss.im`
* Endpoint : `/api/v2/sign/user/auth/id/result`
* Method : `POST`
* Content-type : `application/json`

**요청 헤더**

| 이름 | 타입 | 필수값 여부 | 설명 |
|---|---|---|---|
| Authorization | string | Y | `Bearer {Access Token}` |
| Content-Type | string | Y | `application/json` |

**요청 파라미터**

| 이름 | 타입 | 필수값 여부 | 설명 |
|---|---|---|---|
| txId | string | Y | 결과 확인이 필요한 인증 요청 트랜잭션 아이디 |
| sessionKey | string | Y | 결과조회에서는 인증수단과 무관하게 `txId`와 함께 필수로 전달. 요청/응답 AES 암·복호화용 세션 키로, 매 요청마다 새로 생성하고 인증요청에서 사용한 세션키는 재사용 금지 [(생성 방법)](/bedrock/reference/framework/인증/tosscertSessionKey.html)|

**요청 예시**
:::code-group

```bash [Shell(curl)]
curl --location --request POST 'https://cert.toss.im/api/v2/sign/user/auth/id/result' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' \
--header 'Content-Type: application/json' \
# 세션 키는 매 요청 시 새로 생성해야 합니다.
--data-raw '{
       "txId" : "c1ce9214-9878-4751-b433-0c96641b0e13",
       "sessionKey" : "v1$71c3d6cd-6a74-48a8-8ab2-b48e6133ae6f$Q0U7Bdg4dWd0XXucjsM/mda89bFU7eHnoUhgQ3k+cGQ9gv37jvWC+8isrkO2CR4+qgoPg+U+K7/tQH2m+uU7L8Ab0gzbQo6ASX39NpcP6RHpI+VBi323ssYnBmJL7n0z4aNm6raUEsMoNwrOaMDe0DqfalgOeZgZUztWew1pfZul2Q3/WIBMdp+npS4sFnBRoBrzLroVsuNRTLK0XT6m5hak+ys+vBg5vZFoI0JN7j7zsr8lqGi6piSkygl1PLPugnSC9cOezxMoVN5c/csEVQxMsfkwqTIASaZVECnP50dO70TydYhBFCqxw3DpEDBHcXNDucOtdVOPslCPNx3NZv1i0IH0r92ULb3w2Y0Fncy4/xL1dPSS+TbA5540u2Wb3cxqVNHib7WwSMHBwQtXAnFSFZmcvQQPXtTeQ7SCvNnhA8k3gbboSpbDBg60RWn/1zF/ogBYRldO1BFtq7KP+jOm6I2OSSVpagH1Wu5MXhEtiTmsx7M8j/IM8EfnXbD9axJnlW2fKHZVvAj+5KNhqy90PUimBCKiXqjvUwOqb9hGGEzJ4JVKbIIiy1EYOaRkPTK9GurZwQaqM4o4c8pzOYRQR/3XIPWHxLv/jwsaMcfUIQFyKE+w898g+l1zO0jcck59/R64kZcirT9AsGFnRUWrsHGIkM95jdYlpUsnCXw="
  }'
```

```java
URL url = new URL("https://cert.toss.im/api/v2/sign/user/auth/id/result");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST"); 

httpConn.setRequestProperty("Authorization", "Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ");
httpConn.setRequestProperty("Content-Type", "application/json"); 

// 세션 키는 매 요청 시 새로 생성해야 합니다.
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("{" +
        "\"txId\" : \"c1ce9214-9878-4751-b433-0c96641b0e13\"," +
        "\"sessionKey\" : \"v1$71c3d6cd-6a74-48a8-8ab2-b48e6133ae6f$Q0U7Bdg4dWd0XXucjsM/mda89bFU7eHnoUhgQ3k+cGQ9gv37jvWC+8isrkO2CR4+qgoPg+U+K7/tQH2m+uU7L8Ab0gzbQo6ASX39NpcP6RHpI+VBi323ssYnBmJL7n0z4aNm6raUEsMoNwrOaMDe0DqfalgOeZgZUztWew1pfZul2Q3/WIBMdp+npS4sFnBRoBrzLroVsuNRTLK0XT6m5hak+ys+vBg5vZFoI0JN7j7zsr8lqGi6piSkygl1PLPugnSC9cOezxMoVN5c/csEVQxMsfkwqTIASaZVECnP50dO70TydYhBFCqxw3DpEDBHcXNDucOtdVOPslCPNx3NZv1i0IH0r92ULb3w2Y0Fncy4/xL1dPSS+TbA5540u2Wb3cxqVNHib7WwSMHBwQtXAnFSFZmcvQQPXtTeQ7SCvNnhA8k3gbboSpbDBg60RWn/1zF/ogBYRldO1BFtq7KP+jOm6I2OSSVpagH1Wu5MXhEtiTmsx7M8j/IM8EfnXbD9axJnlW2fKHZVvAj+5KNhqy90PUimBCKiXqjvUwOqb9hGGEzJ4JVKbIIiy1EYOaRkPTK9GurZwQaqM4o4c8pzOYRQR/3XIPWHxLv/jwsaMcfUIQFyKE+w898g+l1zO0jcck59/R64kZcirT9AsGFnRUWrsHGIkM95jdYlpUsnCXw=\"" +
        "}");
writer.flush();
writer.close(); 

httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() / 100 == 2
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
```

```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://cert.toss.im/api/v2/sign/user/auth/id/result');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization' : 'Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ',
    'Content-Type' : 'application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
       "txId" : "c1ce9214-9878-4751-b433-0c96641b0e13",
       "sessionKey" : "v1$71c3d6cd-6a74-48a8-8ab2-b48e6133ae6f$Q0U7Bdg4dWd0XXucjsM/mda89bFU7eHnoUhgQ3k+cGQ9gv37jvWC+8isrkO2CR4+qgoPg+U+K7/tQH2m+uU7L8Ab0gzbQo6ASX39NpcP6RHpI+VBi323ssYnBmJL7n0z4aNm6raUEsMoNwrOaMDe0DqfalgOeZgZUztWew1pfZul2Q3/WIBMdp+npS4sFnBRoBrzLroVsuNRTLK0XT6m5hak+ys+vBg5vZFoI0JN7j7zsr8lqGi6piSkygl1PLPugnSC9cOezxMoVN5c/csEVQxMsfkwqTIASaZVECnP50dO70TydYhBFCqxw3DpEDBHcXNDucOtdVOPslCPNx3NZv1i0IH0r92ULb3w2Y0Fncy4/xL1dPSS+TbA5540u2Wb3cxqVNHib7WwSMHBwQtXAnFSFZmcvQQPXtTeQ7SCvNnhA8k3gbboSpbDBg60RWn/1zF/ogBYRldO1BFtq7KP+jOm6I2OSSVpagH1Wu5MXhEtiTmsx7M8j/IM8EfnXbD9axJnlW2fKHZVvAj+5KNhqy90PUimBCKiXqjvUwOqb9hGGEzJ4JVKbIIiy1EYOaRkPTK9GurZwQaqM4o4c8pzOYRQR/3XIPWHxLv/jwsaMcfUIQFyKE+w898g+l1zO0jcck59/R64kZcirT9AsGFnRUWrsHGIkM95jdYlpUsnCXw="
       }');
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$response = curl_exec($ch);

curl_close($ch);
```

:::

**성공 응답**

| 이름 | 타입 | 설명 |
|---|---|---|
| resultType | string | 성공 시 `SUCCESS` |
| success.txId | string | 결과를 조회한 인증 트랜잭션 아이디 |
| success.status | string | `COMPLETED` *(결과 조회가 정상 처리된 상태)* |
| success.userIdentifier | string | null | 현재 버전 미사용 (`null`) |
| success.userCiToken | string | null | 현재 버전 미사용 (`null`) |
| success.signature | string | 사용자가 서명한 전자서명 값(**Base64 인코딩된 DER**). **txId와 함께 저장 관리 필수** |
| success.randomValue | string | null | 현재 버전 미사용 (`null`) |
| success.completedDt | string | 사용자 인증 완료 시각 (`YYYY-MM-DDThh:mm:ss±hh:mm`, ISO 8601) |
| success.requestedDt | string | 최초 인증 요청 시각 (`YYYY-MM-DDThh:mm:ss±hh:mm`, ISO 8601) |
| success.personalData | object | 인증에 사용된 **개인정보(암호화 값)**. 하위 필드 표 참고 |

**personalData(인증을 진행한 사용자 개인정보) Object**

| 이름 | 타입 | 설명 |
|---|---|---|
| ci | string | 암호화된 사용자의 CI |
| name | string | 암호화된 사용자의 이름 |
| birthday | string | 암호화된 생년월일 8자리 |
| gender | string | 암호화된 성별 정보 (`MALE` | `FEMALE`) |
| nationality | string | 암호화된 국적 (`LOCAL` | `FOREIGNER`) |
| ci2 | string | null | 예측 불가 상황에서 ci 유출 대응을 위한 임시 파라미터, `null` 고정 |
| di | string | 암호화된 사용자의 DI |
| ciUpdate | string | null | 예측 불가 상황에서 ci 유출 대응을 위한 임시 파라미터, `null` 고정 |
| ageGroup | string | 암호화된 성인여부 (`ADULT` | `MINOR`) |

```json
// 결과조회 응답에서는 인증을 호출하는 방식에 상관없이 동일한 바디 파라미터를 제공합니다.
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "c1ce9214-9878-4751-b433-0c96641b0e13",
    "status": "COMPLETED",
    "userIdentifier": null,
    "userCiToken": null,
    "signature": "MIIJCAYJKoZIhvcN...(생략)...ghkgBZQMEAgEFADCBwwYJKoZIhvcNAQcBoIG1BIGyeyJ0eElkIjoiZGU1ZjVkNDItNTA4Yi00Njg2LWJiYzAtNDczNmJmZWJhY2FkIiwicGFydG5lckNvZGUiOiJURVNUMSIsInNlcnZpY2VUeXBlIjoi6rCE7Y647J247KadIiwiaWRlbnRpZmllciI6bnVsbCwidXNlcklkZW50aWZpZXIiOm51bGwsInJlcXVlc3RUcyI6IjIwMjItMDQtMjJUMDE6MDU6NDIrMDk6MDAifaCCBiUwggYhMIIECaADAgECAgN2Xf8wDQYJKoZIhvcNAQELBQAwUTELMAkGA1UEBgwCS1IxGzAZBgNVBAoMElZpdmEgUmVwdWJsaWNhIEluYzESMBAGA1UECwwJVG9zcyBDZXJ0MREwDwYDVQQDDAhUb3NzIENBMTAeFw0yMjA0MTQwMjM0MTFaFw0yNTA0MTMxNDU5NTlaMHwxCzAJBgNVBAYTAktSMRswGQYDVQQKDBJWaXZhIFJlcHVibGljYSBJbmMxEjAQBgNVBAsMCVRvc3MgQ2VydDEoMCYGCgmSJomT8ixkAQEMGDcwMDI3MjMyMDIxMTEzMDgwMjAwOTk5MTESMBAGA1UEAwwJ6rmA7IiY67mIMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAljEvPPqzfLIkulmJJ45z+1jfron60TSXRx9KWeVXt41yU7qgoWQkrhOVd4g/AGwS2jxStjJ2TU7AFEaTMhA6KLkMhrsE3l48B//AaTh2UA0NEVwa+/C2Aw7qh5rg170yEe0sRVs5syH3R4bEiGia0CmSGSRnVIgNuazVf/EpHAvAvkEcknn6VjrivylLsHlq2UYTZw7t8Ijva51tiS660XUOfeamJniUfyqiYZZGtrOtF1FCuOldECGt3C6oJytmg4R4MIIfouEUfWEeiZKL1//AiQ2i1I0zJDKqH7eB54534yuJFtQs4ocIlNg/VMbJYWaOjRooTxRqabquNb41MQIDAQABo4IB1TCCAdEwfgYDVR0jBHcwdYAUIOEEYoA6EFhC3FSBskx+jPX3qh+hWqRYMFYxCzAJBgNVBAYMAktSMRswGQYDVQQKDBJWaXZhIFJlcHVibGljYSBJbmMxEjAQBgNVBAsMCVRvc3MgQ2VydDEWMBQGA1UEAwwNVG9zcyBSb290IENBMYIBAjAdBgNVHQ4EFgQUzGBp9tdMgfWMqyYxYqNQ9CaPHkIwDgYDVR0PAQH/BAQDAgbAMIGLBgNVHSABAf8EgYAwfjB8BgsqgxqMmyIFAQEBAzBtMCsGCCsGAQUFBwIBFh9odHRwOi8vY2EuY2VydC50b3NzLmltL2Nwcy5odG1sMD4GCCsGAQUFBwICMDIeMABUAGgAaQBzACAAaQBzACAAVABvAHMAcwAgAGMAZQByAHQAaQBmAGkAYwBhAHQAZTBbBgNVHR8EVDBSMFCgTqBMhkpodHRwOi8vY2EuY2VydC50b3NzLmltL2NybC90b3NzX2NybF9kcDJwMjU4Ni5jcmw/Y2VydGlmaWNhdGVSZXZvY2F0aW9uTGlzdDA1BggrBgEFBQcBAQQpMCcwJQYIKwYBBQUHMAGGGWh0dHA6Ly9vY3NwLmNlcnQudG9zcy5pbS8wDQYJKoZIhvcNAQELBQADggIBABgt3/wzvsAMXX9JJK1JJbgXO5Ft5TdoJEdJXwdjIVrSDg62vreg9K3sR7pAz7Zw3/IUabWrChMnIfD8fmbVB1vB0vX+S9HcvIkNhhM5m3rQUnEMpsO+oK73IZ7E9IHKfYUy0QrrjVwqQakKI5Zc6YfLd9oCWSWh25oGwUgo524gkC86xYG2CLGpP4bDLEIZQe5+Dg+2v6KWuouDI/SnYkAXU+Qi0+YYGR3w3d2Qp5yqZ/D5hcR2aOEFDfl31NwVVeJ1lCHE+bhhqoxZzfUDl+2X1jHdIRyZ+kYARJg5VI+if9OhtT+pI1d55EGCkgi+xRlp03mCLHFr4a5KjZG4+5ds+73s2dUasAeiaZ6XmisfjtR1Gs5eV4wgtBJ12+faBxXIPhhDvZaO5Ag7ehMAyrn8VwgQAC5WMnsMqRx4t1AwInU9NgMRhKxjxrBxhWzjVBmBjeD891OHQO4pFF6QC5SzFj4ud/sX2XkB2iKj8aJUDeBN5H03FDmd0v6li3OZ2L2O5vcFVKK62EJazk7okXDTfiSf8lJa35lZPR170LqDSNOtp5u/HkdYPFZzEt0ROn5x3drEMSvrLtzCmEfgAj5NHKZfmj2VrXvRXALXXhENQLOqsWxbMrX19VyaXeUdz2+EHPwYybiRvqpqw5ZXx67HJtRRFIIBfSUjzGAnk8GIMYIB7jCCAeoCAQEwWDBRMQswCQYDVQQGDAJLUjEbMBkGA1UECgwSVml2YSBSZXB1YmxpY2EgSW5jMRIwEAYDVQQLDAlUb3NzIENlcnQxETAPBgNVBAMMCFRvc3MgQ0ExAgN2Xf8wDQYJYIZIAWUDBAIBBQCgaTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMjA0MjExNjA1NTNaMC8GCSqGSIb3DQEJBDEiBCDFQjwDSF7RJrV5Cg3x6GlErYK7YwZV5b23yGTMuMKgXjANBgkqhkiG9w0BAQEFAASCAQBAcLs7q9Uy4Krsx8ynUgy5zyV1+QD4Er9uxpxfLuSXFw3kSbHdmQxekFN5G1aJSpQQtLHM0WhPpVZ/PnRxa2dBxt4gmIiAygjo9jsOsuU9xwbfxgIihD57Kf8H2zcPLUglDCoKP4k2c5o0GfzoOFvU31KPvWJDxPM/55TcmrJCwTWDEs76PviQcjq9IqYFxrm5jUhznCNnbew/xrGTvCNPQhge5/rapMh7UYPbsxXWaj29zC/jnDJXsiteFA6bbaFSrPJNMQHV+czza6jzS+XhaRPohmisszZ8YGbqPLvI0zmnMzIv947L3bknwPtgY5wEYg+cKPZ6SxJxpJW0DPs/",
    "randomValue": null,
    "completedDt": "2022-02-13T18:01:53+09:00",
    "requestedDt": "2022-02-13T18:00:26+09:00",
    "personalData": {
      "ci": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$X3g52aAyCBirz0UVp1oNRq0SfGtj66vGtUT3rp1aSdm1h//xmpm7vdf48fbGI2i7VTBj6TKG2rqanP6Yo9MiTQu63C8kLWayzWAMp+RLyXLovvnFb9SxxdblRtZbj5KRNlBWK9t2VXI=",
      "name": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$9oiJBRei1KI/SgXtXGmkfNHu+pdAUHXBxA==",
      "birthday": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$LQgw26ExChwWi8cQQz6GrdMAdMZGyaEI",
      "gender": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$WnREqd1HM/Ci7p+3KIqROusVkYeSAQ==",
      "nationality": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$UH5Kqd3dPV1daxw0i23eMWjeXcXC",
      "ci2": null,
      "di": "v1$2e161d9d-e620-443e-9a27-8db41cc96cf9$6GKr2zaUWWfI6rpJ6/AV9U4W0S4nhAMFIFLkt5CS6N8Gjb1Oc/dpitkMSSvLroDO5b6zdl9bufGSQ6SiVQdlYN2OWYFBr/Hb4e4AYwQpFxDbpi9ksYt52aFa3G2DwaNOQMUBkyQ1IWc=",
      "ciUpdate": null
    }
  }
}

```

**실패 응답**

| 이름 | 타입 | 설명 |
|---|---|---|
| resultType | string | 실패 시 `FAIL` |
| error.errorType | number | 에러 유형 |
| error.errorCode | string | 에러 코드(예: `CE3102`) |
| error.reason | string | 에러 메시지 |
| error.data | object | 부가 데이터(있을 경우) |
| error.title | string | null | 에러 제목(있을 경우) |

```json
{
  "resultType": "FAIL",
  "error": {
    "errorType": 0,
    "errorCode": "CE3102",
    "reason": "요청이 아직 완료되지 않았습니다.",
    "data": {},
    "title": null
  },
  "success": null
}

```

---

---
url: 'https://developers-apps-in-toss.toss.im/tosspay/develop.md'
description: '토스페이 개발 가이드입니다. SDK 연동, API 사용법, 구현 예제를 확인하세요.'
---

# 개발하기

![](/assets/pay_flow.tHujBJQR.png)

::: tip BaseURL
`https://pay-apps-in-toss-api.toss.im`
:::

## 1. 결제 생성하기

결제 건을 생성합니다.

* Content-type : application/json
* Method : `POST`
* URL : `/api-partner/v1/apps-in-toss/pay/make-payment`

**요청 헤더**\
| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string | Y | 토스 로그인을 통해 획득한 userKey 값 |

**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| orderNo | String | Y | **가맹점의 주문번호**  주문번호는 반드시 가맹점별로 매회 유니크해야 하며, 중복될 경우 결제 생성 요청이 실패합니다.  - ‘숫자, 영문자, 특수문자 `_-:.^@’` 만 사용 가능하며, 50자 이내여야 합니다.  - 동일 주문번호는 구매자 인증 완료 이후 절대 재사용이 불가합니다.  - 최초 생성 후 2년이 지난 주문번호는 재사용할 수 없습니다.  - 테스트 환경과 라이브 환경 간의 주문번호 충돌 방지를 위해 가맹점 관리가 필요합니다. |
| productDesc | String | Y | **상품 설명**  상품 설명은 공백으로만 설정할 수 없고, 백슬래시 `\` 와 따옴표 `,`를 포함할 수 없으며 총 255자 이내여야 합니다. 이 값에 한글이 포함되었다면 인코딩에 유의해주세요.  토스 인코딩 방식은 UTF-8 형식을 사용합니다. |
| amount | Integer | Y | **총 결제 금액**  금액과 관련된 모든 파라미터는 숫자 형태로 보내주셔야 에러가 발생하지 않습니다. |
| amountTaxFree | Integer | Y | **결제 금액 중 비과세 금액**  판매하시는 상품이 과세 품목이면 해당 값을 0으로 보내주세요.  비과세액은 필수값이니 빈 값으로 보내주시는 경우 에러가 발생합니다. |
| amountTaxable | Integer | N | **결제 금액 중 과세 금액**  별도의 과세액을 설정하지 않고, 비과세 금액을 0원으로 보내주시면 토스페이 서버에서 자동으로 과세와 부가세를 계산합니다. |
| amountVat | Integer | N | **결제 금액 중 부가세**  값이 없으면 환불할 과세 금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다. |
| amountServiceFee | Integer | N | **결제 금액 중 봉사료**  봉사료 금액입니다. |
| enablePayMethods | String | N | **결제수단 구분 변수**  가맹점 필요에 따라 결제창에 노출하는 결제수단을 제어할 수 있습니다.  - TOSS\_MONEY : 결제수단 중 토스머니만 노출  - CARD : 결제수단 중 카드만 노출  - null 또는 그 외의 값 : 상점에 설정된 기본 결제수단으로 노출 |
| cashReceipt | boolean | N | **현금영수증 발급 가능 여부**  현금영수증 기능을 활용하시는 경우 true, 미사용의 경우 false 로 선언해 주시기 바랍니다.  반드시 true 또는 false 값을 전달해 주셔야 하고, null 과 같은 비정상 값을 전달할 경우 해당 필드는 명시적으로 false 로 처리됩니다. |
| cashReceiptTradeOption | String | N | **현금영수증 발급 타입**  - GENERAL : 일반(기본 값)  - CULTURE : 문화비  - PUBLIC\_TP : 교통비 |
| installment | String | N | **할부 제한 타입**  신용카드 결제 시, 사용자의 할부 선택을 제한할 수 있습니다.  - USE : 할부 사용 (기본값)  - NOT\_USE : 할부 미사용 |
| isTestPayment | boolean | Y | 샌드박스 결제 요청이면 true, 라이브앱 결제 요청이면 false |

```
curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/pay/make-payment' \
--header 'Content-Type: application/json' \
--header 'x-toss-user-key : 1234' \
--data '{
    "orderNo":"test-20250417-3",
    "productDesc":"test02",
    "amount":10,
    "amountTaxFree":0,
    "isTestPayment":true
}'
```

**응답 파라미터**
| 이름 | 타입 | 설명 |
| --- | --- | --- |
| payToken | String | **토스페이 토큰**  매회 유니크한 토큰 값이 생성됩니다.  가맹점에서는 이 값을 반드시 저장하고 관리하셔야 합니다. |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "payToken": "string"
  }
}
```

## 2. 결제 인증하기

**SDK를 통해 연동해주세요.**

토스페이 결제창을 띄우고, 사용자 인증을 수행해요.\
인증이 완료되면 성공 여부를 반환해요.

checkoutPayment 함수는 결제창을 통해 사용자 인증만 해요.\
실제 결제 처리는 인증 성공 후 서버에서 별도로 해야 해요.\
[checkoutPayment](/bedrock/reference/framework/토스페이/checkoutPayment.md)를 참고해 주세요.

## 3. 결제 실행하기

구매자가 결제를 시도하면, 먼저 결제 정보를 생성하고 인증을 받아요.\
이때 결제 상태는 '대기' 중이에요. 이후 결제를 실제로 승인하려면 주어진 주문번호와 결제 토큰을 사용해서 이 함수로 생성된 결제를 승인해요.\
실제 승인이 완료되면, 구매자의 결제 수단(예: 카드, 계좌)에서 실제로 금액이 출금돼요.

* Content-type : application/json
* Method : `POST`
* URL : `/api-partner/v1/apps-in-toss/pay/execute-payment`

**요청 헤더**\
| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string | Y | 토스 로그인을 통해 획득한 userKey 값 |

**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| payToken | String | Y | 토스페이 토큰 |
| orderNo | String | N | 가맹점 주문번호 |
| isTestPayment | boolean | Y | payToken 이 샌드박스에서 발급된 것이면 true, 라이브앱에서 발급된 것이면 false |

```
curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/pay/execute-payment' \
--header 'Content-Type: application/json' \
--header 'x-toss-user-key : 1234' \
--data '{
    "payToken":"test-20250417-3",
    "orderNo":"test02",
    "isTestPayment":true
}'
```

**응답**
| 이름 | 타입 | 설명 |
| --- | --- | --- |
| mode | String | **결제환경**  - LIVE : 실거래용  - TEST : 테스트용 |
| orderNo | String | **승인된 상품 주문번호** |
| amount | Integer | **상품금액** |
| approvalTime | String | **결제건의 승인 처리 시간**  결제건의 승인 처리 시간 (yyyy-MM-dd HH:mm:ss)  요청에 따른 결제건 처리 시간입니다. 환불 시에도 동일한 변수로 리턴되므로 구분하여 관리하시기 바랍니다. |
| stateMsg | String | **상태 응답 텍스트 값**  정상 응답일 경우 “결제 완료” 로 내려감 |
| discountedAmount | Integer | **할인된 금액**  할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다.  할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. 결제 상점에 따라 할인조건은 차이가 있을 수 있습니다. |
| paidAmount | Integer | **지불수단 승인금액**  총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다. |
| payMethod | String | **결제수단**  - TOSS\_MONEY : 토스머니  - CARD : 카드 |
| payToken | String | **토스페이 토큰**  매회 유니크한 토큰 값이 생성됩니다.  가맹점에서는 이 값을 반드시 저장하고 관리하셔야 합니다. |
| transactionId | String | **거래 트랜잭션 아이디**  결제의 거래구분을 위하여 토스 서버에서 유니크한 값을 생성해서 전달드립니다.  매출전표를 호출하거나 환불 진행 시 구분 값으로 활용할 수 있습니다. |
| cardCompanyCode | String | **승인 카드사 코드** |
| cardCompanyName | String | **승인 카드사명** |
| cardAuthorizationNo | String | **구매자가 확인할 수 있는 카드사 승인번호**  정상적인 카드사 승인번호는 라이브 키 결제에서 확인하실 수 있습니다. |
| spreadOut | String | **사용자가 선택한 카드 할부개월**  5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다. |
| noInterest | String | **카드 무이자 적용 여부**  - ture : 무이자  - false : 일반 |
| salesCheckLinkUrl | String | **신용카드 매출전표 호출 URL**  승인된 카드 결제건의 매출전표를 확인할 수 있는 URL 입니다.  구매자의 추가인증 완료 후 거래내역을 확인할 수 있습니다. |
| cardMethodType | String | **카드 타입**  승인된 카드의 타입을 구분할 수 있습니다. 예를 들어, 상점의 신용카드 결제 비율을 알고 싶다면 이 값을 활용해주세요.  - CREDIT : 신용카드  - CHECK : 체크카드  - PREPAYMENT : 선불카드 |
| cardNumber | String | **마스킹된 카드번호**  카드번호 16자리 중 중간자리는 마스킹됩니다. |
| cardUserType | String | **카드 사용자 구분**  - PERSONAL : 본인카드  - PERSONAL\_FAMILY : 가족카드  - CORP\_PERSONAL : 법인지정 결제계좌 임직원  - CORP\_PRIVATE : 법인 공용  - CORP\_COMPANY : 법인지정 결제계좌 회사 (하나카드만) |
| cardNum4Print | String | **사용자가 선택한 카드의 끝 4자리**  사용자가 선택한 결제수단( `payMethod`)이 ‘카드’ 인 경우 카드번호 끝 4자리를 전달합니다. (카드사에 따라 마스킹이 포함되어 있을 수 있습니다) |
| cardBinNumber | String | **카드 BIN 넘버**  카드사에서 준 카드 BIN 번호 (마스킹되어있을 수 있습니다)  100% 신뢰는 불가합니다. |
| cashReceiptMgtKey | String | **현금영수증 관리번호 식별값**  국세청 승인번호는 아니며 토스페이에서 자체적으로 만든 식별값입니다. 해당 필드 존재로 현금영수증 발급 구분 가능합니다. |
| accountBankCode | String | **은행 코드**  사용자가 선택한 결제수단( `payMethod`)이 ‘토스머니’인 경우 토스가 정의한 은행 코드를 전달합니다. |
| accountBankName | String | **은행 명** |
| accountNumber | String | **계좌번호**  계좌번호는 일부 마스킹을 포함하고 있습니다. |
| msg | String | 응답이 성공이 아닌 경우 설명 메시지 |
| errorCode | String | 에러 코드 |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "code": 0,
      "mode": "TEST",
      "orderNo": "20250417-2",
      "amount": 10,
      "approvalTime": "2025-04-17 12:32:10",
      "stateMsg": "결제 완료",
      "discountedAmount": 0,
      "paidAmount": 10,
      "payMethod": "TOSS_MONEY",
      "payToken": "O1NZck9XME8ureeVJVJP67",
      "transactionId": "45a77cf4-5577-4d5c-8827-4d4dd328bf12",
      "cardCompanyCode": null,
      "cardCompanyName": null,
      "cardAuthorizationNo": null,
      "spreadOut": null,
      "noInterest": null,
      "salesCheckLinkUrl": null,
      "cardMethodType": null,
      "cardNumber": null,
      "cardUserType": null,
      "cardNum4Print": null,
      "cardBinNumber": null,
      "cashReceiptMgtKey": null,
      "accountBankCode": "092",
      "accountBankName": "토스뱅크",
      "accountNumber": "100******094",
      "msg": null,
      "errorCode": null
  }
}
```

## 4. 결제 환불하기

결제 건을 구매자에게 돌려줍니다.

* Content-type : application/json
* Method : `POST`
* URL : `/api-partner/v1/apps-in-toss/pay/refund-payment`

**요청 헤더**\
| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string | Y | 토스 로그인을 통해 획득한 userKey 값 |

**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| payToken | String | Y | 토스페이 토큰 |
| reason | String | Y | 환불 사유  한글 및 숫자, 영문자, 특수문자 `_ - : . ^ @ ( ) [ ] # / ! % ? &` 만 허용합니다. |
| isTestPayment | boolean | Y | payToken 이 샌드박스에서 발급된 것이면 true, 라이브앱에서 발급된 것이면 false |

**응답**
| 이름 | 타입 | 설명 |
| --- | --- | --- |
| refundNo | String | 환불 번호 |
| approvalTime | String | 결제건의 환불 처리 시간 (yyyy-MM-dd HH:mm:ss) |
| cashReceiptMgtKey | String | 현금영수증 관리번호 식별 |
| refundableAmount | Integer | 환불 가능 금액 |
| discountedAmount | Integer | 할인된 금액 |
| paidAmount | Integer | 지불수단 승인금액 |
| refundedAmount | Integer | 환불요청 금액 |
| refundedDiscountAmount | Integer | 환불요청 금액 중 실 차감된 할인 금액 |
| refundedPaidAmount | Integer | 환불요청 금액 중 실 차감된 지불수단 금 |
| payToken | String | 환불된 결제토큰 |
| transactionId | String | 거래 트랜잭션 아이디 |
| cardMethodType | String | 카드 타입  - CREDIT : 신용카드  - CHECK : 체크카드  - PREPAYMENT : 선불카드 |
| cardNumber | String | 마스킹된 카드번호 |
| cardUserType | String | 카드 사용자 구분  - PERSONAL : 본인 카드  - PERSONAL\_FAMILY : 가족카드  - CORP\_PERSONAL : 법인지정 결제계좌 임직원  - CORP\_PRIVATE : 법인 공용  - CORP\_COMPANY : 법인지정 결제계좌 회사(하나카드만) |
| cardNum4Print | String | 사용자가 선택한 카드의 끝 4자리 |
| cardBinNumber | String | 카드 BIN 넘버 |
| accountBankCode | String | 은행코드  사용자가 선택한 결제수단(`payMethod`)이 '토스머니'인 경우 토스가 정의한 은행 코드를 전달합니다. |
| accountBankName | String | 은행 명 |
| accountNumber | String | 마스킹된 계좌번호 |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "refundNo": "string",
    "approvalTime": "string",
    "cashReceiptMgtKey": "string",
    "refundableAmount": 0,
    "discountedAmount": 0,
    "paidAmount": 0,
    "refundedAmount": 0,
    "refundedDiscountAmount": 0,
    "refundedPaidAmount": 0,
    "payToken": "string",
    "transactionId": "string",
    "cardMethodType": "string",
    "cardNumber": "string",
    "cardUserType": "string",
    "cardNum4Print": "string",
    "cardBinNumber": "string",
    "accountBankCode": "string",
    "accountBankName": "string",
    "accountNumber": "string"
  }
}
```

## 5. 결제 상태 조회하기

생성된 결제건의 거래 상태와 거래 트랜잭션을 조회할 수 있습니다.\
상황에 따라, 승인 혹은 환불 응답을 수신하지 못한 경우에도 활용 가능합니다.

* Content-type : application/json
* Method : `POST`
* URL : `/api-partner/v1/apps-in-toss/pay/get-payment-status`

**요청 헤더**\
| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| x-toss-user-key | string | Y | 토스 로그인을 통해 획득한 userKey 값 |

**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| payToken | String | Y | 토스페이 토큰 |
| orderNo | String | Y | 가맹점 주문번호 |
| isTestPayment | boolean | Y | payToken 이 샌드박스에서 발급된 것이면 true, 라이브앱에서 발급된 것이면 false |

**응답**
| 이름 | 타입 | 설명 |
| --- | --- | --- |
| mode | String | 결제환경  - LIVE : 실거래용  - TEST : 테스트용 |
| payToken | String | 토스페이 토큰 |
| orderNo | String | 토스페이와 연계된 상점 주문번호 |
| payStatus | String | 결제상태 |
| payMethod | String | 결제수단  - TOSS\_MONEY : 토스머니  - CARD : 카드 |
| amount | Integer | 가맹점이 토스로 전달한 결제 총 금액 |
| discountedAmount | Integer | 할인된 금액 |
| discountAmountV2 | Integer | 즉시 할인 적용 금액 |
| paidPointV2 | Integer | 토스 포인트 사용금액 |
| paidAmount | Integer | 지불수단 승인금액 |
| refundableAmount | Integer | 환불 가능 잔액 |
| amountTaxable | Integer | 총 결제 금액 중 적용된 과세 금액 |
| amountTaxFree | Integer | 총 결제 금액 중 적용된 비과세 금액 |
| amountVat | Integer | 총 결제 금액 중 적용된 부가세 금액 |
| amountServiceFee | Integer | 총 결제 금액 중 적용된 봉사료 |
| disposableCupDeposit | Integer | 일회용 컵 보증금 |
| accountBankCode | String | 은행코드 |
| accountBankName | String | 은행명 |
| accountNumber | String | 마스킹된 계좌번호 |
| card | Object | 카드 정보 |
| noInterest | Boolean | 카드 무이자 적용 여부  - true : 무이자  - false : 일반 |
| spreadOut | Integer | 사용자가 선택한 카드 할부개월 |
| cardAuthorizationNo | String | 구매자가 확인할 수 있는 카드사 승인번호 |
| cardMethodType | String | 카드 타입  - CREDIT : 신용카드  - CHECK : 체크카드  - PREPAYMENT : 선불카드 |
| cardUserType | String | 카드 사용자 구분  - PERSONAL : 본인 카드  - PERSONAL\_FAMILY : 가족카드  - CORP\_PERSONAL : 법인지정 결제계좌 임직원  - CORP\_PRIVATE : 법인 공용  - CORP\_COMPANY : 법인지정 결제계좌 회사(하나카드만) |
| cardNumber | String | 마스킹된 카드번호 |
| cardBinNumber | String | 카드 BIN 넘버 |
| cardNum4Print | String | 사용자가 선택한 카드의 끝 4자리 |
| salesCheckLinkUrl | String | 신용카드 매출전표 호출URL |
| cardCompanyName | String | 승인 카드사명 |
| cardCompanyCode | Integer | 카드사 코드 |
| transactions | list | 거래 트랜잭션 |
| stepType | String | 요청된 거래 타입  - PAY : 결제  - REFUND : 환불 |
| transactionId | String | 거래 트랜잭션 아이디  결제의 거래구분을 위하여 유니크한 값을 생성하여 전달드립니다.  거래 대사 시, 이 값을 활용하시길 권장드립니다. |
| paidAmount | Integer | 요청된 거래 타입(stepType) 중 적용된 지불수단 금액 |
| transactionAmount | Integer | 요청된 거래 타입(stepType)의 가맹점 전달금액  ’환불’ 요청의 경우 -(마이너스) 금액이 리턴됩니다. |
| discountedAmount | Integer | 요청된 거래 타입(stepType) 중 적용된 할인금액  할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. |
| pointAmount | Integer | 요청된 거래 타입(stepType) 중 포인트 금액 |
| regTs | String | 요청 처리 시간 |
| createdTs | String | 결제 생성 시간  사용자 최초 결제 요청 시간 |
| paidTs | String | 결제 완료 처리 시간 |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "mode": "string",
    "payToken": "string",
    "orderNo": "string",
    "payStatus": "string",
    "payMethod": "string",
    "amount": 0,
    "discountedAmount": 0,
    "discountAmountV2": 0,
    "paidPointV2": 0,
    "paidAmount": 0,
    "refundableAmount": 0,
    "amountTaxable": 0,
    "amountTaxFree": 0,
    "amountVat": 0,
    "amountServiceFee": 0,
    "disposableCupDeposit": 0,
    "accountBankCode": "string",
    "accountBankName": "string",
    "accountNumber": "string",
    "card": {
      "noInterest": true,
      "spreadOut": 0,
      "cardAuthorizationNo": "string",
      "cardMethodType": "string",
      "cardUserType": "string",
      "cardNumber": "string",
      "cardBinNumber": "string",
      "cardNum4Print": "string",
      "salesCheckLinkUrl": "string",
      "cardCompanyName": "string",
      "cardCompanyCode": 0
    },
    "transactions": [
      {
        "stepType": "string",
        "transactionId": "string",
        "paidAmount": 0,
        "transactionAmount": 0,
        "discountedAmount": 0,
        "pointAmount": 0,
        "regTs": "string"
      }
    ],
    "createdTs": "string",
    "paidTs": "string"
  }
}
```

## 6. 코드 정리

### 결제상태 리스트

| **값** | **설명** |
| --- | --- |
| PAY\_STANDBY | 결제 대기 중 |
| PAY\_APPROVED | 구매자 인증 완료 |
| PAY\_CANCEL | 결제 취소 |
| PAY\_PROGRESS | 결제 진행 중 |
| PAY\_COMPLETE | 결제 완료 |
| REFUND\_PROGRESS | 환불 진행 중 |
| REFUND\_SUCCESS | 환불 성공 |
| SETTLEMENT\_COMPLETE | 정산 완료 |
| SETTLEMENT\_REFUND\_COMPLETE | 환불 정산 완료 |

### 은행코드 리스트

토스머니 결제의 경우 사용자가 선택한 계좌의 정보를 함께 전달합니다.
| **은행 코드 (accountBankCode)** | **은행 명 (accountBankName)** |
| --- | --- |
| 002 | KDB산업은행 |
| 003 | IBK기업은행 |
| 004 | KB국민은행 |
| 005 | KEB하나은행 |
| 007 | 수협은행 |
| 011 | NH농협은행 |
| 020 | 우리은행 |
| 023 | SC은행 |
| 027 | 씨티은행 |
| 031 | 대구은행 |
| 032 | 부산은행 |
| 034 | 광주은행 |
| 035 | 제주은행 |
| 037 | 전북은행 |
| 039 | 경남은행 |
| 045 | MG새마을금고 |
| 048 | 신협 |
| 050 | 저축은행 |
| 064 | 산림조합 |
| 071 | 우체국 |
| 081 | 하나은행 |
| 088 | 신한은행 |
| 089 | 케이뱅크 |
| 090 | 카카오뱅크 |
| 092 | 토스뱅크 |
| 103 | SBI저축은행 |
| 218 | KB증권 |
| 230 | 미래에셋증권 |
| 238 | 미래에셋증권 |
| 240 | 삼성증권 |
| 243 | 한국투자증권 |
| 247 | NH투자증권 |
| 261 | 교보증권 |
| 262 | 하이투자증권 |
| 263 | 현대차투자증권 |
| 264 | 키움증권 |
| 265 | 이베스트증권 |
| 266 | SK증권 |
| 267 | 대신증권 |
| 269 | 한화투자증권 |
| 270 | 하나증권 |
| 271 | 토스증권 |
| 278 | 신한투자증권 |
| 279 | DB금융투자 |
| 280 | 유진투자 |
| 287 | 메리츠증권 |
| 888 | 토스머니 |
| 889 | 토스포인트 |

### 카드사코드 리스트

| **카드사 이름** | **카드(매입사) 코드** |
| --- | --- |
| 신한 | 1 |
| 현대 | 2 |
| 삼성 | 3 |
| 국민 | 4 |
| 롯데 | 5 |
| 하나 | 6 |
| 우리 | 7 |
| 농협 | 8 |
| 씨티(미지원) | 9 |
| 비씨(BC) | 10 |

### 에러 코드

| 값 | 설명 |
| --- | --- |
| PAYMENT\_EXISTING\_PAYMENT | 이미 존재하는 결제입니다. |
| COMMON\_INVALID\_API\_KEY | 바르지 않은 apiKey 입니다. |
| COMMON\_BREAK\_TIME\_OF\_BANK | 지금은 은행 점검 시간입니다. 점검이 끝난 후 사용해주세요. |
| [그 외의 에러코드](https://docs-pay.toss.im/guide/error-code) | |

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/시작하기/intro.md
description: 앱인토스 Granite에 대해 소개하고 있습니다.
---

# 개요

앱인토스 SDK는 **토스 앱 내에서 미니앱을 빠르게 구축하기 위한 WebView 및 React Native용 런타임 프레임워크**예요.\
SDK의 코어는 `Granite`이며, 앱 실행 환경과 통신을 담당하는 **공통 런타임 프레임워크**예요.

현재는 **WebView SDK**와 **React Native SDK** 두 가지 형태로 제공돼요.\
이 문서는 `Granite`의 `AppsInToss` 구성요소와, 네이티브에서 전달되는 초기 데이터(`InitialProps`)를 설명해요.

## 시그니처

### `AppsInToss`

```typescript
AppsInToss: {
    registerApp(
      AppContainer: ComponentType<PropsWithChildren<InitialProps>>,
      { appName, context, router }: BedrockProps
    ): (initialProps: InitialProps) => JSX.Element;
    readonly appName: string;
}
```

### `InitialProps`

```typescript
type InitialProps = AndroidInitialProps | IOSInitialProps;
```

## AppsInToss

`AppsInToss.registerApp`은 서비스의 기본 환경을 설정하고, 복잡한 초기 구성 없이 개발을 빠르게 시작하도록 도와줘요.\
**`appName`만 전달해도** 파일 기반 라우팅, 쿼리 파라미터 처리, 뒤로 가기, 화면 가시성 감지 등 핵심 기능을 즉시 사용할 수 있어요.

### 제공 기능

* **파일 기반 라우팅**: Next.js처럼 경로와 URL이 자동 매핑돼요.
  * `/my-service/pages/home.ts` → `intoss://my-service/home`
* **쿼리 파라미터 처리**: URL 스킴 파라미터(referrer 등)를 바로 사용 가능
* **뒤로 가기 제어**: 뒤로 가기 이벤트를 가로채 다이얼로그 표시나 화면 닫기 처리 가능
* **화면 가시성 감지**: 화면이 보이거나 가려지는 이벤트에 맞춰 동작 제어 가능

### 프로퍼티

### 예제: 앱 등록하기

```tsx
import { AppsInToss } from '@apps-in-toss/framework';
import { PropsWithChildren } from 'react';
import { InitialProps } from '@granite-js/react-native';
import { context } from '../require.context';

function AppContainer({ children }: PropsWithChildren<InitialProps>) {
  return <>{children}</>;
}

// 앱 이름과 context만 전달하면 기본 설정이 완료돼요.
export default AppsInToss.registerApp(AppContainer, { context });
```

## InitialProps

React Native 앱에서 사용자가 특정 화면으로 진입할 때, 네이티브(Android/iOS)가 앱으로 전달하는 **초기 데이터 타입**이에요.\
플랫폼별 구조가 다르고, 초기 렌더링과 상태 설정에 필요한 핵심 정보가 포함돼요.

* Android: `AndroidInitialProps`
* iOS: `IOSInitialProps`

### 프로퍼티

### 예제: 초기 데이터 활용하기

```tsx
import { AppsInToss } from '@apps-in-toss/framework';
import { PropsWithChildren } from 'react';
import { InitialProps } from '@granite-js/react-native';
import { context } from '../require.context';

function AppContainer({ children, ...initialProps }: PropsWithChildren<InitialProps>) {
  // 화면 진입 시 네이티브가 내려준 초기값을 활용할 수 있어요
  console.log({ initialProps });
  return <>{children}</>;
}

export default AppsInToss.registerApp(AppContainer, { context });
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인증/tosscertEncrypt.md
---
# 개인정보 암복호화

토스 인증 API는 일부 요청에서 고객의 개인정보가 포함될 수 있어요.  안전을 위해 고객사 서버와 토스 서버는 암호화된 데이터만 주고받아요. 평문이 필요할 땐 데이터를 복호화해 확인해 주세요.

* 인증 요청에서 고객의 이름, 생년월일, 휴대폰번호를 전달할 때 암호화
* 전자서명 서비스 원문에 고객의 개인정보가 포함되는 경우 원문 암호화
* 인증 결과로 토스 서버에서 CI・DI 등을 포함한 개인정보를 제공하는 경우 암호화

:::tip 원터치 본인 인증
고객사 서버에서 토스인증 서버로 고객의 정보를 전달하지 않기 때문에 암호화 과정이 불필요해요.\
다만, 사용자 인증이 완료된 이후 결과조회 API를 호출할 때는 세션키를 포함해서 요청해야 해요.
:::
---

## 세션 키 생성 및 암호화 예제

:::code-group

```java
package im.toss.cert.sdk;

import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;

class TossCertSessionTest {

    @Test
    public void test() {

        // 1. 세션 생성기를 사전에 1회만 생성해 주세요.
        TossCertSessionGenerator tossCertSessionGenerator = new TossCertSessionGenerator();

        // 2. 개인정보가 포함되어 있는 인증요청 API 호출 전에 세션을 생성해 주세요.
        TossCertSession tossCertSession = tossCertSessionGenerator.generate();

        // 3. 개인정보를 암호화 해주세요.
        String userName = "김토스";
        String encryptedUserName = tossCertSession.encrypt(userName);
        System.out.println("encryptedUserName: " + encryptedUserName);

        // 4. 인증요청 API를 호출해 주세요.
        // 인증요청 API의 바디 파라미터에 생성된 sessionKey를 추가해 주세요.
        String sessionKey = tossCertSession.getSessionKey();
        String userName = encryptedUserName;

        // 5. 사용자의 인증이 끝나면 결과조회 API 호출 전에 새로운 세션을 생성해 주세요.
        TossCertSession tossCertSession = tossCertSessionGenerator.generate();

        // 6. 결과조회 API를 호출해주세요.
        // 결과조회 API의 바디 파라미터에 생성된 sessionKey를 추가해 주세요.
        String sessionKey = tossCertSession.getSessionKey();
        String txId = "a39c84d9-458d-47e4-acf7-c481e851f79b";

        // 7. 복호화를 위해 결과조회 요청에서 생성했던 tossCertSession를 가지고 있어야 합니다.
        // response.userName 을 응답받은 암호화된 userName 이라고 가정합니다.
        // decryptedUserName 은 무결성 검증까지 완료되어 있습니다.
        String decryptedUserName = tossCertSession.decrypt(response.userName);
    }
}

```

:::

:::info 참고하세요
토스 테스트 환경에서는 실제 사용자의 개인정보가 아닌 토스가 생성한 가상 인물의 고정된 개인정보를 제공해요.
:::

:::tip 세션키 생성시 사용하는 Public key

```
"MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAoVdxG0Qi9pip46Jw9ImSlPVD8+L2mM47ey6EZna7D7utgNdh8Tzkjrm1Yl4h6kPJrhdWvMIJGS51+6dh041IXcJEoUquNblUEqAUXBYwQM8PdfnS12SjlvZrP4q6whBE7IV1SEIBJP0gSK5/8Iu+uld2ctJiU4p8uswL2bCPGWdvVPltxAg6hfAG/ImRUKPRewQsFhkFvqIDCpO6aeaR10q6wwENZltlJeeRnl02VWSneRmPqqypqCxz0Y+yWCYtsA+ngfZmwRMaFkXcWjaWnvSqqV33OAsrQkvuBHWoEEkvQ0P08+h9Fy2+FhY9TeuukQ2CVFz5YyOhp25QtWyQI+IaDKk+hLxJ1APR0c3tmV0ANEIjO6HhJIdu2KQKtgFppvqSrZp2OKtI8EZgVbWuho50xvlaPGzWoMi9HSCb+8ARamlOpesxHH3O0cTRUnft2Zk1FHQb2Pidb2z5onMEnzP2xpTqAIVQyb6nMac9tof5NFxwR/c4pmci+1n8GFJIFN18j2XGad1mNyio/R8LabqnzNwJC6VPnZJz5/pDUIk9yKNOY0KJe64SRiL0a4SNMohtyj6QlA/3SGxaEXb8UHpophv4G9wN1CgfyUamsRqp8zo5qDxBvlaIlfkqJvYPkltj7/23FHDjPi8q8UkSiAeu7IV5FTfB5KsiN8+sGSMCAwEAAQ==";
```

:::

제공되는 언어를 살펴보세요\
기본적으로 SDK 사용을 권장하지만, 다양한 언어의 코드 샘플도 함께 제공해요
https://github.com/toss/toss-cert-examples

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/게임/getUserKeyForGame.md
---

# 게임 로그인

## `getUserKeyForGame`

`getUserKeyForGame` 함수는 **게임 미니앱에서 유저를 식별할 수 있는 키 값을 가져오는 함수**예요.\
별도의 서버 연동 없이도 토스 로그인 기능처럼 유저를 구분할 수 있어요.

이 함수로 반환되는 유저 식별자(`hash`)는 **미니앱별로 고유하며,** [프로모션(토스 포인트) 기능](/bedrock/reference/framework/게임/grantPromotionRewardForGame.md)에서도 함께 사용할 수 있어요.

::: tip 주의하세요

* 이 함수는 **게임 카테고리 미니앱에서만 사용 가능**하며, 비게임 카테고리에서 호출하면 오류가 발생해요.
* **토스앱 5.232.0 버전 이상**에서 지원돼요. 그 이하 버전에서는 `undefined`를 반환해요.
* 모든 유저의 식별자를 안정적으로 확보하기 위해 **토스앱 최소 지원 버전이 5.232.0 버전으로 상향되었어요.**
  * 지원 버전 미만에서는 미니앱 진입 시 업데이트 안내 화면이 표시돼요.
* 게임 유저 식별자는 **게임사 내부 유저 식별용 키**로만 사용되며, 해당 키로 토스 서버에 직접 요청할 수 없어요.
* 샌드박스에서는 mock 데이터가 내려가고 있어, QR 코드로 테스트를 부탁드려요.
  :::

## 시그니처

```typescript
function getUserKeyForGame(): Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>;
```

### 반환 값

사용자 키 조회 결과를 반환해요.

* `GetUserKeyForGameSuccessResponse`: 사용자 키 조회에 성공했어요. `{ type: 'HASH', hash: string }` 형태로 반환돼요.
* `'INVALID_CATEGORY'`: 게임 카테고리가 아닌 미니앱에서 호출했어요.
* `'ERROR'`: 알 수 없는 오류가 발생했어요.
* `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.

## 예제

::: code-group

```js [js]
import { getUserKeyForGame } from '@apps-in-toss/web-framework';

async function handleGetUserKey() {
  const result = await getUserKeyForGame();

  if (!result) {
    console.warn('지원하지 않는 앱 버전이에요.');
  } else if (result === 'INVALID_CATEGORY') {
    console.error('게임 카테고리가 아닌 미니앱이에요.');
  } else if (result === 'ERROR') {
    console.error('사용자 키 조회 중 오류가 발생했어요.');
  } else if (result.type === 'HASH') {
    console.log('사용자 키:', result.hash);
    // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
  }
}
```

```tsx [React]
// webview
import { getUserKeyForGame } from '@apps-in-toss/web-framework';

function GameUserKeyButton() {
  async function handleClick() {
      const result = await getUserKeyForGame();

      if (!result) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }

      if (result === 'INVALID_CATEGORY') {
        console.error('게임 카테고리가 아닌 미니앱이에요.');
        return;
      }

      if (result === 'ERROR') {
        console.error('사용자 키 조회 중 오류가 발생했어요.');
        return;
      }

      if (result.type === 'HASH') {
        console.log('사용자 키:', result.hash);
        // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
      }
  }

  return (
    <button onClick={handleClick}>유저 키 가져오기</button>
  );
}
```

```tsx [React Native]
// react-native
import { Button } from 'react-native';
import { getUserKeyForGame } from '@apps-in-toss/framework';

function GameUserKeyButton() {
  async function handlePress() {
      const result = await getUserKeyForGame();

      if (!result) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }

      if (result === 'INVALID_CATEGORY') {
        console.error('게임 카테고리가 아닌 미니앱이에요.');
        return;
      }

      if (result === 'ERROR') {
        console.error('사용자 키 조회 중 오류가 발생했어요.');
        return;
      }

      if (result.type === 'HASH') {
        console.log('사용자 키:', result.hash);
        // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
      }
  }

  return (
    <Button onPress={handlePress} title="유저 키 가져오기" />
  );
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/게임/openGameCenterLeaderboard.md
---

# 게임 리더보드 열기 (`openGameCenterLeaderboard`)

`openGameCenterLeaderboard` 함수는 사용자가 게임 리더보드에서 자신의 순위를 확인할 수 있도록 리더보드 WebView를 호출해요.\
친구를 추가하거나, 친구에게 자신의 점수를 공유할 수도 있어요.

::: tip 주의하세요

* 토스앱 5.221.0 버전부터 지원해요. 게임 리더보드를 지원하지 않는 버전에서는 `undefined`를 반환합니다.
* 게임 프로필 WebView와 화면이 겹칠 수 있어요. 게임 진입 직후 바로 리더보드를 호출하는 것은 피해 주세요.
* 미니앱 정보 승인이 되지 않은 상황에서 호출하면 `LeaderBoard not found` 오류가 발생해요.

:::

## 시그니처

```typescript
function openGameCenterLeaderboard(): Promise<void>;
```

### 반환 값

## 예제

### 리더보드 웹뷰 호출하기

::: code-group

```js [js]
import { isMinVersionSupported, openGameCenterLeaderboard } from '@apps-in-toss/web-framework';

function handleOpenGameCenterLeaderboard() {
  const isSupported = isMinVersionSupported({
    android: '5.221.0',
    ios: '5.221.0',
  });

  if (!isSupported) {
    console.warn('지원하지 않는 앱 버전이에요.');
    return;
  }

  openGameCenterLeaderboard();
}
```

```tsx [React]
import { isMinVersionSupported, openGameCenterLeaderboard } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

// '리더보드' 버튼을 누르면 리더보드 웹뷰가 열려요.
function GameCenterLeaderboardOpenButton() {
  const isSupported = isMinVersionSupported({
    android: '5.221.0',
    ios: '5.221.0',
  });

  if (!isSupported) {
    return;
  }

  function handleClick() {
    openGameCenterLeaderboard();
  }

  return <Button onClick={handleClick}>리더보드 웹뷰 호출</Button>;
}
```

```tsx [React Native]
import { isMinVersionSupported, openGameCenterLeaderboard } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

// '리더보드' 버튼을 누르면 리더보드 웹뷰가 열려요.
function GameCenterLeaderboardOpenButton() {
  const isSupported = isMinVersionSupported({
    android: '5.221.0',
    ios: '5.221.0',
  });

  if (!isSupported) {
    return;
  }

  function handlePress() {
    openGameCenterLeaderboard();
  }

  return <Button onPress={handlePress}>리더보드 웹뷰 호출</Button>;
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-game](https://github.com/toss/apps-in-toss-examples/tree/main/with-game) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/게임/submitGameCenterLeaderBoardScore.md
---

# 게임 리더보드에 점수 제출하기 (`submitGameCenterLeaderBoardScore`)

`submitGameCenterLeaderBoardScore` 함수는 사용자가 게임이 완료되면 게임 리더보드에 점수를 제출합니다.\
사용자는 앱인토스 SDK에서 식별해요.\
점수를 제출하면 사용자가 리더보드에서 확인할 수 있어요.

::: tip 주의하세요

* 토스앱 5.221.0 버전부터 지원해요. 게임 리더보드를 지원하지 않는 버전에서는 `undefined`를 반환합니다.
* 게임 프로필이 생성되기 전에 점수를 제출하면 오류가 발생할 수 있어요. 게임에 진입하자마자 바로 점수를 제출하는 것은 피해 주세요.
* 미니앱 정보 승인이 되지 않은 상황에서 호출하면 `LeaderBoard not found` 오류가 발생해요.
* 샌드박스 환경에서도 테스트할 수 있어요. 샌드박스에서 기록한 점수는 실제 서비스 리더보드에는 반영되지 않아요.

:::

## 시그니처

```typescript
function submitGameCenterLeaderBoardScore(params: {
  score: string;
}): Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>;
```

### 파라미터

### 반환 값

## 예제

### 게임 점수를 토스게임센터 리더보드에 제출하기

::: code-group

```js [js]
import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';

async function handleSubmitGameCenterLeaderBoardScore() {
  try {
    const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });

    if (!result) {
      console.warn('지원하지 않는 앱 버전이에요.');
      return;
    }

    if (result.statusCode === 'SUCCESS') {
      console.log('점수 제출 성공!');
    } else {
      console.error('점수 제출 실패:', result.statusCode);
    }
  } catch (error) {
    console.error('점수 제출 중 오류가 발생했어요.', error);
  }
}
```

```tsx [React]
import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function GameCenterLeaderBoardScoreSubmitButton() {
  async function handleClick() {
    try {
      const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });

      if (!result) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }

      if (result.statusCode === 'SUCCESS') {
        console.log('점수 제출 성공!');
      } else {
        console.error('점수 제출 실패:', result.statusCode);
      }
    } catch (error) {
      console.error('점수 제출 중 오류가 발생했어요.', error);
    }
  }

  return <Button onClick={handleClick}>점수 제출하기</Button>;
}
```

```tsx [React Native]
import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function GameCenterLeaderBoardScoreSubmitButton() {
  async function handlePress() {
    try {
      const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });

      if (!result) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }

      if (result.statusCode === 'SUCCESS') {
        console.log('점수 제출 성공!');
      } else {
        console.error('점수 제출 실패:', result.statusCode);
      }
    } catch (error) {
      console.error('점수 제출 중 오류가 발생했어요.', error);
    }
  }

  return <Button onPress={handlePress}>점수 제출하기</Button>;
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-game](https://github.com/toss/apps-in-toss-examples/tree/main/with-game) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/startup-speed.md
---
# 게임 시작 속도 향상

AppsInToss 미니앱에서 게임 시작 속도는 첫인상을 좌우하는 핵심 요소예요.
게임이 3초 안에 시작되지 않으면, 사용자가 쉽게 이탈할 수 있어요.

## 1. 시작 성능 목표

### 성능 벤치마크

```
🎯 목표 시작 시간
├── 우수: < 2초 (네트워크 양호)
├── 양호: < 3초 (일반적 환경)  
├── 최소: < 5초 (느린 네트워크)
└── 임계: > 5초 (개선 필수)
```

### 측정 기준점

* 로딩 시작: 사용자가 게임 링크 클릭
* 첫 프레임: 게임 UI가 화면에 표시
* 상호작용 가능: 사용자 입력 받기 시작
* 완전 로드: 모든 초기 리소스 로드 완료

***

### Unity WebGL 시작 단계

```
📱 시작 과정 (총 소요시간: 목표 3초)
├── 1. HTML/JS 다운로드 (0.2초)
├── 2. WASM 다운로드 (0.8초)  
├── 3. WASM 컴파일 (0.5초)
├── 4. Unity 초기화 (0.3초)
├── 5. 첫 씬 로드 (0.7초)
├── 6. 스크립트 실행 (0.3초)
└── 7. 첫 프레임 렌더링 (0.2초)
```

### 병목 지점 식별

```c#
// 성능 측정 도구
public class StartupProfiler : MonoBehaviour
{
    private static float startTime;
    
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
    static void OnBeforeSceneLoad()
    {
        startTime = Time.realtimeSinceStartup;
        Debug.Log($"[Startup] Before Scene Load: {startTime}s");
    }
    
    void Awake()
    {
        float awakeTime = Time.realtimeSinceStartup - startTime;
        Debug.Log($"[Startup] Awake: {awakeTime}s");
    }
    
    void Start()
    {
        float startMethodTime = Time.realtimeSinceStartup - startTime;
        Debug.Log($"[Startup] Start: {startMethodTime}s");
        
        // AppsInToss 분석 시스템에 전송
        AppsInToss.Analytics.LogEvent("startup_timing", new Dictionary<string, object>
        {
            {"awake_time", awakeTime},
            {"start_time", startMethodTime}
        });
    }
}
```

***

## 3. 파일 크기 최적화

### WASM 파일 최적화

```c#
// Build Settings 최적화
public class BuildOptimizer
{
    [MenuItem("AppsInToss/Optimize Build Settings")]
    static void OptimizeBuildSettings()
    {
        // IL2CPP 설정 최적화
        PlayerSettings.SetScriptingBackend(BuildTargetGroup.WebGL, ScriptingImplementation.IL2CPP);
        
        // 코드 최적화 레벨
        PlayerSettings.SetIl2CppCompilerConfiguration(BuildTargetGroup.WebGL, Il2CppCompilerConfiguration.Release);
        
        // 불필요한 코드 제거
        PlayerSettings.stripEngineCode = true;
        PlayerSettings.SetManagedStrippingLevel(BuildTargetGroup.WebGL, ManagedStrippingLevel.High);
        
        // 압축 설정
        PlayerSettings.WebGL.compressionFormat = WebGLCompressionFormat.Brotli;
    }
}
```

### 에셋 최적화

```c#
// 텍스처 압축 자동화
public class TextureOptimizer : AssetPostprocessor
{
    void OnPreprocessTexture()
    {
        var importer = assetImporter as TextureImporter;
        
        // WebGL 플랫폼 설정
        var platformSettings = new TextureImporterPlatformSettings
        {
            name = "WebGL",
            overridden = true,
            maxTextureSize = 1024, // 모바일 고려
            format = TextureImporterFormat.DXT5,
            compressionQuality = 80, // 품질 vs 크기 균형
            allowsAlphaSplitting = true
        };
        
        importer.SetPlatformTextureSettings(platformSettings);
    }
}
```

***

## 4. 점진적 로딩 전략

### 필수 vs 선택적 리소스 분리

```c#
public class ProgressiveLoader : MonoBehaviour
{
    [System.Serializable]
    public class LoadPhase
    {
        public string name;
        public Object[] assets;
        public bool isEssential;
        public float maxLoadTime;
    }
    
    public LoadPhase[] loadPhases;
    
    async void Start()
    {
        // Phase 1: 즉시 필요한 필수 리소스만
        await LoadPhase("Essential");
        ShowBasicUI(); // 빠르게 사용자에게 보여주기
        
        // Phase 2: 게임플레이 리소스 (백그라운드)
        _ = LoadPhase("Gameplay");
        
        // Phase 3: 부가 기능들 (지연 로딩)
        _ = LoadPhase("Optional");
    }
    
    async Task LoadPhase(string phaseName)
    {
        var phase = loadPhases.First(p => p.name == phaseName);
        var stopwatch = System.Diagnostics.Stopwatch.StartNew();
        
        foreach (var asset in phase.assets)
        {
            await LoadAssetAsync(asset);
            
            // 시간 제한으로 반응성 유지
            if (phase.maxLoadTime > 0 && stopwatch.ElapsedMilliseconds > phase.maxLoadTime)
            {
                Debug.LogWarning($"Phase {phaseName} exceeded time limit");
                break;
            }
        }
    }
}
```

### Addressable 활용

```c#
public class AddressableStartup : MonoBehaviour
{
    [SerializeField] private AssetReference essentialUI;
    [SerializeField] private AssetReference gameplayAssets;
    
    async void Start()
    {
        // 1단계: 필수 UI 로드
        var uiHandle = essentialUI.InstantiateAsync();
        await uiHandle.Task;
        
        ShowLoadingScreen();
        
        // 2단계: 게임플레이 에셋 로드 (프로그레스 표시)
        var gameplayHandle = gameplayAssets.LoadAssetAsync<GameObject>();
        
        while (!gameplayHandle.IsDone)
        {
            UpdateLoadingProgress(gameplayHandle.PercentComplete);
            await Task.Yield();
        }
        
        StartGame();
    }
}
```

***

## 5. 첫 프레임 최적화

### 첫 프레임에서 피해야 할 작업들

```c#
public class FirstFrameOptimizer : MonoBehaviour
{
    void Start()
    {
        // ❌ 피해야 할 작업들 (첫 프레임에서)
        
        // 1. 대량의 오브젝트 생성
        // for (int i = 0; i < 1000; i++) Instantiate(prefab);
        
        // 2. 복잡한 계산
        // CalculateComplexAlgorithm();
        
        // 3. 파일 I/O
        // File.ReadAllText("large_file.json");
        
        // 4. 네트워크 요청  
        // UnityWebRequest.Get(url).SendWebRequest();
        
        // ✅ 대신 코루틴이나 비동기로 처리
        StartCoroutine(InitializeGameSystems());
    }
    
    IEnumerator InitializeGameSystems()
    {
        // 프레임별로 작업 분산
        yield return StartCoroutine(LoadEssentialData());
        yield return StartCoroutine(InitializeUI());
        yield return StartCoroutine(SetupGameplay());
        
        OnInitializationComplete();
    }
    
    IEnumerator LoadEssentialData()
    {
        int itemsPerFrame = 10;
        
        for (int i = 0; i < dataItems.Count; i++)
        {
            ProcessDataItem(dataItems[i]);
            
            // 매 N개마다 프레임 양보
            if (i % itemsPerFrame == 0)
                yield return null;
        }
    }
}
```

### 오브젝트 풀링 사전 준비

```c#
public class StartupObjectPool : MonoBehaviour
{
    [System.Serializable]
    public class PoolData
    {
        public GameObject prefab;
        public int preloadCount;
        public bool loadOnStart;
    }
    
    public PoolData[] pools;
    
    void Start()
    {
        // 필수 오브젝트만 즉시 로드
        foreach (var pool in pools.Where(p => p.loadOnStart))
        {
            StartCoroutine(PreloadPool(pool));
        }
        
        // 나머지는 지연 로드
        StartCoroutine(PreloadRemainingPools());
    }
    
    IEnumerator PreloadPool(PoolData pool)
    {
        var poolContainer = new GameObject($"Pool_{pool.prefab.name}");
        
        for (int i = 0; i < pool.preloadCount; i++)
        {
            var obj = Instantiate(pool.prefab, poolContainer.transform);
            obj.SetActive(false);
            
            // 2개마다 프레임 양보
            if (i % 2 == 0) yield return null;
        }
    }
}
```

***

## 6. 메모리 사전 최적화

### 시작 시 메모리 설정

```c#
public class MemoryPreoptimizer : MonoBehaviour
{
    void Awake()
    {
        // 텍스처 스트리밍 설정
        QualitySettings.streamingMipmapsActive = true;
        QualitySettings.streamingMipmapsMemoryBudget = 128; // MB
        
        // 오디오 설정 최적화
        AudioSettings.GetConfiguration(out var config);
        config.sampleRate = 22050; // 모바일에서는 낮은 샘플레이트
        config.speakerMode = AudioSpeakerMode.Stereo;
        AudioSettings.Reset(config);
        
        // 가비지 컬렉션 최적화
        System.GC.Collect();
        System.GC.WaitForPendingFinalizers();
    }
}
```

***

## 7. 네트워크 최적화

### CDN 및 캐싱 전략

```c#
public class NetworkOptimizer : MonoBehaviour
{
    private static readonly Dictionary<string, byte[]> assetCache = new Dictionary<string, byte[]>();
    
    public async Task<T> LoadAssetFromCDN<T>(string url) where T : Object
    {
        // 로컬 캐시 확인
        if (assetCache.TryGetValue(url, out var cachedData))
        {
            return DeserializeAsset<T>(cachedData);
        }
        
        // CDN에서 로드
        using var request = UnityWebRequest.Get(url);
        
        // 압축 헤더 설정
        request.SetRequestHeader("Accept-Encoding", "gzip, deflate, br");
        
        await request.SendWebRequest();
        
        if (request.result == UnityWebRequest.Result.Success)
        {
            var data = request.downloadHandler.data;
            assetCache[url] = data; // 캐싱
            
            return DeserializeAsset<T>(data);
        }
        
        return null;
    }
}
```

***

## 8. 브라우저별 최적화

\###브라우저 감지 및 최적화

```c#
// JavaScript 최적화 (HTML Template에 추가)
class BrowserOptimizer {
    static detectBrowser() {
        const ua = navigator.userAgent;
        
        if (ua.includes('Chrome')) {
            return 'chrome';
        } else if (ua.includes('Safari') && !ua.includes('Chrome')) {
            return 'safari';
        } else if (ua.includes('Firefox')) {
            return 'firefox';
        }
        
        return 'unknown';
    }
    
    static optimizeForBrowser() {
        const browser = this.detectBrowser();
        
        switch (browser) {
            case 'chrome':
                this.optimizeForChrome();
                break;
            case 'safari':
                this.optimizeForSafari();
                break;
            case 'firefox':
                this.optimizeForFirefox();
                break;
        }
    }
    
    static optimizeForSafari() {
        // Safari WebGL 컨텍스트 최적화
        Module.canvas.addEventListener('webglcontextlost', function(event) {
            event.preventDefault();
            console.log('WebGL context lost, attempting recovery...');
        });
        
        // Safari 메모리 최적화
        if (window.performance && window.performance.memory) {
            setInterval(() => {
                if (window.performance.memory.usedJSHeapSize > 100 * 1024 * 1024) {
                    console.log('High memory usage detected, triggering GC');
                    window.gc && window.gc();
                }
            }, 30000);
        }
    }
}

// Unity 로드 전 최적화 실행
BrowserOptimizer.optimizeForBrowser();
```

***

## 9. 개발자 도구 및 측정

### 시작 성능 측정 도구

```c#
public class StartupBenchmark : MonoBehaviour
{
    private static readonly List<(string phase, float time)> benchmarks = new List<(string, float)>();
    
    public static void MarkPhase(string phaseName)
    {
        float time = Time.realtimeSinceStartup;
        benchmarks.Add((phaseName, time));
        
        Debug.Log($"[Benchmark] {phaseName}: {time:F2}s");
        
        // AppsInToss 분석에 전송
        AppsInToss.Analytics.LogEvent("startup_phase", new Dictionary<string, object>
        {
            {"phase", phaseName},
            {"time", time},
            {"device_model", SystemInfo.deviceModel},
            {"memory_size", SystemInfo.systemMemorySize}
        });
    }
    
    public static void GenerateReport()
    {
        var report = new StringBuilder();
        report.AppendLine("=== 시작 성능 리포트 ===");
        
        for (int i = 0; i < benchmarks.Count; i++)
        {
            var current = benchmarks[i];
            float deltaTime = i > 0 ? current.time - benchmarks[i-1].time : current.time;
            
            report.AppendLine($"{current.phase}: {current.time:F2}s (delta: {deltaTime:F2}s)");
        }
        
        Debug.Log(report.ToString());
    }
}
```

***

## 10. 체크리스트 및 모범 사례

### 시작 최적화 체크리스트

* WASM 파일 크기 < 10MB
* 첫 씬 에셋 크기 < 5MB
* 첫 프레임에서 무거운 작업 제거
* 점진적 로딩 구현
* 브라우저별 최적화 적용
* 성능 측정 및 분석 도구 적용
* CDN 캐싱 전략 구현
* 메모리 사전 최적화

### 일반적인 함정들

```c#
// ❌ 피해야 할 패턴들

// 1. Start()에서 모든 것을 초기화
void Start() 
{
    LoadAllData(); // 블로킹
    InitializeAllSystems(); // 무거운 작업
    ConnectToServer(); // 네트워크 지연
}

// 2. Resources.Load 남용
void LoadAssets()
{
    // 동기적 로딩으로 프레임 드롭
    var texture = Resources.Load<Texture2D>("LargeTexture");
    var audio = Resources.Load<AudioClip>("LargeAudio");
}

// 3. 첫 프레임에서 복잡한 UI 생성
void Start()
{
    // 수백 개의 UI 요소를 한번에 생성
    for (int i = 0; i < 500; i++)
    {
        Instantiate(uiElementPrefab);
    }
}
```

### 올바른 패턴들

```c#
// 분산된 초기화
async void Start()
{
    ShowSplashScreen();
    
    // 단계별 로딩
    await LoadEssentialData();
    ShowBasicUI();
    
    await LoadGameplayData();
    EnableGameplay();
    
    await LoadOptionalFeatures();
    OnFullyLoaded();
}

// 비동기 리소스 로딩
async Task LoadAssets()
{
    var textureTask = LoadAssetAsync<Texture2D>("LargeTexture");
    var audioTask = LoadAssetAsync<AudioClip>("LargeAudio");
    
    await Task.WhenAll(textureTask, audioTask);
}

// 점진적 UI 생성
IEnumerator CreateUI()
{
    int elementsPerFrame = 5;
    
    for (int i = 0; i < totalElements; i++)
    {
        CreateUIElement(i);
        
        if (i % elementsPerFrame == 0)
            yield return null; // 프레임 양보
    }
}
```

사용자는 완벽한 게임보다 빠르게 시작되는 게임을 선호해요.\
필수 기능부터 빠르게 보여주고 나머지는 점진적으로 로드해요

---

---
url: 'https://developers-apps-in-toss.toss.im/checklist/app-game.md'
description: >-
  게임 미니앱 출시 전 필수 체크리스트입니다. 내비게이션 바, 사운드, 등급 표기, 디자인 가이드 준수 등 출시 검토 통과를 위한 상세
  가이드를 확인하세요.
---

# 게임 출시 가이드

게임 미니앱 출시 전에 꼭 확인해야 할 체크리스트에요.\
아래 내용을 지키지 않으면 앱 출시 검토에서 반려될 수 있으니 반드시 확인해 주세요.

:::info **확인해 주세요**

* 앱 출시 검토 전에는 **앱 정보 검토, 사업자 인증, 대표관리자 신청 승인**이 먼저 완료되어야 해요.
  * [**콘솔에서 앱 등록하기**](/prepare/console-workspace.html)를 확인해 주세요.
* [**다크패턴 방지 정책**](/design/consumer-ux-guide.html) 및 [**미니앱 브랜딩 가이드**](/design/miniapp-branding-guide.html)을 꼭 준수해 주세요.
* 미니앱 내의 콘텐츠에 ‘불법성’, ‘선정성’ 등 법적으로 위반될 수 있는 콘텐츠가 없는지 확인해 주세요.
* 자사 앱 및 자사 웹으로의 유도는 불가하므로 [**가이드**](/intro/guide.html#자사-앱-설치-외부-링크)를 꼭 준수해 주세요.
  :::

## 1. 연령 등급 표기

**앱인토스 게임 미니앱 접속 시 표시 되는 연령 등급은** 콘솔에 입력한 정보를 기반으로 자동으로 노출 돼요.\
(토스 앱 버전 5.240.0부터 노출 / [콘솔에서 연령 등급 정보 입력 하는 방법 보러가기](/prepare/console-workspace.html#_4-3-%E1%84%80%E1%85%A6%E1%84%8B%E1%85%B5%E1%86%B7-%E1%84%83%E1%85%B3%E1%86%BC%E1%84%80%E1%85%B3%E1%86%B8%E1%84%87%E1%85%AE%E1%86%AB%E1%84%85%E1%85%B2))

* 게임 등급분류에 대한 궁금한 점을 [블로그 아티클](https://toss.im/apps-in-toss/blog/game_rating_classification?slugOrId=game_rating_classification)에서 해결할 수 있어요.
* 만약, 게임 등급분류와 관련한 정보 확인이 필요한 경우 [게임물관리위원회](https://www.grac.or.kr/)로 문의해 주세요.

![](/assets/game_ranking.FXD3b7tr.png)

## 2. 풀스크린

사용자의 몰입도 향상 및 높은 게임 경험을 위하여 모든 게임 미니앱은 풀스크린으로 구현해 주세요.

* 게임 콘텐츠 및 플레이 화면이 디바이스 전체 화면을 완전히 점유해야 해요.
* 상단/하단의 빈 영역 등으로 인해 시각적으로 단절된 부분이 없어야 하며, **웹뷰 여백이나 반투명 영역이 남지 않도록 구현해 주세요.**
* 풀스크린 구현으로 인한 해상도 저하 또는 컴포넌트나 에셋이 깨지지 않게 구현해 주세요.
* iOS의 **Dynamic Island**, 기기별 노치·카메라 홀 등을 침범하지 않도록 안전 영역을 고려해야 해요.
* **기기 회전에 따른 비율 깨짐, 레터박스(검은 여백) 발생이 되지 않는지 꼭 확인해 주세요.**
* UI 깨짐, 스크롤 오류, 입력 불가 영역 등이 없어야 해요.

![](/assets/full-screen.DZlEFuV9.png)

## 3. 내비게이션 바

미니앱 상단에 위치하는 공통으로 적용되는 내비게이션 바를 말해요.\
**게임 미니앱을 위한 공통 내비게이션 바 사용이 필요해요.**

![](/assets/game-guide-3.DhBrYXz2.png)

| **위치** | **항목**         | 설명                                                                                                                                                                                                                                        |
| -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **우측** | 제휴사 기능 버튼 | 선택- 화면에 필요한 기능 1개를 노출시킬 수 있어요.- 모노 아이콘만 추가할 수 있어요.- 문구나 커스텀 UI는 지원하지 않아요.- 화면별로 커스텀이 가능해요. - 홈 버튼은 넣을 수 없어요. |
|          | 더보기 버튼 (⋯)  | 필수  - 신고하기, 공유하기 등 토스의 기능이 들어가요.  - 커스텀할 수 없어요.                                                                                                                    |
|          | 닫기 버튼 (X)    | 필수                                                                                                                                                                                                    |

* **제휴사 기능 버튼** 추가하는 방법은 [내비게이션 바 설정](/bedrock/reference/framework/UI/NavigationBar.md) 문서를 참고하세요.
* 우측 상단 **⋯** 버튼과 **X** 버튼이 고정 노출되며, 정상 동작이 되는지 확인해 주세요.
* **내비게이션 바의 X 버튼이 게임 화면의 다른 버튼과 겹치지 않는지 확인해 주세요.**\
  (기종마다 상이할 수 있기에 꼭 체크해 주세요.)
* 종료 시 종료한다는 것에 대한 **확인 모달**은 필수로 사용해 주세요.
  * 텍스트: `$서비스명$을 종료할까요?`
  * 버튼: `취소` / `종료하기` (브랜드 컬러 적용)

![](/assets/game-guide-4.DDFiAEE3.png)

## 4. 시스템 모드

현재 앱인토스 미니앱 서비스는 다크 모드를 제공하지 않아요. (추후 제공 시 공지될 예정이에요.)\
따라서 미니앱 내 테마는 **라이트 모드 기준**으로 설정해 주세요.

## 5. 사운드

미니앱의 사운드는 배경음, 효과음, 햅틱 등을 모두 포함해요.\
게임 미니앱에서 사운드 적용은 선택사항이지만,\
**사용자 경험을 긍정적으로 향상 시키기 위해 사운드 적용을 권장해요.**

* 사운드를 적용한다면 사용자가 배경음과 효과음을 `On/Off` 할 수 있어야 해요.
* 디바이스의 무음 모드 또는 진동 설정 시 해당 설정에 맞춰 작동해야 해요.
* 백그라운드 전환 및 복귀 시 사운드가 멈추거나 다시 재생이 되어야 해요.
  * 백그라운드 전환 시 사운드가 계속 재생이 되지 않는지 확인해야 해요.
  * 백그라운드에서 복귀했을 때 사운드가 사라지지 않는지 반드시 확인해야 해요.
    * 단, 필요한 경우 (예: 틀린 그림 찾기)에만 사용할 수 있어요.

## 6. 확대/축소

미니앱의 화면을 손가락으로 확대 또는 축소하는 액션을 할 때에 관한 내용이에요.

* 미니앱 내에서 제스처를 통한 확대/축소 기능은 기본적으로 사용이 불가해요.
  * 사용자의 미니앱 경험을 수호하기 위함이에요.
  * 단, 틀린 그림 찾기와 같이 해당 기능이 필수로 필요한 경우에만 제한적으로 이용할 수 있어요.

:::tip 핀치줌 막기
meta viewport에 `initial-scale=1, maximum-scale=1, user-scalable=no` 를 추가하면 모바일 브라우저에서 핀치줌을 비활성화할 수 있어요.\
:::

## 7. 접근성

앱인토스는 토스 앱의 서비스로서, **모든 사용자가 불편 없이 미니앱을 이용할 수 있도록 접근성 준수**를 권장하고 있어요.

* 텍스트·버튼 등 주요 요소의 **명도 대비(contrast)** 가 충분한지 확인해 주세요.
* 버튼, 조작 UI는 **터치 영역**을 확보해 주세요.
* 화면 전환, 애니메이션 등이 **지나치게 빠르거나 현기증을 유발하지 않도록** 구현해 주세요.
* 스크린 리더 사용 시 주요 콘텐츠가 의도한 순서대로 읽히는지 확인해 주세요.
* 접근성에 대한 더 자세한 사항은 [가이드](https://frontend-fundamentals.com/a11y/)를 참고해 주세요.

## 8. 전반적인 서비스 이용 및 동작

더욱 나은 사용자 경험을 위해 아래 내용을 반드시 확인해 주세요.

* 앱 정보의 나이 제한과 서비스 내용이 일치하는지 확인해 주세요.
* 미니앱에 설정된 **세로모드 또는 가로모드**가 정상적으로 구현되는지 확인해 주세요.
* 스크롤과 인터렉션, UI의 반응이 원활한지 확인해 주세요. (2초 이상의 반응일 경우 사용자 이탈률이 증가할 수 있어요.)
* 미니앱 내의 컴포넌트가 정상적으로 작동하는지 확인해 주세요.
* 좌측 스와이프와 안드로이드 OS 자체의 뒤로가기 버튼을 누를 경우 종료되지 않게 해주세요.
* 게임 진행 시, 스코어 측정과 스테이지 클리어와 같이 주요 기능이 정상적으로 동작하는지 확인해 주세요.
* 게임 종료 후 재접속 및 토스 로그인을 사용할 때에는 기기를 변경하거나 토스 앱 삭제 후 재설치하여 다시 로그인하더라도 데이터가 정상적으로 저장되는지 확인해 주세요.
* 광고를 3회 이상 시청한 이후에도 게임이 정상적으로 작동하는지 확인해 주세요.
* 게임 진행이 불가한 버그가 없는지 확인해 주세요.

## 9. 데이터 및 메모리 사용량

미니앱 이용 중 발생하는 **데이터 사용량**과 **메모리 사용량**을 점검해야 해요.
이는 사용자 경험에 직접적인 영향을 미치기 때문에, 반드시 최적화가 필요해요.

* **데이터 사용량이 과도하면** 로딩 지연, 데이터 요금 부담 등으로 사용자 불만이 발생할 수 있어요.\
  → 이미지, 영상, 리소스 파일의 용량을 최소화해 주세요.
* **메모리 누수가 발생할 경우** 기기 발열이나 앱 강제 종료로 이어질 수 있어요.\
  → 게임 내 오브젝트, 타이머, 이벤트 리스너가 정상적으로 해제되는지 확인해 주세요.
* 앱인토스 검수 과정에서도 데이터·메모리 사용량을 함께 확인하니,\
  **과도한 사용이나 누수가 발생하지 않도록 반드시 점검해 주세요.**

> 개발 중에는 개발자 도구(DevTools)나 Xcode/Android Studio의 프로파일러를 활용해\
> 메모리 및 네트워크 사용량을 실시간으로 확인해 주세요.

* 이미지나 애니메이션의 해상도가 지나치게 높으면 메모리 사용량이 급증할 수 있어요.\
  → **기기 성능에 맞는 적정 해상도**를 사용해 주세요.

## 10. 앱 사용 권한

개발한 미니앱에서 사용되는 권한들에 대한 내용이에요.

* 콘솔에서 앱 번들을 업로드하면 미니앱에서 필요한 권한들을 확인할 수 있어요.
* 사용이 필요한 권한이 정상적으로 적용 및 작동되고 있는지 꼭 확인해주세요.
* 사용자가 특정 권한 동의를 하지 않더라도 해당 기능을 제외한 나머지 기능이 정상적으로 작동되어야 해요.

![](/assets/game-guide-5.Di4p8C3J.png)

## 11. 보안

**보안 이슈가 발생하는 경우에는 앱 출시 검토에서 반려될 수 있어요.**\
**반려된 경우, 자세한 사유는 이메일과 콘솔에서 확인할 수 있어요.**

***

아래는 앱인토스가 제공하는 기능별 가이드라인을 안내드려요.

## 12. 인앱 광고

앱인토스 콘솔에서 인앱 광고를 설정하여 연동한 경우, 아래 항목을 반드시 확인해 주세요.\
광고 로딩, 종료, 리워드 처리 등은 모두 검수 항목에 포함돼요.

* 콘솔에서 설정한 **광고가 정상적으로 노출되는지** 확인해 주세요.
* **광고는 반드시 사전 로드(Preload)** 되어야 해요.
  * 페이지 진입 시마다 광고를 사전 로드해 두면 노출 지연을 방지할 수 있어요.
* **리워드 광고의 경우,** 광고가 **정상적으로 완료된 이후에만** 보상이 지급되어야 해요.
  * 광고가 중도 종료되거나 실패한 경우에는 보상이 지급되지 않아야 해요.
* 광고를 표시할 때(`show` 호출)에는 반드시 **광고 SDK에서 전달하는 이벤트(event)** 를 받아 처리해야 해요.
  * 이벤트를 수신하지 않은 상태에서 내부 처리를 진행하면 오류가 발생하거나 **eCPM(노출 단가)에 영향을 줄 수 있어요.**
* 광고 종료 후에는 **미니앱의 음악이 자동으로 재개**되어야 해요.
* 광고가 **정상 종료되거나 중도 종료될 경우,** 사용자 화면이 **정상적으로 미니앱으로 복귀(랜딩)** 되어야 해요.
* 출시 전에는 **테스트용 광고 ID가 설정되어 있지 않은지** 반드시 확인해 주세요.

## 13. 인앱 결제

게임 미니앱에서는 **디지털 재화**(아이템, 코인 등)를 판매할 수 있으며,\
결제는 반드시 **인앱결제(In-App Purchase)** 를 통해 진행해야 해요.
인앱결제를 연동한 경우 아래 항목을 모두 확인해 주세요.

* 사용자가 아이템을 선택해 **결제 화면으로 진입할 때,**\
  미니앱 내에서 재생 중인 **음악이나 효과음이 자동으로 멈추는지** 확인해 주세요.
* 미니앱 내에서 표시된 **상품 금액**과 실제 **결제창(애플 App Store / 구글 Play Store)** 에 노출되는 금액이 정확히 일치해야 해요.
* 결제 진행 중 오류 없이 정상적으로 결제가 완료되는지,\
  결제를 **완료하지 않고 이탈한 경우에는 정상적으로 취소 처리**되는지 확인해 주세요.
* 결제 실패 시에는 **오류 원인(예: 네트워크 오류, 결제 취소 등)** 을
  사용자에게 명확히 안내해야 해요.
* 결제 완료 후에는 사용자가 **결제 내역을 확인할 수 있는 화면 또는 메뉴**를 제공해야 해요.
* 사용자가 **기기를 변경하거나 토스 앱을 재설치**하더라도,\
  인앱결제를 통해 구매한 데이터가 **정상적으로 유지**되어야 해요.
* 현재는 **구독 상품은 제공할 수 없어요.**\
  (추후 제공 예정이에요.)

## 14. 프로모션

프로모션을 사용하는 경우에는 [**프로모션 검토 가이드**](/promotion/console.html#_8-프로모션-검토-가이드라인)를 꼭 확인해 주세요.\
또한 자체적인 이벤트나 프로모션인 경우에도 프로모션 가이드 및 아래 내용은 진행할 수 없어요.

* 현금성 또는 환금성 이벤트는 아닌지 확인해 주세요.
* 게임 아이템, 기프티콘, 상품권 등을 현금화하거나 포인트를 토스포인트로 전환하는 이벤트는 불가해요.
* 사행성 또는 투기성 등 성격의 이벤트는 허용되지 않아요.

## 15. 게임 프로필 & 리더보드

제공하는 기능 중 게임 프로필과 리더보드를 적용한 경우 아래 내용을 모두 확인해 주세요.

* 사용자가 게임 프로필을 생성하기 전에 먼저 리더보드를 호출하지는 않았는지 확인해 주세요.
  * 게임 진입 직후 리더보드를 호출하게 될 경우 오류가 발생해요.
* 개발한 리더보드 화면이 정상적으로 노출되는지 확인해 주세요.
* 게임을 진행한 후 해당 게임의 결과가 실시간으로 리더보드에 반영되는지 확인해 주세요.

## 16. 공유 리워드

미니앱을 주변 사람들에게 공유하고 초대할 경우 리워드가 제공되는 기능이에요.\
연동한 경우 아래 내용을 모두 확인해 주세요.

* 앱인토스 콘솔에서 친구 초대를 한 경우 설정된 리워드가 정상적으로 노출되는지 확인해 주세요.
* 친구 초대 및 리워드를 진행하지 않고 사용자가 종료한 경우 미니앱으로 다시 랜딩되는지 확인해 주세요.
* 친구 초대가 정상적으로 완료되면 초대자에게 설정된 보상이 정상적으로 지급되는지 확인해 주세요.
* 더 이상 초대할 친구가 없을 때는 관련 화면이 미노출 되는지 확인해 주세요.

## 17. 토스 로그인

토스 로그인을 사용한 경우에 아래 내용을 모두 확인해 주세요.

* 콘솔에서 등록한 약관 및 약관 확인 시 정상적으로 연결하는지 확인해 주세요.
* 약관 확인 및 체크 박스 선택과 하단의 ‘동의하고 시작하기’ CTA를 누를 경우 정상적으로 로그인이 진행되는지 확인해 주세요.
  * 로그인 실패로 노출이 되거나 로그인이 완료되었다면 다른 페이지로 이동 시 로그인이 풀리지 않아야 해요.
* 토스앱 설정에서 ‘토스로 로그인한 서비스’ 에서 로그인을 끊으면 다시 미니앱 접속 시 기존 데이터가 남아 있지 않고 새롭게 로그인을 요청하는지 확인해 주세요.
* 토스 로그인 요청 화면에서 **‘닫기’** 를 누를 경우 아래와 같이 작동하게 해주세요.
  * 로그인을 인트로 페이지에서 약관을 받는 경우 닫기 버튼을 눌렀을 때 → **미니앱이 닫힘**
  * 서비스 플로우 중간에 약관을 받는 경우 → **이전 미니앱 화면으로 랜딩**
* 토스 로그인을 사용하는 경우, 사용자가 서비스의 성격과 가치를 이해한 상태에서 로그인(약관 동의)을 진행할 수 있어야 해요.
* 특히 미니앱 진입과 함께 토스 로그인을 요청하려면, 첫 화면에서 인트로 페이지를 통해 어떤 서비스인지 명확히 안내해야 해요.

![](/assets/game-guide-2.S10J2Avo.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/게임/grantPromotionRewardForGame.md
---

# 게임 프로모션(토스 포인트)

## `grantPromotionRewardForGame`

`grantPromotionRewardForGame` 함수는 [`getUserKeyForGame`](/bedrock/reference/framework/게임/getUserKeyForGame.md) 으로부터 받은 **유저 식별자 (`hash`)를 사용해 프로모션(토스 포인트) 기능을 실행하는 함수**예요.\
별도의 서버 연동 없이도 **게임 미니앱 내에서 유저에게 토스 포인트를 지급**하고, 혜택탭에 노출할 수 있어요.

이 함수는 **게임 카테고리 미니앱에서만 호출할 수 있으며,** 비게임 카테고리에서 실행하면 오류가 발생해요.

::: tip 프로모션 기능
앱인토스의 프로모션은 **사용자의 특정 행동을 기준으로 토스 포인트를 지급하는 이벤트 기능**이에요.\
프로모션은 **비즈 월렛에 충전한 예산으로 진행**할 수 있으며, **혜택 탭 노출 여부를 콘솔에서 설정**할 수 있어요.\
[프로모션 기능 이해하기](/promotion/intro.md)\
[프로모션 기능 콘솔 가이드](/promotion/console.md)\
:::

::: tip 주의하세요

* **토스앱 5.232.0 버전 이상**에서 지원해요.\
  해당 버전 미만에서는 `undefined`가 반환돼요.
* 모든 사용자의 식별자를 안정적으로 확보하기 위해 **토스앱 최소 지원 버전을 5.232.0으로 상향**했어요.
  * 최소 버전 미만에서는 미니앱 진입 시 업데이트 안내 화면이 표시돼요.
* 게임 유저 식별자는 **게임사 내부 식별용 키**로만 사용되며, 이 키로 토스 서버에 직접 요청할 수 없어요.
* **프로모션 기능을 개발한 후, 실제 프로모션을 시작하기 전에 테스트용 프로모션 코드로 최소 1회 이상 호출해야 합니다.**\
  (테스트 호출을 통해 프로모션이 정상적으로 등록 및 승인 상태로 전환돼요.)
  :::

## 시그니처

```typescript
function grantPromotionRewardForGame({ params, }: {
    params: {
        promotionCode: string;
        amount: number;
    };
}): Promise<GrantPromotionRewardForGameResult>;
```

### 파라미터

### 반환 값

포인트 지급 결과를 반환해요.

* `{ key: string }`: 포인트 지급에 성공했어요. key는 리워드 키를 의미해요.
* `{ errorCode: string, message: string }`: 포인트 지급에 실패했어요. 에러 코드를 확인해 주세요.

### 에러 코드

프로모션 함수 사용 중 발생할 수 있는 에러 코드 목록입니다.\
응답 코드나 메시지를 참고해 **적절한 예외 처리 로직**을 적용해 주세요.

::: tip `4109` 에러가 발생한다면?

* 프로모션 예산의 **80% 소진이 이메일로 안내**가 발송돼요.
* 프로모션을 계속 진행하려면 **콘솔에서 예산을 증액**해 주세요.
* 예산이 부족할 경우, **비즈월렛에서 금액을 충전**해 예산을 늘릴 수 있어요.
* 예산이 모두 소진되면 프로모션이 **자동으로 종료되어 `4109` 에러가 발생**해요.
* 예산 부족으로 인해 포인트 지급이 실패하면 **사용자 CS 이슈로 이어질 수 있으니 주의**해 주세요.
  :::

| 코드 | 메시지 | 발생 원인 / 대응 방법 |
|------|--------|-------------------|
| `40000`| |게임이 아닌 미니앱에서 호출한 경우|
| `4100` | 프로모션 정보를 찾을 수 없어요 | 콘솔에 등록되지 않은 프로모션 키로 호출한 경우|
| `4109` | 프로모션이 실행중이 아니에요 | 콘솔에서 프로모션을 시작하지 않았거나, 예산이 모두 소진되어 자동 종료된 경우|
| `4110` | 리워드를 지급/회수할 수 없어요 | 내부 시스템 오류 발생한 경우로, **재지급 로직**을 적용해 주세요. |
| `4111` | 리워드 지급내역을 찾을 수 없어요 |존재하지 않은 지급 내역을 조회한 경우|
| `4112` | 프로모션 머니가 부족해요 |예산 부족으로 지급이 실패한 경우로, 콘솔에서 예산 증액 또는 비즈월렛 충전 필요|
| `4114` | 1회 지급 금액을 초과했어요 ||
| `4116` | 최대 지급 금액이 예산을 초과했어요 ||
|`ERROR`|알 수 없는 오류가 발생했어요.||
|`undefined`|앱 버전이 최소 지원 버전보다 낮아요.||

## 예제

::: code-group

```js [js]
import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';

async function handleGrantPromotionRewardForGame() {
  const result = await grantPromotionRewardForGame({
    params: {
      promotionCode: 'GAME_EVENT_2024',
      amount: 1000,
    },
  });

  if (!result) {
    console.warn('지원하지 않는 앱 버전이에요.');
  } else if (result === 'ERROR') {
    console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
  } else if ('key' in result) {
    console.log('포인트 지급 성공!', result.key);
  } else if ('errorCode' in result) {
    console.error('포인트 지급 실패:', result.errorCode, result.message);
  }
}
```

```tsx [React]
// webview
import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';

function GrantRewardButton() {
  async function handleClick() {
      const result = await grantPromotionRewardForGame({
        params: {
          promotionCode: 'GAME_EVENT_2024',
          amount: 1000,
        },
      });

      if (!result) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }

      if (result === 'ERROR') {
        console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
        return;
      }

      if ('key' in result) {
        console.log('포인트 지급 성공!', result.key);
      } else if ('errorCode' in result) {
        console.error('포인트 지급 실패:', result.errorCode, result.message);
      }
  }

  return (
    <button onClick={handleClick}>포인트 지급하기</button>
  );
}
```

```tsx [React Native]
// react-native
import { Button } from 'react-native';
import { grantPromotionRewardForGame } from '@apps-in-toss/framework';

function GrantRewardButton() {
  async function handlePress() {
      const result = await grantPromotionRewardForGame({
        params: {
          promotionCode: 'GAME_EVENT_2024',
          amount: 1000,
        },
      });

      if (!result) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }

      if (result === 'ERROR') {
        console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
        return;
      }

      if ('key' in result) {
        console.log('포인트 지급 성공!', result.key);
      } else if ('errorCode' in result) {
        console.error('포인트 지급 실패:', result.errorCode, result.message);
      }
  }

  return <Button onPress={handlePress} title="포인트 지급하기" />;
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/토스페이/CheckoutPaymentResult.md
---

# 결제 결과 반환

## `CheckoutPaymentResult`

`CheckoutPaymentResult` 는 토스페이 결제창에서 사용자가 인증에 성공했는지 여부예요.

## 시그니처

```typescript
interface CheckoutPaymentResult {
  success: boolean;
  reason?: string;
}
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/토스페이/CheckoutPaymentOptions.md
---

# 결제 옵션

## `CheckoutPaymentOptions`

`CheckoutPaymentOptions` 는 토스페이 결제창을 띄울 때 필요한 옵션이에요.

## 시그니처

```typescript
interface CheckoutPaymentOptions {
  payToken: string;
}
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/토스페이/checkoutPayment.md
---

# 결제 인증 실행하기

## `checkoutPayment`

`checkoutPayment` 함수는 토스페이 결제창을 띄우고, 사용자 인증을 수행해요. 인증이 완료되면 성공 여부를 반환해요.

이 함수는 결제창을 통해 사용자 인증만 해요. 실제 결제 처리는 인증 성공 후 서버에서 별도로 해야 해요.

## 시그니처

```typescript
function checkoutPayment(options: CheckoutPaymentOptions): Promise<CheckoutPaymentResult>;
```

### 파라미터

### 반환 값

## 예제

### 토스페이 결제창 띄우고 인증 처리하기

::: code-group

```js [js]
import { checkoutPayment } from '@apps-in-toss/web-framework';

async function handleCheckoutPayment() {
  try {
    // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
    const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());
    const { success, reason } = await checkoutPayment({ payToken });

    if (success) {
      // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
      await fetch('/my-api/payment/execute', {
        method: 'POST',
        body: JSON.stringify({ payToken }),
        headers: { 'Content-Type': 'application/json' },
      });
      console.log('결제 성공');
    } else {
      console.log('인증 실패:', reason);
    }
  } catch (error) {
    console.error('결제 인증 중 오류가 발생했어요:', error);
  }
}
```

```tsx [React]
import { checkoutPayment } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function TossPayButton() {
  async function handlePayment() {
    try {
      // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
      const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());

      const { success, reason } = await checkoutPayment({ payToken });

      if (success) {
        // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
        await fetch('/my-api/payment/execute', {
          method: 'POST',
          body: JSON.stringify({ payToken }),
          headers: { 'Content-Type': 'application/json' },
        });
        console.log('결제 성공');
      } else {
        console.log('인증 실패:', reason);
      }
    } catch (error) {
      console.error('결제 인증 중 오류가 발생했어요:', error);
    }
  }

  return <Button onClick={handlePayment}>결제하기</Button>;
}
```

```tsx [React Native]
import { TossPay } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function TossPayButton() {
  async function handlePayment() {
    try {
      // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
      const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());

      const { success, reason } = await TossPay.checkoutPayment({ payToken });

      if (success) {
        // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
        await fetch('/my-api/payment/execute', {
          method: 'POST',
          body: JSON.stringify({ payToken }),
          headers: { 'Content-Type': 'application/json' },
        });
        console.log('결제 성공');
      } else {
        console.log('인증 실패:', reason);
      }
    } catch (error) {
      console.error('결제 인증 중 오류가 발생했어요:', error);
    }
  }

  return <Button onPress={handlePayment}>결제하기</Button>;
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인앱
  결제/createOneTimePurchaseOrder.md
---

# 결제하기

## `createOneTimePurchaseOrder`

`createOneTimePurchaseOrder` 함수는 인앱 결제 결제창을 띄우고, 사용자가 결제를 진행해요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.

## 시그니처

```typescript
function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;
```

### 파라미터

```typescript

interface IapCreateOneTimePurchaseOrderOptions {
  options: {sku: string; processProductGrant: (params: { orderId: string }) => boolean | Promise<boolean> };
  onEvent: (event: SuccessEvent) => void | Promise<void>;
  onError: (error: unknown) => void | Promise<void>;
}

interface IapCreateOneTimePurchaseOrderResult {
  orderId: string;
  displayName: string;
  displayAmount: string;
  amount: number;
  currency: string;
  fraction: number;
  miniAppIconUrl: string | null;
}

interface SuccessEvent {
  type: 'success';
  data: IapCreateOneTimePurchaseOrderResult;
}
```

### 에러코드

## 반환값

## 예제

### 특정 인앱결제 주문서 페이지로 이동하기

::: code-group

```js [js]
import { IAP } from "@apps-in-toss/web-framework";

let cleanup; 

function handleBuyProduct(sku) {
  cleanup = IAP.createOneTimePurchaseOrder({
    options: {
      sku,
      processProductGrant: ({ orderId }) => {
        console.log('상품 지급 로직 실행:', orderId);
        return true;
      },
    },
    onEvent: (event) => {
      console.log('이벤트:', event);
      cleanup?.();
    },
    onError: (error) => {
      console.error('인앱결제에 실패했어요:', error);
      cleanup?.();
    },
  });
}

window.addEventListener('pagehide', () => {
  cleanup?.();
});
```

```tsx [React]
import { IAP } from "@apps-in-toss/web-framework";
import { Button } from "@toss/tds-mobile";
import { useCallback } from "react";
 
interface Props {
  sku: string;
}
 
function IapCreateOneTimePurchaseOrderButton({ sku }: Props) { 
  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
      },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  return <Button onClick={handleBuy}>구매하기</Button>;
}
```

```tsx [React Native]
import { IAP } from "@apps-in-toss/framework";
import { Button } from "@toss/tds-react-native";
import { useCallback } from "react";
 
interface Props {
  sku: string;
}
 
function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
  const handleClick = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
        },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, []);

  return <Button onPress={handleClick}>구매하기</Button>;
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-in-app-purchase](https://github.com/toss/apps-in-toss-examples/tree/main/with-in-app-purchase) 코드를 내려받아 체험해 보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/growth/share.md'
description: >-
  앱인토스 공유 기능을 통한 바이럴 효과 가이드입니다. 공유하기 기능과 공유 리워드를 활용해 자연스러운 사용자 확산을 만드는 방법을
  확인하세요.
---

# 공유 기능으로 바이럴 효과 만들기

지인에게 서비스를 공유하는 기능은 강력한 신뢰를 기반으로 **더 높은 유입률과 리텐션**을 만들 수 있어요.\
**기존 사용자가 지인에게 서비스를 공유하는 바이럴 기능을** 통해 토스에서 장기적인 성장의 기반을 만들어보세요.

***

## 왜 공유하기를 통한 바이럴 효과가 중요한가요?

공유하기는 **높은 신뢰도와 함께 광고보다 진입 장벽이 낮아 효과적인 사용자 유입 수단**으로 이용될 수 있어요.\
또한, 추가적인 마케팅 비용 없이도 서비스 지속 확산이 가능해서 사용자 획득 비용을 낮출 수 있어요.

토스팀에서도 다양한 ‘공유 기능 및 이벤트’를 제공하여 많은 사용자가 서비스를 공유하도록 유도하고 있어요.\
공유를 통해 들어온 사용자는 **서비스에 더 오래 머물고, 다시 찾을 가능성도 높아져요.**

![](/assets/growth_share_1.Dbe0XTcf.png)

## 토스 기능으로 바이럴 효과 만들기

### ① 공유하기

::: tip 공유하기
공유하기는 화면 최상단에서 토스에서 사용가능한 여러 기능을 안내하는 내비게이션 바에서 제공되는 기능이에요.\
[내비게이션 바 가이드 바로가기](/bedrock/reference/framework/UI/NavigationBar.md)
:::

내비게이션 바의 \[더보기] 영역에서 공유하기 기능을 제공해요.\
상단에 반드시 배치되는 공유하기 기능을 이용해 사용자가 서비스를 공유할 수 있도록 바이럴을 만들 수 있어요.

![](/assets/growth_share_2.Zr3Jp8zF.png)

### ② 게임 공유 리워드

::: tip 게임 공유 리워드
공유 리워드는 연락처 모듈을 통해 토스를 사용하는 유저의 연락처를 불러오며 공유한 유저에게 리워드를 제공하는 기능이에요.\
[공유 리워드 가이드 바로가기](/reward/intro.md)
:::

공유한 사용자에게 **리워드라는** **강력한 공유 동기**를 제공해 지인을 초대하도록 유도할 수 있어요.\
서비스 내 재화를 제공하는 기능임에 따라 **별도 비용 없이 효과적인 마케팅 효과**를 만들 수 있어요.

연락처 모듈을 활용하면 토스 사용자의 연락처를 모두 불러오기 때문에 더 넓은 풀에서 바이럴을 진행할 수 있어요.

![](/assets/growth_share_3.BzZs-HkP.png)

### ③ 게임 리더보드

::: tip 게임 리더보드
리더보드는 유저들의 게임 점수를 기반으로 랭킹을 제공하는 기능이에요.\
유저는 리더보드를 통해 친구를 맺을 수 있고 친구에게 점수를 공유할 수 있어요.\
[리더보드 가이드 바로가기](/game-center/intro.md)
:::

사용자는 **리더보드**를 통해 **친구에게 점수와 함께 게임 서비스를 공유**할 수 있어요.\
**점수**를 공유하는 과정에서 **경쟁심을 자극**하여 **잠재 사용자의 참여율을 높이고** 강력한 바이럴을 만들 수 있어요.

또한 리더보드의 경우 앞으로 푸시, 토스 앱 내 노출 등 여러가지 기능이 추가되어 더욱 고도화될 예정이에요.

![](/assets/growth_share_4.hw46lkKx.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/친구초대/contactsViral.md
---

# 공유 리워드

## `contactsViral`

`contactsViral` 함수는 친구에게 공유하고 리워드를 받을 수 있는 기능을 제공해요. 사용자가 친구에게 공유를 완료하면, 앱 브릿지를 통해 이벤트가 전달되고, 해당 이벤트를 기반으로 리워드 정보를 받을 수 있어요.

::: tip 주의하세요

* 본 기능은 토스앱 5.223.0 버전부터 지원해요. 하위 버전에서는 `undefined`가 반환됩니다.
* 기능 사용을 위해서는 미니앱 승인이 반드시 필요합니다. 미승인 상태에서는 `Internal Server Error`가 발생합니다.

:::

::: tip 참고하세요

* 테스트 환경(샌드박스 앱)에서는 빈 화면으로 보여요. 리워드 지급 버튼을 눌러도 실제로 동작하지 않아요.
* 콘솔 내 QR코드로 테스트를 진행해 주세요.
* 콘솔에 등록된 리워드 ID를 활용하여 테스트를 할 수 있어요.
* 친구 목록은 상호 연락처 저장 여부 외에도 다음 조건에 따라 달라질 수 있어요
  * 마케팅 수신 동의 여부
  * 야간 마케팅 수신 동의 여부
  * 푸시 토큰 등록 여부
  * 연락처 알림 차단 여부
    :::

### 시그니처

```ts
function contactsViral(params: ContactsViralParams): () => void;
```

### 파라미터

### 반환값

### 예제

::: code-group

```js [js]
import { contactsViral } from '@apps-in-toss/web-framework';

function handleContactsViral(moduleId) {
  const cleanup = contactsViral({
    options: { moduleId: moduleId.trim() },
    onEvent: (event) => {
      if (event.type === 'sendViral') {
        console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
      } else if (event.type === 'close') {
        console.log('모듈 종료:', event.data.closeReason);
        cleanup();
      }
    },
    onError: (error) => {
      console.error('에러 발생:', error);
      cleanup?.();
    },
  });
}
```

```tsx [React]
import { contactsViral } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';
import { useCallback } from 'react';

function ContactsViralButton({ moduleId }: { moduleId: string }) {
  const handleContactsViral = useCallback(() => {
    try {
      const cleanup = contactsViral({
        options: { moduleId: moduleId.trim() },
        onEvent: (event) => {
          if (event.type === 'sendViral') {
            console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
          } else if (event.type === 'close') {
            console.log('모듈 종료:', event.data.closeReason);
            cleanup();
          }
        },
        onError: (error) => {
          console.error('에러 발생:', error);
          cleanup?.();
        },
      });
    } catch (error) {
      console.error('실행 중 에러:', error);
    }
  }, [moduleId]);

  return <Button onClick={handleContactsViral}>친구에게 공유하고 리워드 받기</Button>;
}
```

```tsx [React Native]
import { contactsViral } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';
import { useCallback } from 'react';

function ContactsViralButton({ moduleId }: { moduleId: string }) {
  const handleContactsViral = useCallback(() => {
    try {
      const cleanup = contactsViral({
        options: { moduleId: moduleId.trim() },
        onEvent: (event) => {
          if (event.type === 'sendViral') {
            console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
          } else if (event.type === 'close') {
            console.log('모듈 종료:', event.data.closeReason);
            cleanup();
          }
        },
        onError: (error) => {
          console.error('에러 발생:', error);
          cleanup?.();
        },
      });
    } catch (error) {
      console.error('실행 중 에러:', error);
    }
  }, [moduleId]);

  return <Button onPress={handleContactsViral}>친구에게 공유하고 리워드 받기</Button>;
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-contacts-viral](https://github.com/toss/apps-in-toss-examples/tree/main/with-contacts-viral) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

## `ContactsViralOption`

`ContactsViralOption`는 [연락처 공유 기능](/bedrock/reference/framework/친구초대/contactsViral.md)을 사용할 때 필요한 옵션이에요.

### 시그니처

```ts
type ContactsViralOption = {
  moduleId: string;
};
```

### 프로퍼티

## `ContactsViralParams`

`ContactsViralParams` 는 `contactsViral` 함수를 실행할 때 사용하는 파라미터 타입이에요. 옵션을 설정하고, 이벤트 및 에러 처리 콜백을 지정할 수 있어요.

### 시그니처

```ts
interface ContactsViralParams {
  options: ContactsViralOption;
  onEvent: (event: ContactsViralEvent) => void;
  onError: (error: unknown) => void;
}
```

### 프로퍼티

## `ContactsViralSuccessEvent`

`ContactsViralSuccessEvent` 는 연락처 공유 모듈이 정상적으로 종료됐을 때 전달되는 이벤트 객체예요. 종료 이유와 함께 리워드 상태 및 남은 친구 수 등 관련 정보를 제공해요.

### 시그니처

```ts
type ContactsViralSuccessEvent = {
  type: 'close';
  data: {
    closeReason: 'clickBackButton' | 'noReward';
    sentRewardAmount?: number;
    sendableRewardsCount?: number;
    sentRewardsCount: number;
    rewardUnit?: string;
  };
};
```

### 프로퍼티

### 예제

모듈 종료 이벤트 처리하기

```ts
contactsViral({
  options: { moduleId: 'your-module-id' },
  onEvent: (event) => {
    if (event.type === 'close') {
      console.log('종료 사유:', event.data.closeReason);
      console.log('공유 완료한 친구 수:', event.data.sentRewardsCount);
    }
  },
  onError: (error) => {
    console.error('에러 발생:', error);
  },
});
```

## `RewardFromContactsViralEvent`

`RewardFromContactsViralEvent` 는 친구에게 공유하기를 완료했을 때 지급할 리워드 정보를 담는 타입이에요. 이 타입을 사용하면 공유가 완료됐을 때 지급할 리워드 정보를 확인할 수 있어요.

### 시그니처

```ts
type RewardFromContactsViralEvent = {
  type: 'sendViral';
  data: {
    rewardAmount: number;
    rewardUnit: string;
  };
};
```

### 프로퍼티

### 예제

공유 완료 후 리워드 정보 처리하기

```ts
contactsViral({
  options: { moduleId: 'your-module-id' },
  onEvent: (event) => {
    if (event.type === 'sendViral') {
      console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
    }
  },
  onError: (error) => {
    console.error('에러 발생:', error);
  },
});
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/친구초대/RewardFromContactsViralEvent.md
---

# 공유 완료 리워드 정보 이벤트

## `RewardFromContactsViralEvent`

`RewardFromContactsViralEvent` 는 친구에게 공유하기를 완료했을 때 지급할 리워드 정보를 담는 타입이에요. 이 타입을 사용하면 공유가 완료됐을 때 지급할 리워드 정보를 확인할 수 있어요.

## 시그니처

```ts
type RewardFromContactsViralEvent = {
  type: 'sendViral';
  data: {
    rewardAmount: number;
    rewardUnit: string;
  };
};
```

### 프로퍼티

## 예제

### 공유 완료 후 리워드 정보 처리하기

```ts
contactsViral({
  options: { moduleId: 'your-module-id' },
  onEvent: (event) => {
    if (event.type === 'sendViral') {
      console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
    }
  },
  onError: (error) => {
    console.error('에러 발생:', error);
  },
});
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/Config.md
---

# 공통 설정

미니앱에서 공통으로 사용하는 **브랜드, 호스트, 권한, 빌드 옵션** 등의 전역 설정을 한 곳에서 관리할 수 있어요.\
아래 예제는 **WebView**와 **React Native** 환경에서 사용할 수 있는 기본 설정 템플릿이에요.

기본 설정을 적용하면 **내비게이션 바**가 자동으로 표시돼요.\
내비게이션 바의 **더보기 버튼**을 통해 공유하기, 신고하기 등의 기능을 쉽게 사용할 수 있어요.\
별도 서버 연동이나 추가 구현 없이 SDK만 적용하면 바로 사용 가능해요.

::: tip SDK 1.6.1 버전부터는 bridgeColorMode 설정은 불필요해요
SDK 1.6.1 버전부터는내부 운영 정책 변경으로 브릿지 뷰 기능이 제거되었어요.\
브릿지 뷰의 색상 모드를 설정하던 `bridgeColorMode` 는 불필요해요.
:::

## WebView 설정

* `appName` : 콘솔에 등록한 앱 ID를 입력해 주세요.
* `displayName` : 사용자에게 노출될 앱 이름을 입력해 주세요. 콘솔에 등록된 이름과 동일하게 입력해야 해요.
* `primaryColor` : 앱의 기본 색상 값을 지정해 주세요. 지정한 색상은 버튼 등에 적용돼요.
* `icon` : 앱의 로고 이미지 URL을 입력해 주세요. 콘솔의 앱 정보에서 업로드한 이미지를 우클릭해 링크 복사 후 넣어 주세요.
* `permissions` : 권한이 필요한 경우 설정해 주세요. [필요한 권한 설정하기](/bedrock/reference/framework/권한/permission.md) 문서를 참고해 주세요.
* `webViewProps.type` : 미니앱에 맞게 내비게이션 바를 설정할 수 있어요.
  * 게임 : `game`
  * 비게임 : `partner`

::: code-group

```typescript [게임]
interface defineConfig {
  appName: string; // 콘솔에 등록한 앱ID
  brand: {
    displayName: string; // 사용자에게 노출될 앱 이름
    primaryColor: string; // 브랜드 기본 색상(hex)
    icon: string; // 앱 아이콘(이미지 웹 URL)
  };
  web: {
    host: string; // 개발 서버 호스트
    port: number; // 개발 서버 포트
    commands: {
      dev: string; // 실행 명령어
      build: string; // 빌드 명령어
    };
  };
  permissions: Permission[]; // 런타임 권한(필요 시 확장)
  outdir: string; // 빌드 산출물 경로
  webViewProps: {
    type: 'game'; // 게임 내비게이션 // [!code highlight]
  };
}
```

```typescript [비게임]
interface defineConfig {
  appName: string; // 콘솔에 등록한 앱ID
  brand: {
    displayName: string; // 사용자에게 노출될 앱 이름
    primaryColor: string; // 브랜드 기본 색상(hex)
    icon: string; // 앱 아이콘(이미지 웹 URL)
  };
  web: {
    host: string; // 개발 서버 호스트
    port: number; // 개발 서버 포트
    commands: {
      dev: string; // 실행 명령어
      build: string; // 빌드 명령어
    };
  };
  permissions: Permission[]; // 런타임 권한(필요 시 확장)
  outdir: string; // 빌드 산출물 경로
  webViewProps: {
    type: 'partner'; // 비게임 // [!code highlight]
  };
}
```

```tsx [예시]
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'webview-template',
  brand: {
    displayName: '웹뷰템플릿',
    primaryColor: '#3182F6',
    icon: 'https://static.toss.im/icons/png/4x/icon-person-man.png',
  },
  web: {
    host: 'localhost',
    port: 5173,
    commands: {
      dev: 'vite',
      build: 'tsc -b && vite build',
    },
  },
  permissions: [
    {
      name: 'clipboard',
      access: 'read',
    },
    {
      name: 'clipboard',
      access: 'write',
    },
    {
      name: 'camera',
      access: 'access',
    },
    {
      name: 'photos',
      access: 'read',
    },
  ],
  outdir: 'dist',
  webViewProps: {
    type: 'partner' | 'game' | 'extenral',
  },
});
```

:::

## React Native 설정

* `scheme` : 앱 라우팅 스킴을 입력해 주세요. `intoss`로 입력하면 돼요.
* `appName` : 콘솔에 등록한 앱 ID를 입력해 주세요.
* `displayName` : 사용자에게 노출될 앱 이름을 입력해 주세요. 콘솔에 등록된 이름과 동일하게 입력해야 해요.
* `primaryColor` : 앱의 기본 색상 값을 지정해 주세요. 지정한 색상은 버튼 등에 적용돼요.
* `icon` : 앱의 로고 이미지 URL을 입력해 주세요. 콘솔의 앱 정보에서 업로드한 이미지를 우클릭해 링크 복사 후 넣어 주세요.
* `permissions` : 권한이 필요한 경우 설정해 주세요. [필요한 권한 설정하기](/bedrock/reference/framework/권한/permission.md) 문서를 참고해 주세요.

::: code-group

```typescript [게임]
interface defineConfig({
  scheme: string,            // 앱 라우팅 스킴 (intoss)
  appName: string,           // 콘솔에 등록한 앱ID
  plugins: [
    appsInToss({
      brand: {
        displayName: string,  // 사용자에게 노출될 앱 이름
        primaryColor: string, // 브랜드 기본 색상(hex)
        icon: string,         // 앱 아이콘(이미지 웹 URL)
      },
      permissions: Permission[], // 런타임 권한(필요 시 확장)
    }),
  ],
});

```

```typescript [비게임]
interface defineConfig({
  scheme: string,            // 앱 라우팅 스킴 (intoss)
  appName: string,           // 콘솔에 등록한 앱ID
  plugins: [
    appsInToss({
      brand: {
        displayName: string,  // 사용자에게 노출될 앱 이름
        primaryColor: string, // 브랜드 기본 색상(hex)
        icon: string,         // 앱 아이콘(이미지 웹 URL)
      },
      permissions: Permission[], // 런타임 권한(필요 시 확장)
    }),
  ],
});

```

```tsx [예시]
import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  scheme: 'intoss',
  appName: 'rn-template',
  plugins: [
    appsInToss({
      brand: {
        displayName: 'rn-template',
        primaryColor: '#3182F6',
        icon: 'https://static.toss.im/icons/png/4x/icon-person-man.png',
      },
      permissions: [
        {
          name: 'clipboard',
          access: 'read',
        },
        {
          name: 'clipboard',
          access: 'write',
        },
        {
          name: 'camera',
          access: 'access',
        },
        {
          name: 'photos',
          access: 'read',
        },
      ],
    }),
  ],
});
```

:::

## 환경 변수 설정 (React Native)

React Native 미니앱에서 **빌드 시점에 환경 변수를 주입해야 하는 경우** `plugin-env` 플러그인을 사용할 수 있어요.

* `import.meta.env` 형태로 접근할 수 있어요.
* `granite.config.ts`에서만 설정할 수 있어요.

자세한 설정 방법은 [환경 변수 설정 문서](/bedrock/reference/framework/UI/Config.md)를 참고해 주세요.

## 내비게이션 바 (게임)

화면 상단에 고정되는 영역으로, 앱인토스 전용 컴포넌트가 제공돼요.\
게임용 내비게이션 바는 **투명한 배경**에 **더보기 버튼**과 **닫기(X) 버튼**으로 구성돼요.

::: tip 주의해주세요

* X 버튼이 게임 화면의 다른 버튼과 겹치지 않도록 개발해 주세요.
  * [safeArea](/bedrock/reference/framework/화면%20제어/safe-area.md) 문서를 참고하세요.
* X 버튼을 눌렀을 때는 종료 확인 모달을 반드시 표시해 주세요.
  * 텍스트 : `$서비스명$을 종료할까요?`
  * 버튼 : `취소` / `종료하기` (브랜드 컬러 적용)

:::

![](/assets/thumbnail-navigation-game.D4C6-eQu.png)

## 내비게이션 바 (비게임)

비게임 미니앱에서는 흰색 배경의 내비게이션 바가 기본으로 제공돼요.\
좌측에는 미니앱 로고와 이름이, 우측에는 더보기 버튼과 X 버튼이 위치해요.

또한, 더보기 버튼 왼쪽에 아이콘을 한 개 추가할 수 있어요.\
자세한 내용은 [내비게이션 바 설정](/bedrock/reference/framework/UI/NavigationBar.md) 문서를 참고해 주세요.

![](/assets/thumbnail-navigation-nongame.Dqi4C07P.png)

## 내비게이션 바 기능

내비게이션 바의 **더보기 버튼**을 통해 **공유하기, 신고하기** 등의 기능을 쉽게 사용할 수 있어요.\
별도 서버 연동이나 추가 구현 없이, **SDK만 적용하면 바로 사용할 수 있어요.**\
**게임, 비게임 구분 없이 WebView와 React Native 환경 모두 동일하게 동작해요.**

### 문의하기 / 신고하기

콘솔에 등록한 **고객센터 링크와 홈페이지 주소**가 자동으로 표시돼요.\
신고하기 기능을 통해 사용자가 제보를 보낼 수 있고, 파트너사는 콘솔을 통해 제보 내용을 확인할 수 있어요.

![](/assets/nav_declare.wr-d3eJN.png)

### 공유하기

**공유하기** 기능을 통해 사용자는 미니앱을 다른 사람에게 쉽게 공유할 수 있어요.\
공유 시 **미니앱 이름**과 **딥링크 주소**가 함께 전송돼요.

![](/assets/nav_share.C1afpEQo.png)

### 권한 설정

**권한 설정** 기능을 통해 사용자는 미니앱이 요청하는 권한을 확인하고, 언제든지 ON/OFF로 제어할 수 있어요.

![](/assets/nav_permission.C863hU5a.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/AdMobFullScreenEvent.md
---

# 광고 공통 이벤트 타입

## `AdMobFullScreenEvent`

`AdMobFullScreenEvent`는 앱 화면을 덮는 광고(예: 전면 광고, 보상형 광고)를 사용하는 경우에 발생하는 이벤트 타입이에요.

## 시그니처

```typescript
type AdMobFullScreenEvent = AdClicked | AdDismissed | AdFailedToShow | AdImpression | AdShow;
```

## 예제

### 광고 이벤트 처리하기

```ts
function handleEvent(event: AdMobFullScreenEvent) {
  switch (event.type) {
    case 'clicked':
      console.log('광고가 클릭됐어요.');
      break;

    case 'dismissed':
      console.log('광고가 닫혔어요.');
      break;

    case 'failedToShow':
      console.log('광고가 보여지지 않았어요.');
      break;

    case 'impression':
      console.log('광고가 노출됐어요.');
      break;

    case 'show':
      console.log('광고가 보여졌어요.');
      break;
  }
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/AdNetworkResponseInfo.md
---

# 광고 네트워크 응답 객체

## `AdNetworkResponseInfo`

`AdNetworkResponseInfo` 는 광고 네트워크 응답 정보를 담고 있는 객체예요.

## 시그니처

```typescript
interface AdNetworkResponseInfo {
  adSourceId: string;
  adSourceName: string;
  adSourceInstanceId: string;
  adSourceInstanceName: string;
  adNetworkClassName: string | null;
}
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/ResponseInfo.md
---

# 광고 로드 응답 객체

## `ResponseInfo`

`ResponseInfo` 는 광고 로드 응답 정보를 담고 있는 객체예요.

## 시그니처

```typescript
interface ResponseInfo {
  adNetworkInfoArray: Array<AdNetworkResponseInfo>;
  loadedAdNetworkInfo: AdNetworkResponseInfo | null;
  responseId: string | null;
}
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/showAdMobInterstitialAd.md
---

# 광고 보여주기

## `showAdMobInterstitialAd`

> ⚠️ **Deprecated**\
> 이 함수는 곧 제거될 예정이에요. 대신 [`showAppsInTossAdMob`](./showAppsInTossAdMob.html)을 사용해주세요.

`showAdMobInterstitialAd` 함수는 앱 화면 전체를 덮는 전면 광고를 사용자에게 노출해요. 이 함수는 `loadAdMobInterstitialAd` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.

## 시그니처

```typescript
function showAdMobInterstitialAd(params: ShowAdMobInterstitialAdParams): typeof noop;
```

### 파라미터

### 프로퍼티

## 예제

### 버튼 눌러 불러온 전면 광고 보여주기

::: code-group

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text, View } from '@toss/tds-mobile';
import { useCallback, useEffect, useState } from 'react';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobInterstitialAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
  const navigate = useNavigate();

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            navigate({ to: '/' });
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, [navigation]);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  useEffect(() => {
    const cleanup = loadAd();
    return cleanup;
  }, [loadAd]);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button size="medium" onClick={showAd} disabled={adLoadStatus !== 'loaded'}>Show Ad</Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useFocusEffect } from '@granite-js/native/@react-navigation/native';
import { Button, Text } from "@toss/tds-react-native";
import { useCallback, useState } from 'react';
import { View } from 'react-native';
import { useNavigation } from '@granite-js/react-native';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobInterstitialAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
  const navigation = useNavigation();

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            navigation.navigate('/examples/google-admob-interstitial-ad-landing');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, [navigation]);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  useFocusEffect(loadAd);

  return (
    <View>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button onPress={showAd} disabled={adLoadStatus !== 'loaded'}>Show Ad</Button>
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-interstitial-ad](https://github.com/toss/apps-in-toss-examples/tree/main/with-interstitial-ad) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/showAdMobRewardedAd.md
---

# 광고 보여주기

## `showAdMobRewardedAd`

> ⚠️ **Deprecated**\
> 이 함수는 곧 제거될 예정이에요. 대신 [`showAppsInTossAdMob`](./showAppsInTossAdMob.html)을 사용해주세요.

`showAdMobRewardedAd` 함수는 사용자가 광고를 끝까지 보면 리워드를 받을 수 있도록, 보상형 광고를 화면에 보여줘요. 이 함수는 `loadAdMobRewardedAd` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.

## 시그니처

```typescript
function showAdMobRewardedAd(params: ShowAdMobRewardedAdParams): typeof noop;
```

### 파라미터

### 프로퍼티

## 예제

### 버튼 눌러 불러온 보상형 광고 보여주기

::: code-group

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useCallback, useState } from 'react';

const AD_UNIT_ID = '<AD_UNIT_ID>';

export default function GoogleAdmobRewardedAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;

          case 'userEarnedReward':
            console.log('사용자가 광고 시청을 완료했음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onClick={loadAd}>
        광고 로드
      </Button>
      <Button title="Show Ad" onClick={showAd} disabled={adLoadStatus !== 'loaded'}>
        광고 보여주기
      </Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobRewardedAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;

          case 'userEarnedReward':
            console.log('사용자가 광고 시청을 완료했음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <View>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onPress={loadAd} />
      <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-rewarded-ad](https://github.com/toss/apps-in-toss-examples/tree/main/with-rewarded-ad) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/showAppsInTossAdMob.md
---

# 광고 보여주기

## `showAppsInTossAdMob`

광고를 사용자에게 노출해요. 이 함수는 `loadAppsInTossAdMob` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.

### 시그니처

```typescript
function showAppsInTossAdMob(params: ShowAdMobParams): typeof noop;
```

### 파라미터

### 프로퍼티

### 예제

버튼 눌러 불러온 광고 보여주기

::: code-group

```js [js]
import { GoogleAdMob } from '@apps-in-toss/web-framework';

const AD_GROUP_ID = '<AD_GROUP_ID>';

const showAdButton = document.getElementById('show-ad-button');
showAdButton.addEventListener("click", () => {
  const cleanup = GoogleAdMob.loadAppsInTossAdMob({
    options: {
      adGroupId: AD_GROUP_ID,
    },
    onEvent: (event) => {
      switch (event.type) {
        case 'loaded':
          console.log('광고 로드 성공', event.data);
          cleanup();
          GoogleAdMob.showAppsInTossAdMob({
            options: {
              adGroupId: AD_GROUP_ID,
            },
            onEvent: (event) => {
              switch (event.type) {
                case 'show':
                  console.log('광고 컨텐츠 보여졌음');
                  break;
                case 'requested':
                  console.log('광고 보여주기 요청 완료');
                  break;
                case 'impression':
                  console.log('광고 노출');
                  break;
                case 'clicked':
                  console.log('광고 클릭');
                  break;
                case 'userEarnedReward':  // 보상형 광고만 사용 가능
                  console.log('광고 보상 획득 unitType:', event.data.unitType);
                  console.log('광고 보상 획득 unitAmount:', event.data.unitAmount);
                  break;
                case 'dismissed':
                  console.log('광고 닫힘');
                  break;
                case 'failedToShow':
                  console.log('광고 보여주기 실패');
                  break;
              }
            },
            onError: (error) => {
              console.error('광고 보여주기 실패', error);
            },
          });
          break;
      }
    },
    onError: (error) => {
      console.error('광고 불러오기 실패', error);
      cleanup?.();
    },
  });
})
```

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useCallback, useState } from 'react';

const AD_GROUP_ID = '<AD_GROUP_ID>';

function GoogleAdmobExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAppsInTossAdMob({
      options: {
        adGroupId: AD_GROUP_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            cleanup();
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
        cleanup?.();
      },
    });
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAppsInTossAdMob.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAppsInTossAdMob({
      options: {
        adGroupId: AD_GROUP_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
          case 'impression':
            console.log('광고 노출');
            break;
          case 'clicked':
            console.log('광고 클릭');
            break;
          case 'userEarnedReward': // 보상형 광고만 사용 가능
            console.log('광고 보상 획득 unitType:', event.data.unitType);
            console.log('광고 보상 획득 unitAmount:', event.data.unitAmount);
            break;
          case 'dismissed':
            console.log('광고 닫힘');
            break;
          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onClick={loadAd}>
        광고 로드
      </Button>
      <Button title="Show Ad" onClick={showAd} disabled={adLoadStatus !== 'loaded'}>
        광고 보여주기
      </Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useFocusEffect } from '@granite-js/native/@react-navigation/native';
import { useNavigation } from '@granite-js/react-native';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';

const AD_GROUP_ID = '<AD_GROUP_ID>';

export function GoogleAdmobExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
  const navigation = useNavigation();

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAppsInTossAdMob({
      options: {
        adGroupId: AD_GROUP_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            cleanup();
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
        cleanup?.();
      },
    });
  }, [navigation]);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAppsInTossAdMob.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAppsInTossAdMob({
      options: {
        adGroupId: AD_GROUP_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            break;
          case 'impression':
            console.log('광고 노출');
            break;
          case 'clicked':
            console.log('광고 클릭');
            break;
          case 'userEarnedReward': // 보상형 광고만 사용 가능
            console.log('광고 보상 획득 unitType:', event.data.unitType);
            console.log('광고 보상 획득 unitAmount:', event.data.unitAmount);
            break;
          case 'dismissed':
            console.log('광고 닫힘');
            navigation.navigate('/examples/google-admob-interstitial-ad-landing');
            break;
          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  useFocusEffect(loadAd);

  return (
    <View>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
    </View>
  );
}
```

:::

## `ShowAdMobParams`

`ShowAdMobParams` 는 불러온 광고를 보여주는 함수에 필요한 옵션 객체예요.

### 시그니처

```typescript
type ShowAdMobParams = AdMobHandlerParams<ShowAdMobOptions, ShowAdMobEvent>;
```

## `ShowAdMobEvent`

`ShowAdMobEvent` 는 광고를 보여주는 함수에서 발생하는 이벤트 타입이에요. `requested` 이벤트가 발생하면 광고 노출 요청이 Google AdMob에 성공적으로 전달된 거예요.

### 시그니처

```typescript
type ShowAdMobEvent =
  | { type: 'requested' }
  | { type: 'clicked' }
  | { type: 'dismissed' }
  | { type: 'failedToShow' }
  | { type: 'impression' }
  | { type: 'show' }
  | {
      type: 'userEarnedReward'; // 보상형 광고만 사용 가능
      data: {
        unitType: string;
        unitAmount: number;
      };
    };
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/loadAdMobRewardedAd.md
---

# 광고 불러오기

## `loadAdMobRewardedAd`

> ⚠️ **Deprecated**\
> 이 함수는 곧 제거될 예정이에요. 대신 [`loadAppsInTossAdMob`](./loadAppsInTossAdMob.html)을 사용해주세요.

`loadAdMobRewardedAd` 는 사용자가 광고를 끝까지 시청하면 리워드를 제공할 수 있는 보상형 광고를 미리 불러와서, 광고가 필요한 시점에 바로 보여줄 수 있도록 준비하는 함수예요.

## 시그니처

```typescript
function loadAdMobRewardedAd(params: LoadAdMobRewardedAdParams): typeof noop;
```

### 파라미터

### 프로퍼티

## 예제

### 버튼 눌러 불러온 보상형 광고 보여주기

::: code-group

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useCallback, useState } from 'react';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobRewardedAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;

          case 'userEarnedReward':
            console.log('사용자가 광고 시청을 완료했음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onClick={loadAd}>
        광고 로드
      </Button>
      <Button title="Show Ad" onClick={showAd} disabled={adLoadStatus !== 'loaded'}>
        광고 보여주기
      </Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobRewardedAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;

          case 'userEarnedReward':
            console.log('사용자가 광고 시청을 완료했음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <View>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onPress={loadAd} />
      <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-rewarded-ad](https://github.com/toss/apps-in-toss-examples/tree/main/with-rewarded-ad) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/loadAppsInTossAdMob.md
---

# 광고 불러오기

## `loadAppsInTossAdMob`

`loadAppsInTossAdMob`는 광고를 미리 불러와서, 광고가 필요한 시점에 바로 보여줄 수 있도록 준비하는 함수예요.

### 시그니처

```typescript
function loadAppsInTossAdMob(params: LoadAdMobParams): typeof noop;
```

### 파라미터

### 프로퍼티

### 예제

뷰 진입 시 광고 불러오기

::: code-group

::: code-group

```js [js]
import { GoogleAdMob } from '@apps-in-toss/web-framework';

const AD_GROUP_ID = '<AD_GROUP_ID>';

document.addEventListener('DOMContentLoaded', () => {
  if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
    return;
  }

  const cleanup = GoogleAdMob.loadAppsInTossAdMob({
    options: {
      adGroupId: AD_GROUP_ID,
    },
    onEvent: (event) => {
      console.log(event.type);
      switch (event.type) {
        case 'loaded':
          console.log('광고 로드 성공', event.data);
          adLoadStatus = 'loaded';
          statusText.textContent = '광고 로드 완료';
          cleanup();
          break;
      }
    },
    onError: (error) => {
      console.error('광고 불러오기 실패', error);
      cleanup?.();
    },
  });
});
```

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useCallback, useState } from 'react';

const AD_GROUP_ID = '<AD_GROUP_ID>';

function GoogleAdmobExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
      return;
    }
    
    const cleanup = GoogleAdMob.loadAppsInTossAdMob({
      options: {
        adGroupId: AD_GROUP_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            cleanup();
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
        cleanup?.();
      },
    });
  }, []);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onClick={loadAd}>
        광고 로드
      </Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useEffect } from 'react';
import { View, Text } from 'react-native';
     
const AD_GROUP_ID = '<AD_GROUP_ID>';
     
function GoogleAdmobExample() {
  useEffect(() => {
    if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
      return;
    }
    const cleanup = GoogleAdMob.loadAppsInTossAdMob({
      options: {
        adGroupId: AD_GROUP_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            cleanup();
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
        cleanup?.();
      },
    });
  }, []);
    
  return (
    <View>
      <Text>Page</Text>
    </View>
  );
}
```

:::

## `LoadAdMobParams`

`LoadAdMobParams` 는 광고를 불러오는 함수에 필요한 옵션 객체예요.

### 시그니처

```typescript
type LoadAdMobParams = AdMobHandlerParams<LoadAdMobOptions, LoadAdMobEvent>;
```

## `LoadAdMobEvent`

`LoadAdMobEvent` 는 광고를 불러오는 함수에서 발생하는 이벤트 타입이에요. `loaded` 이벤트가 발생하면 광고를 성공적으로 불러온 거예요.

### 시그니처

```typescript
type LoadAdMobEvent = AdMobFullScreenEvent | {
  type: 'loaded';
};
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/LoadAdMobOptions.md
---

# 광고 옵션 객체

## `LoadAdMobParams`

`LoadAdMobParams` 는 광고를 불러오는 함수에 필요한 옵션 객체예요.

## 시그니처

```typescript
type LoadAdMobParams = AdMobHandlerParams<LoadAdMobOptions, LoadAdMobEvent>;
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/ShowAdMobParams.md
---

# 광고 옵션 객체

## `ShowAdMobParams`

`ShowAdMobParams` 는 불러온 광고를 보여주는 함수에 필요한 옵션 객체예요.

## 시그니처

```typescript
type ShowAdMobParams = AdMobHandlerParams<ShowAdMobOptions, ShowAdMobEvent>;
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/LoadAdMobEvent.md
---

# 광고 이벤트 타입

## `LoadAdMobEvent`

`LoadAdMobEvent` 는 광고를 불러오는 함수에서 발생하는 이벤트 타입이에요. `loaded` 이벤트가 발생하면 광고를 성공적으로 불러온 거예요.

## 시그니처

```typescript
type LoadAdMobEvent = AdMobFullScreenEvent | {
  type: 'loaded';
};
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/ShowAdMobEvent.md
---

# 광고 이벤트 타입

## `ShowAdMobEvent`

`ShowAdMobEvent` 는 광고를 보여주는 함수에서 발생하는 이벤트 타입이에요. `requested` 이벤트가 발생하면 광고 노출 요청이 Google AdMob에 성공적으로 전달된 거예요.

## 시그니처

```typescript
type ShowAdMobEvent =
  | { type: 'requested' }
  | { type: 'clicked' }
  | { type: 'dismissed' }
  | { type: 'failedToShow' }
  | { type: 'impression' }
  | { type: 'show' }
  | {
      type: 'userEarnedReward'; // 보상형 광고만 사용 가능
      data: {
        unitType: string;
        unitAmount: number;
      };
    };
```

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/guide/recommend-engine.md'
---
# 권장 Unity 엔진 버전

앱인토스 미니앱 전환 시 최적의 성능과 안정성을 위해 권장하는 Unity 엔진 버전 가이드예요.

***

## 1. 권장 버전 개요

### 최우선 권장 (Latest Production Ready)

```
Unity 2023.3 LTS
├── 릴리스: 2024년 6월
├── 지원 기간: 2027년까지
├── AppsInToss 지원: 최신 최적화 & 신기능 완전 지원
├── WebGL 성능: 최대 40% 향상
└── 안정성: ★★★★★
```

### 신규 권장 (Latest Features)

```
Unity 2024.2 LTS (예정)
├── 릴리스: 2024년 10월 (베타)
├── 지원 기간: 2028년까지 예정
├── AppsInToss 지원: 실험적 지원 (베타)
├── AI 통합: Unity Muse & Sentis 완전 통합
└── 안정성: ★★★★☆ (베타 단계)
```

### 안정적 최고 권장 (Proven Production Ready)

```
Unity 2022.3 LTS
├── 릴리스: 2023년 6월
├── 지원 기간: 2025년까지
├── AppsInToss 지원: 완전 최적화
└── 안정성: ★★★★★
```

### 권장 (Stable)

```
Unity 2021.3 LTS  
├── 릴리스: 2022년 4월
├── 지원 기간: 2024년까지
├── AppsInToss 지원: 완전 지원
└── 안정성: ★★★★☆
```

***

## 2. 버전별 상세 분석

### Unity 2023.3 LTS (최우선 권장)

#### 주요 장점

* Unity 6 기반: 완전히 새로운 아키텍처와 성능 향상
* Enhanced WebGL: 최대 40% 빠른 런타임 성능
* Universal Render Pipeline 17: 차세대 렌더링 기능
* Unity Netcode for GameObjects: 내장된 멀티플레이어 지원
* Entity Component System (ECS) 1.0: 고성능 데이터 지향 설계
* Unity Sentis: 온디바이스 AI 추론 엔진
* WebAssembly Multi-threading: 브라우저 멀티스레딩 지원 향상
* Improved Memory Management: 가비지 컬렉션 최적화

#### 최적화

```c#
// Unity 2023.3에서 지원하는 최신 최적화 기능들
var buildPlayerOptions = new BuildPlayerOptions
{
    scenes = scenes,
    locationPathName = outputPath,
    target = BuildTarget.WebGL,
    options = BuildOptions.None,
    // Unity 6 전용 최적화 옵션들
    extraScriptingDefines = new[] { 
        "APPSINTOS_OPTIMIZED", 
        "WEBGL_2_0", 
        "UNITY_6_FEATURES",
        "ECS_ENABLED",
        "SENTIS_AVAILABLE" 
    }
};

// 새로운 WebGL 설정
PlayerSettings.WebGL.compressionFormat = WebGLCompressionFormat.Brotli;
PlayerSettings.WebGL.webAssemblyArithmeticExceptions = false;
PlayerSettings.WebGL.wasmStreaming = true; // 새로운 스트리밍 기능
```

#### 성능 벤치마크 (vs 2022.3)

| 메트릭 | Unity 2023.3 | Unity 2022.3 | 개선율 |
|:--|:--:|:--:|:--:|
| 빌드 시간 | 32초 | 45초 | +29% |
| 시작 시간 | 1.6초 | 2.1초 | +24% |
| 메모리 사용량 | 68MB | 85MB | +20% |
| FPS (모바일) | 72 FPS | 55 FPS | +31% |
| 렌더링 성능 | +40% | 기준 | +40% |

#### Unity 6 전용 기능

* GPU Resident Drawer: 렌더링 성능 극대화
* Spatial Audio: 3D 오디오 최적화
* Web Platform Support: 향상된 브라우저 호환성
* Unity Cloud Build: 클라우드 빌드 최적화

### Unity 2024.2 LTS (실험적 지원)

#### 주요 장점

* Unity Muse 통합: AI 기반 콘텐츠 생성
* Advanced Graphics Features: 차세대 그래픽 효과
* Enhanced Multiplayer: 개선된 네트워킹 성능
* Better IDE Integration: Visual Studio Code 완전 지원
* Improved Package Manager: 의존성 관리 향상
*

#### 주의사항

* 베타 단계이므로 프로덕션 사용 주의
* AppsInToss SDK와의 호환성 테스트 필요
* 일부 기능이 불안정할 수 있음

### Unity 2022.3 LTS (안정적 검증된 선택)

#### 주요 장점

* WebGL 2.0 완전 지원: 최신 그래픽 기능 활용
* IL2CPP 최적화: 향상된 성능과 코드 보안
* New Input System: 모바일 터치 입력 최적화
* Addressable Assets: 효율적인 리소스 관리
* URP 최적화: 모바일 렌더링 성능 향상
* Burst Compiler: 고성능 연산 최적화

### 성능 벤치마크

| 메트릭 | Unity 2022.3 | Unity 2021.3 | 개선율 |
|:--|:--:|:--:|:--:|
| 빌드 시간 | 45초 | 60초 | +25% |
| 시작 시간 | 2.1초 | 2.8초 | +25% |
| 메모리 사용량 | 85MB | 105MB | +19% |
| FPS (모바일) | 55 FPS | 45 FPS | +22% |

### Unity 2021.3 LTS (안정적 선택)

#### 주요 장점

* 검증된 안정성: 2년간 검증된 LTS 버전
* WebGL 최적화: 우수한 WebGL 빌드 성능
* URP 지원: Universal Render Pipeline 완전 지원
* Package Manager: 안정적인 패키지 관리
* Timeline: 고급 시퀀싱 도구
*

#### 제한사항

* 일부 최신 WebGL 기능 미지원
* New Input System 완전하지 않음
* 메모리 최적화가 2022.3 대비 제한적

### Unity 2020.3 LTS (호환성 위주)

#### 사용 가능한 경우

* 기존 프로젝트가 이미 2020.3에서 안정적으로 동작
* 써드파티 플러그인이 최신 버전을 지원하지 않음
* 개발팀이 버전 업그레이드에 대한 리스크를 피하고 싶은 경우

#### 한계점

* WebGL 2.0 지원 제한적
* 성능 최적화 기능 부족
* 보안 업데이트 제한적
* 새로운 AppsInToss 기능 지원 제한

***

## 3. 버전 선택 가이드

### 신규 프로젝트 (2024년 권장)

```
새로운 게임 개발
├── Unity 2023.3 LTS (1순위 권장)
│   ├── Unity 6 최신 기능 활용
│   ├── 최대 40% 성능 향상
│   ├── 장기 지원 (2027년까지)
│   └── AppsInToss 최신 최적화
├── Unity 2022.3 LTS (안정적 선택)
│   ├── 검증된 안정성
│   ├── 완전한 AppsInToss 지원
│   └── 보수적 개발팀 권장
└── Unity 2024.2 LTS (실험적, 얼리어답터)
    ├── 최신 AI 기능
    ├── 차세대 그래픽
    └── 베타 테스터 및 실험 프로젝트
```

### 기존 프로젝트 업그레이드 가이드

```
기존 게임 포팅
├── 현재 Unity 2022.3
│   └── Unity 2023.3 LTS 업그레이드 권장 (성능 향상 40%)
├── 현재 Unity 2021.3 이상
│   ├── Unity 2023.3 LTS 업그레이드 (최우선)
│   └── 또는 Unity 2022.3 유지 (안정적)
├── 현재 Unity 2020.3
│   └── Unity 2023.3 LTS 업그레이드 필수 (2단계 업그레이드)
└── Unity 2019.4 이하
    └── Unity 2023.3 LTS 마이그레이션 필수 (단계별)
```

### 팀 상황별 권장사항 (2024 업데이트)

```
대규모 팀 (엔터프라이즈)
├── Unity 2023.3 LTS (1순위)
│   ├── 최대 성능 최적화 필요
│   ├── 충분한 테스트 리소스 확보 가능
│   └── 장기 지원 중요
├── Unity 2022.3 LTS (대안)
│   └── 보수적 접근 필요 시

중간 규모 팀 (스튜디오)
├── Unity 2023.3 LTS (권장)
│   ├── 성능과 안정성 균형
│   ├── 점진적 업그레이드 가능
│   └── ROI 최적화
├── Unity 2022.3 LTS (현실적 선택)
│   └── 안정성 최우선 시

소규모/개인 개발 (인디)
├── Unity 2023.3 LTS (강력 권장)
│   ├── 최신 기능으로 경쟁력 확보
│   ├── 빠른 개발 주기 지원
│   └── 성능 최적화 자동화
├── Unity 2024.2 LTS (얼리어답터)
│   └── 실험적 프로젝트 및 학습용
```

***

## 4. 업그레이드 가이드

### Unity 2022.3 → 2023.3 업그레이드 (권장)

#### 1단계: 사전 준비

```bash
# Git을 사용하는 경우
git checkout -b unity-upgrade-2023-3
git commit -am "Pre-upgrade backup for Unity 2023.3"
```

#### 2단계: Unity 2023.3 설치

* Unity Hub에서 Unity 2023.3 LTS 설치
* WebGL Build Support 모듈 포함 설치
* AppsInToss SDK 최신 버전 (v2.8+) 호환 확인

#### 3단계: 프로젝트 변환

```c#
// Unity 2023.3 전용 최적화 옵션 적용
#if UNITY_2023_3_OR_NEWER
    // Unity 6 기능 활용
    PlayerSettings.WebGL.wasmStreaming = true;
    PlayerSettings.WebGL.powerPreference = WebGLPowerPreference.HighPerformance;
    // ECS 시스템 설정
    #if ECS_ENABLED
    // ECS 기반 컴포넌트 최적화
    #endif
#endif
```

#### 4단계: 성능 최적화 설정

* Universal Render Pipeline 17 업그레이드
* Burst Compiler 최신 버전 적용
* Addressable Assets 최신 버전 업데이트
* Unity Sentis 설정 (AI 기능 사용 시)

#### 5단계: AppsInToss SDK 업데이트

* SDK를 v2.8 이상으로 업데이트
* 새로운 Unity 6 기능 연동 설정
* 성능 모니터링 도구 업데이트

### Unity 2019.4 → 2023.3 완전 마이그레이션 (권장)

#### 1단계: 프로젝트 백업

```
# Git을 사용하는 경우
git checkout -b unity-upgrade-2022-3
git commit -am "Pre-upgrade backup"
```

#### 2단계: 점진적 업그레이드

```
2019.4 → 2020.3 → 2021.3 → 2022.3
각 단계별로 빌드 테스트 및 문제 해결
```

#### 3단계: API 업데이트

```c#
// 구버전 코드
#if UNITY_2019_4_OR_NEWER
    // Legacy code
#endif

// 신버전 코드  
#if UNITY_2022_3_OR_NEWER
    // New optimized code
#endif
```

#### 4단계: 설정 마이그레이션

* Player Settings 재검토
* Package Manager 업데이트
* Build Settings 최적화
* AppsInToss SDK 최신버전 설치

### 일반적인 업그레이드 이슈

#### 스크립팅 API 변경

```c#
// Unity 2019.x
WWW www = new WWW(url);
yield return www;

// Unity 2022.x
using (UnityWebRequest www = UnityWebRequest.Get(url))
{
    yield return www.SendWebRequest();
}
```

#### 렌더링 파이프라인 변경

```c#
// Built-in → URP 마이그레이션
// 머티리얼 자동 변환 도구 사용
// 셰이더 호환성 검사 필요
```

## 5. 특수 상황별 권장사항

### WebGL 2.0 필수 프로젝트

```
고품질 3D 게임
├── Unity 2022.3 LTS 필수
├── WebGL 2.0 전용 기능 활용
├── Compute Shader 제한적 지원
└── 고급 셰이더 효과
```

### 레거시 플러그인 의존성

```
써드파티 플러그인 사용
├── 플러그인 호환성 먼저 확인
├── 업체에 업데이트 요청
├── 대안 솔루션 검토
└── 필요시 커스텀 포팅
```

### 빠른 출시 일정

```
타이트한 개발 일정
├── 현재 안정 버전 유지
├── Unity 2021.3 LTS 권장
├── 업그레이드는 차기 버전에서
└── 최소한의 변경으로 포팅
```

***

## 6. 성능 최적화 by 버전

### Unity 2023.3 LTS 최적화 설정 (최우선 권장)

```c#
// Unity 6 기반 최고 성능 최적화
PlayerSettings.WebGL.compressionFormat = WebGLCompressionFormat.Brotli;
PlayerSettings.WebGL.memorySize = 1024; // 더 큰 메모리 풀 지원
PlayerSettings.WebGL.exceptionSupport = WebGLExceptionSupport.ExplicitlyThrownExceptionsOnly;
PlayerSettings.WebGL.threadsSupport = true; // Unity 6에서 향상된 멀티스레딩
PlayerSettings.WebGL.wasmStreaming = true; // 스트리밍 최적화
PlayerSettings.WebGL.powerPreference = WebGLPowerPreference.HighPerformance;
PlayerSettings.WebGL.webAssemblyArithmeticExceptions = false; // 성능 최적화

// Unity 6 전용 고급 설정
PlayerSettings.WebGL.showUnityLogo = false;
PlayerSettings.WebGL.dataCaching = true;
PlayerSettings.WebGL.debugSymbolMode = WebGLDebugSymbolMode.External;

// ECS 최적화 (Unity 6)
#if ECS_ENABLED
PlayerSettings.SetScriptingDefineSymbolsForGroup(BuildTargetGroup.WebGL, 
    "UNITY_6_FEATURES;ECS_ENABLED;BURST_OPTIMIZED");
#endif
```

### Unity 2024.2 LTS 실험적 설정

```c#
// Unity Muse & AI 기능 통합 설정
PlayerSettings.WebGL.compressionFormat = WebGLCompressionFormat.Brotli;
PlayerSettings.WebGL.memorySize = 1536; // AI 모델을 위한 더 큰 메모리
PlayerSettings.WebGL.wasmStreaming = true;
PlayerSettings.WebGL.powerPreference = WebGLPowerPreference.HighPerformance;

// AI 기능 활성화 (Unity Muse)
#if UNITY_MUSE_AVAILABLE
PlayerSettings.SetScriptingDefineSymbolsForGroup(BuildTargetGroup.WebGL, 
    "UNITY_MUSE_ENABLED;AI_CONTENT_GENERATION");
#endif
```

### Unity 2022.3 최적화 설정 (안정적 검증됨)

```c#
// PlayerSettings 최적화
PlayerSettings.WebGL.compressionFormat = WebGLCompressionFormat.Brotli;
PlayerSettings.WebGL.memorySize = 512;
PlayerSettings.WebGL.exceptionSupport = WebGLExceptionSupport.ExplicitlyThrownExceptionsOnly;
PlayerSettings.WebGL.threadsSupport = false; // 브라우저 호환성
```

### Unity 2021.3 최적화 설정 (호환성 위주)

```c#
// 안전한 설정값들
PlayerSettings.WebGL.compressionFormat = WebGLCompressionFormat.Gzip;
PlayerSettings.WebGL.memorySize = 256;
PlayerSettings.WebGL.linkerTarget = WebGLLinkerTarget.Wasm;
```

***

## 7. 버전 업그레이드 체크리스트

### 사전 준비

* 프로젝트 전체 백업
* 현재 버전에서 완전한 빌드 성공 확인
* 사용 중인 Asset Store 플러그인 목록 작성
* 커스텀 셰이더 및 스크립트 검토

### 업그레이드 후 검증

* 프로젝트 오류 없이 열림
* WebGL 빌드 성공
* AppsInToss SDK 정상 동작
* 게임 핵심 기능 테스트
* 성능 벤치마크 비교
* 모바일 환경 테스트
*

### 최적화 작업

* Build Settings 재설정
* Quality Settings 조정
* Graphics Settings 최적화
* Package 의존성 정리

***

## 8. 지원 및 문제 해결

### Unity 버전 관련 문제

```
일반적인 문제들
├── 빌드 오류: API 변경사항 확인
├── 성능 저하: 설정 재검토 필요
├── 호환성 문제: 플러그인 업데이트
└── 기능 누락: 대안 구현 검토
```

앱인토스 SDK 호환성 (2024년 업데이트)

* Unity 2023.3 LTS: 모든 기능 완전 지원 + Unity 6 신기능 최적화
* Unity 2024.2 LTS: 실험적 지원 (베타, AI 기능 포함)
* Unity 2022.3 LTS: 모든 기능 완전 지원 (검증됨)
* Unity 2021.3 LTS: 주요 기능 완전 지원
* Unity 2020.3 LTS: 기본 기능 지원 (제한적)
* Unity 2019.4 이하: 제한적 지원 (업그레이드 필수)

---

---
url: 'https://developers-apps-in-toss.toss.im/design/resources.md'
description: '토스가 제공하는 그래픽 리소스 가이드입니다. 아이콘, 이모지, 스마트폰 목업, 일러스트레이션 등 그래픽 자산과 활용 방법을 확인하세요.'
---

# {{ $frontmatter.title }}

토스에서 제공하는 그래픽 리소스와 올바른 활용 방법을 안내드려요.

::: tip 그래픽 저작권 안내
토스의 모든 그래픽 자산 및 토스트를 통해 생성된 그래픽은 「저작권법」 및 관련 법령에 따라 보호받는 ㈜비바리퍼블리카의 지식재산권입니다.

제공된 그래픽은 앱인토스 제휴 환경 내에서의 서비스 운영 및 홍보 목적으로만 사용할 수 있으며, 다른 서비스나 매체에서 복제·수정·배포·전송·공중송신 등으로 활용하는 행위는 금지됩니다.
:::

## 토스에서 제공하는 그래픽 리소스

***

### 1. 아이콘 & 이모지

약 7,000개 이상의 토스 아이콘 & 이모지 세트가 제공됩니다.

자체적으로 제작할 경우, 아래 제작 가이드라인을 참고해주세요.

[앱인토스 아이콘 제작 가이드](https://www.notion.so/21b714bbfde780fb84bac2acfbb4a6b9?pvs=21)

![](/assets/resources-1.TUiom1wA.png)

**\[사용 시 유의사항]**

⚠️ 화면에서 24~40px 사이의 크기로 사용해 주세요.\
⚠️ 아이콘을 두 개 이상 병렬로 조합하는 것은 지양하고 있어요. 한 번에 하나씩만 사용해주세요.

### 2. 스마트폰 목업 파일

스마트폰 목업을 사용하여 리소스를 만드시는 경우 위 파일을 사용해주세요.\
크기별로 사용하실 수 있게 제공되니 임의로 크롭, 색상 보정, 왜곡하지 말아주세요.

::: details 디자인 업데이트 반영을 위해, 개발 시에도 아래 URL로 넣으시는 것을 권장드려요.

* **Full**
  * https://static.toss.im/illusts/mockup-template-250508.png
* **Large**
  * Top: https://static.toss.im/illusts/mockup-large-top-0513.png
  * Bottom: https://static.toss.im/illusts/mockup-large-bottom-0513.png
* **Medium**
  * Top: https://static.toss.im/illusts/mockup-medium-top-0513.png
  * Bottom: https://static.toss.im/illusts/mockup-medium-bottom-0513.png
* **Small**
  * Top: https://static.toss.im/illusts/mockup-small-top-0513.png
  * Bottom: https://static.toss.im/illusts/mockup-small-bottom-0513.png

:::

![](/assets/resources-2.NIPZ3nsX.png)

### 3. 토스트 (AI 이미지 생성 툴)

1번의 아이콘 & 이모지를 바탕으로 3D 이미지를 생성할 수 있어요.\
생성한 그래픽은 토스 그래픽 디자인 팀의 사용 승인(1일 이내)을 받아야 실제 화면에 사용할 수 있어요.

### 4. 그 외

3D, 애니메이션 등의 그래픽은 저희가 제공해드린 모듈 속에 포함된 것만 사용 가능해요.\
앞으로 점진적으로 제공 범위를 넓혀갈 예정이에요.

## 그래픽의 올바른 사용법

***

### 1. 문맥에 맞는 그래픽을 사용하세요.

그래픽은 장식이 아닌 사용자의 이해를 더 잘 돕기 위한 용도입니다.

![](/assets/resources-4.Br_-MChs.png)

### 2. 밀도에 맞는 크기로 사용하세요.

단순한 그래픽은 작게, 디테일한 그래픽은 크게 사용해 주세요.

![](/assets/resources-5.-eIbviLB.png)



### 3. 너무 많은 그래픽을 사용하지 마세요.

한 화면에 비슷한 크기의 그래픽이 많을수록 오히려 시선이 분산돼요.\
가장 핵심적인 그래픽 하나만 사용하고, 다른 곳은 보조적인 그래픽(ex. 아이콘)을 활용해주세요.

![](/assets/resources-6.CMjXw9_f.png)

### 4. 실질적인 내용이 가리지 않게 배치하세요.

중요한 정보가 아래로 밀려서 불필요한 스크롤이 생기지 않도록, 크기와 위치를 적절히 조정해서 사용하세요.

![](/assets/resources-7.CT_gLHIa.png)

### 5. 부정적이거나 호소성 감정 표현에 주의하세요.

사용자에게 불쾌감을 주거나, 애원하거나 호소하는 등 부정적인 감정 표현은 다크 패턴이므로 지양합니다.

![](/assets/resources-8.BpwXKF8R.png)

![](/assets/resources-9.CLiXSXkB.png)

### 6. 장식적인 효과나 이펙트를 사용하지 마세요.

의미없는 묘사, 파티클, 그라데이션 등 지나친 장식적인 요소는 화면을 복잡해보이게 만들 수 있어요.

![](/assets/resources-10.CySczKw1.png)

### 7. 상황을 정확히 전달하는 그래픽을 사용하세요.

오류 상황이 아닌데 느낌표 아이콘을 사용하거나, 기다려야하지 않는데 로딩 애니메이션을 쓰는 등의 액션은 사용자의 오해를 불러일으킬 수 있어요.

![](/assets/resources-11.hgGSeVuc.png)

![](/assets/resources-12.LHJaINLp.png)

## 파트너사에서 직접 그래픽을 만들 때 유의사항

***

### 1. 토스 스타일의 일관성을 지켜주세요.

토스는 단순 명료하고 깨끗한 디지털 그래픽 스타일을 지향해요.\
손그림, 서정적인 화풍, 만화적인 표현 등은 이질적으로 느껴질 수 있어요.

✅ **토스의 그래픽 스타일 예시**

![](/assets/resources-24.DxhYyEzy.png)

![](/assets/resources-13.n5Po5S88.png)

![](/assets/resources-14.CO1qTqfU.png)

![](/assets/resources-15.CsC1XC37.png)

### 2. 고화질의 그래픽을 만들어주세요.

깨끗하고 선명한 고화질의 그래픽을 만들어주세요.\
열화되거나, 파티클과 같은 자잘한 효과는 퀄리티가 낮아보일 수 있어 주의해주세요.

![](/assets/resources-16.8S9nvyAA.png)

![](/assets/resources-17.DEJYoggt.png)

### 3. 다크 / 라이트 모드 양쪽에서 가시성을 확보하세요.

토스 앱에 사용되는 그래픽은 다크 / 라이트 모드 둘 다 대응되어야 해요.\
너무 밝거나 어두워서 특정 모드에서 안 보이는 일이 없도록 중간 명도의 그래픽을 만들어주세요.

![](/assets/resources-18.ogwKFe8r.png)

### 4. 화면에 어울리는 컬러와 레이아웃으로 구성하세요.

텍스트, CTA 버튼 등 화면의 다른 요소들과 그래픽의 균형을 맞춰주세요.

![](/assets/resources-19.DeJ794ga.png)

### 5. 긍정적이고 정돈된 인상으로 만들어주세요.

서비스의 안정성과 신뢰감을 만드는데 그래픽이 큰 역할을 합니다.\
그래픽에 모노톤이 너무 많거나, 뿌옇고 칙칙해보이지 않게 디자인 해주세요.

![](/assets/resources-20.BZrEdioA.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/환경
  확인/getDeviceId.md
---

# 기기 고유식별자 확인하기

## `getDeviceId`

`getDeviceId` 함수는 사용 중인 기기의 고유 식별자를 문자열로 반환해요.

이 함수는 현재 사용 중인 기기의 고유 식별자를 문자열로 반환해요. 기기별로 설정이나 데이터를 저장하거나 사용자의 기기를 식별해서 로그를 기록하고 분석하는 데 사용할 수 있어요. 같은 사용자의 여러 기기를 구분하는 데도 유용해요.

## 시그니처

```typescript
function getDeviceId(): string;
```

### 반환 값

## 예제

### 기기 고유 식별자 가져오기

::: code-group

```js [js]
import { getDeviceId } from "@apps-in-toss/web-framework";

const deviceId = getDeviceId();
```

```tsx [React]
import { getDeviceId } from "@apps-in-toss/web-framework";
import { useState } from "react";

const DeviceInfo = () => {
  const [deviceId, setDeviceId] = useState<string | null>(null);

  const fetchDeviceId = async () => {
    setDeviceId(getDeviceId());
  };

  return (
    <div>
      <button onClick={fetchDeviceId}>기기 ID 가져오기</button>
      {deviceId && <p>Device ID: {deviceId}</p>}
    </div>
  );
};
}
```

```tsx [React Native]
import { getDeviceId } from '@apps-in-toss/framework';
import { Text } from '@toss/tds-react-native';

function MyPage() {
  const id = getDeviceId();

  return <Text>사용자의 기기 고유 식별자: {id}</Text>;
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/NavigationBar.md
---

# 내비게이션 바 설정

내비게이션 바는 화면 상단에 고정되어 있는 공통 UI 컴포넌트예요.\
이 문서에서는 **오른쪽 액세서리 영역에 아이콘을 추가하는 방법**과 **왼쪽 영역에 홈 버튼을 추가하는 방법** 두 가지를 설명해요.

## 디자인 가이드

상단 내비게이션은 사용자에게 일관된 정보 구조를 전달하기 위해 **모노톤 아이콘**만을 사용해요.\
컬러 아이콘은 시각적 주의를 과도하게 분산시키고, 불필요한 강조로 혼란을 줄 수 있기 때문이에요.\
토스에서는 기능 중심의 통일된 인터페이스를 위해,\
특수한 케이스를 제외하고는 모두 **모노톤 아이콘으로 통일**해 사용하고 있어요.

![](/assets/navi.BvEf_6ol.png)

## 1. 액세서리 아이콘 추가하기

게임, 비게임 미니앱 모두 우측 상단 **더보기 버튼 왼쪽 영역**에는 기능 버튼을 의미하는 아이콘을 한 개 추가할 수 있어요.

### 플랫폼별 설정 방식

* **WebView**
  * `partner.addAccessoryButton()`으로 런타임에 버튼을 추가할 수 있어요.
  * 클릭 이벤트는 `tdsEvent.addEventListener('navigationAccessoryEvent')`로 받아요.
  * 초기 노출은 `defineConfig`의 `navigationBar.initialAccessoryButton` 옵션을 사용해요.

* **React Native**
  * `useTopNavigation()`의 `addAccessoryButton()`으로 런타임에 버튼을 추가할 수 있어요.
  * 또는 `granite.config.ts`의 `navigationBar.initialAccessoryButton`을 사용해 초기 상태에서 버튼을 노출할 수 있어요.

### 시그니처

```typescript
interface NavigationBarOptions {
  withBackButton?: boolean; // 뒤로가기 버튼 유무
  withHomeButton?: boolean; // 홈버튼 유무
  initialAccessoryButton?: InitialAccessoryButton; // 1개만 노출 가능
}

interface InitialAccessoryButton {
  id: string;
  title?: string;
  icon: {
    name: string;
  };
}
```

### 예제

#### 아이콘 버튼 추가하기 (초기 설정)

::: code-group

```tsx [Web]
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
   // ...
  navigationBar: {
    withBackButton: true,
    withHomeButton: true,
    initialAccessoryButton: {
      id: 'heart',
      title: 'Heart',
      icon: {
        name: 'icon-heart-mono',
      },
    }
  },
});
```

```tsx [React Native]
import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
   // ...
      navigationBar: {
        withBackButton: true,
        withHomeButton: true,
        initialAccessoryButton: {
          icon: {
            name: 'icon-heart-mono',
          },
          id: 'heart',
          title: '하트',
        },
      },
    }),
  ],
});
```

:::

#### 아이콘 추가하기 (동적 추가)

::: code-group

```js [js]
import { partner, tdsEvent } from '@apps-in-toss/web-framework'

partner.addAccessoryButton({
  id: 'heart',
  title: '하트',
  icon: {
    name: 'icon-heart-mono',
  },
});

const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
  onEvent: ({ id }) => {
    if (id === 'heart') {
      console.log('버튼 클릭');
    }
  },
});

window.addEventListener('pagehide', () => {
  cleanup();
});
```

```tsx [React]
import { partner, tdsEvent } from '@apps-in-toss/web-framework'
  // ...
  useEffect(() => {
    partner.addAccessoryButton({  // 하트 아이콘 버튼 추가
      id: 'heart',
      title: '하트',
      icon: {
        name: 'icon-heart-mono',
      },
    });

    // 네비게이션 액세서리 버튼 클릭 이벤트 리스너 등록
    const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
      onEvent: ({ id }) => {
        if (id === 'heart') {
          console.log('버튼 클릭');
        }
      },
    });

    return cleanup;
  }, []);
```

```tsx [React Native]
import { useTopNavigation } from '@apps-in-toss/framework';
import { tdsEvent } from '@toss/tds-react-native';

// ...
const { addAccessoryButton } = useTopNavigation();
  
addAccessoryButton({ // 하트 아이콘 버튼 추가
    title: '하트',
    icon: {
        name: 'icon-heart-mono',
    },
    id: 'heart',
    onPress: () => console.log('버튼 클릭'),
});


// 이벤트 리스너
 useEffect(() => {
    const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
      onEvent: ({ id }) => {
        if (id === 'heart') {
          console.log('heart 클릭됨');
        } 
      },
    });

    // 컴포넌트 언마운트 시 이벤트 리스너 제거
    return () => {
      cleanup();
    };
  }, []);
```

:::

## 2. 홈 버튼 추가하기

비게임 미니앱에서는 왼쪽 상단에 **홈으로 이동하는 버튼**을 표시할 수 있어요.\
홈 버튼은 서비스 이름 오른쪽에 위치하며, 사용자가 언제든 첫 화면으로 돌아올 수 있도록 도와줘요.

::: tip 주의해주세요

* 오른쪽 액세서리 버튼 영역에는 홈 버튼을 중복 추가하지 말아주세요.
* 홈 버튼은 "서비스 진입점" 역할만 수행하며, 커스텀 기능이나 문구 추가는 불가능해요.
  :::

### 설정 방법

홈 버튼을 추가하려면 `navigationBar` 설정에 `withHomeButton: true` 옵션을 추가해 주세요.

```tsx
interface NavigationBarOptions {
  withHomeButton?: boolean; // 홈 버튼 표시 여부
}
```

### 예시

```tsx
navigationBar: {
  withBackButton: true,
  withHomeButton: true, // 홈 버튼 표시
}
```

## 참고사항

* 액세서리 버튼은 **모노톤 아이콘**만 지원돼요.
* 한 번에 표시할 수 있는 액세서리 버튼은 1개뿐이에요.
* 컬러 아이콘이나 커스텀 UI 추가는 지원하지 않아요.
* 홈 버튼은 비게임 미니앱에서만 사용 가능해요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/저장소/Storage.md
---

# 네이티브 저장소 이용하기

## `Storage`

`Storage` 로 네이티브의 저장소를 사용할 수 있어요.

### 시그니처

```typescript
Storage: {
  getItem: typeof getItem;
  setItem: typeof setItem;
  removeItem: typeof removeItem;
  clearItems: typeof clearItems;
}
```

### 프로퍼티

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-storage](https://github.com/toss/apps-in-toss-examples/tree/main/with-storage) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

## `setItem`

`setItem` 함수는 모바일 앱의 로컬 저장소에 문자열 데이터를 저장해요. 주로 앱이 종료되었다가 다시 시작해도 데이터가 유지되어야 하는 경우에 사용해요.

### 시그니처

```typescript
function setItem(key: string, value: string): Promise<void>;
```

### 파라미터

### 반환 값

### 예제

`my-key`에 아이템 저장하기

::: code-group

```js [js]
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleSetStorageItem(value) {
  const storageValue = await Storage.setItem(KEY, value);
}

async function handleGetStorageItem() {
  const storageValue = await Storage.getItem(KEY);
  return storageValue;
}

async function handleRemoveStorageItem() {
  await Storage.removeItem(KEY);
}
```

```tsx [React]
import { Storage } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useState } from 'react';

const KEY = 'my-key';

function StorageTestPage() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onClick={handleSet}>저장하기</Button>
      <Button onClick={handleGet}>가져오기</Button>
      <Button onClick={handleRemove}>삭제하기</Button>
    </>
  );
}
```

```tsx [React Native]
import { Storage } from '@apps-in-toss/framework';
import { Button, Text } from '@toss/tds-react-native';
import { useState } from 'react';

const KEY = 'my-key';

function StorageTestPage() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onPress={handleSet}>저장하기</Button>
      <Button onPress={handleGet}>가져오기</Button>
      <Button onPress={handleRemove}>삭제하기</Button>
    </>
  );
}
```

:::

## `getItem`

`getItem` 함수는 모바일 앱의 로컬 저장소에서 문자열 데이터를 가져와요. 주로 앱이 종료되었다가 다시 시작해도 데이터가 유지되어야 하는 경우에 사용해요.

### 시그니처

```typescript
function getItem(key: string): Promise<string | null>;
```

### 파라미터

### 반환 값

### 예제

`my-key`에 저장된 아이템 가져오기

::: code-group

```js [js]
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleGetItem() {
  const storageValue = await Storage.getItem(KEY);
  return storageValue;
}
```

```tsx [React]
import { Storage } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

const KEY = 'my-key';

function StorageClearButton() {
  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  return <Button onClick={handleGet}>가져오기</Button>;
}
```

```tsx [React Native]
import { Storage } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

const KEY = 'my-key';

function StorageClearButton() {
  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  return <Button onPress={handleGet}>가져오기</Button>;
}
```

:::

## `removeItem`

`removeItem` 함수는 모바일 앱의 로컬 저장소에서 특정 키에 해당하는 아이템을 삭제해요.

### 시그니처

```typescript
declare function removeItem(key: string): Promise<void>;
```

### 파라미터

### 반환 값

### 예제

`my-key`에 저장된 아이템 삭제하기

::: code-group

```js [js]
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleRemoveItem() {
  await Storage.removeItem(KEY);
}
```

```tsx [React]
import { Storage } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

const KEY = 'my-key';

function StorageClearButton() {
  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return <Button onClick={handleRemove}>삭제하기</Button>;
}
```

```tsx [React Native]
import { Storage } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

const KEY = 'my-key';

function StorageClearButton() {
  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return <Button onPress={handleRemove}>삭제하기</Button>;
}
```

:::

## `clearItems`

`clearItems` 함수는 모바일 앱의 로컬 저장소의 모든 아이템을 삭제해요.

### 시그니처

```typescript
declare function clearItems(): Promise<void>;
```

### 반환 값

### 예제

저장소 초기화하기

::: code-group

```js [js]
import { Storage } from '@apps-in-toss/web-framework';

async function handleClearItems() {
  await Storage.clearItems();
  console.log('Storage cleared');
}
```

```tsx [React]
import { Storage } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function StorageClearButton() {
  async function handleClick() {
    await Storage.clearItems();
    console.log('Storage cleared');
  }

  return <Button onClick={handleClick}>저장소 초기화</Button>;
}
```

```tsx [React Native]
import { Storage } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function StorageClearButton() {
  async function handlePress() {
    await Storage.clearItems();
    console.log('Storage cleared');
  }

  return <Button onPress={handlePress}>저장소 초기화</Button>;
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/네트워크/getNetworkStatus.md
---

# 네트워크 연결 상태 확인하기

## `getNetworkStatus`

`getNetworkStatus` 는 디바이스의 현재 네트워크 연결 상태를 가져오는 함수예요.
반환 값은 `NetworkStatus` 타입으로, 인터넷 연결 여부와 연결 유형(Wi-Fi, 모바일 데이터 등)을 나타내요. 값은 다음 중 하나예요.

* `OFFLINE`: 인터넷에 연결되지 않은 상태예요.
* `WIFI`: Wi-Fi에 연결된 상태예요.
* `2G`: 2G 네트워크에 연결된 상태예요.
* `3G`: 3G 네트워크에 연결된 상태예요.
* `4G`: 4G 네트워크에 연결된 상태예요.
* `5G`: 5G 네트워크에 연결된 상태예요.
* `WWAN`: 인터넷은 연결되었지만, 연결 유형(Wi-Fi, 2G~5G)을 알 수 없는 상태예요. 이 상태는 iOS에서만 확인할 수 있어요.
* `UNKNOWN`: 인터넷 연결 상태를 알 수 없는 상태예요. 이 상태는 안드로이드에서만 확인할 수 있어요.

## 시그니처

```typescript
function getNetworkStatus(): Promise<NetworkStatus>;
```

### 반환 값

## 예제

### 현재 네트워크 상태 가져오기

네트워크 연결 상태를 가져와 화면에 표시하는 예제예요.

```tsx
import { useState, useEffect } from 'react';
import { Text, View } from 'react-native';
import { getNetworkStatus, NetworkStatus } from '@apps-in-toss/framework';

function GetNetworkStatus() {
  const [status, setStatus] = useState<NetworkStatus | ''>('');

  useEffect(() => {
    async function fetchStatus() {
      const networkStatus = await getNetworkStatus();
      setStatus(networkStatus);
    }

    fetchStatus();
  }, []);

  return (
    <View>
      <Text>현재 네트워크 상태: {status}</Text>
    </View>
  );
}
```

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-network-status](https://github.com/toss/apps-in-toss-examples/tree/main/with-network-status) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/design/consumer-ux-guide.md'
description: >-
  앱인토스 다크패턴 방지 정책입니다. 고객의 예상을 벗어난 설계를 피하고 일관되고 신뢰할 수 있는 사용자 경험을 제공하기 위한 필수 가이드를
  확인하세요.
---

# 다크패턴 방지 정책

본 가이드라인은 사용자에게 불필요한 혼란이나 불이익을 주는 다크 패턴을 피하기 위해 마련된 지침입니다.\
아래 내용을 반드시 확인해 주세요.

## 고객의 예상을 벗어난 설계는 앱인토스 서비스로 출시할 수 없어요.

토스 사용자는 언제 어디서든 일관되고 신뢰할 수 있는 경험을 기대해요.\
각기 다른 기준으로 화면을 설계하면 사용자가 혼란을 느끼고, 이는 서비스에 대한 신뢰 저하로 이어질 수 있어요.

UX 가이드라인은 창의성을 제한하기 위한 것이 아니라, 고객에게 예측 가능하고 편리한 경험을 제공하기 위한 **최소한의 기준**이에요.\
이를 지켜주시는 것이 곧 고객 만족을 높이고, 서비스의 성과와 경쟁력을 함께 강화하는 길이에요.

## 고객의 예상을 벗어난 설계는 앱인토스 서비스로 출시할 수 없어요.

앱인토스 서비스를 포함한 토스 앱은 누구나 직관적으로 사용할 수 있어야 해요.\
이를 위해 반드시 지켜야 할 최소한의 사용 경험 기준을 정의했어요.

여기서 ‘최소한의 기준’이란, 고객이 제품을 제대로 쓰지 못하게 만드는 치명적인 사용성 오류를 의미해요.\
아래 공통 규칙들은 고객의 예상을 벗어난 설계 사례들이에요.

## 아래와 같은 설계가 적용된 앱은 출시할 수 없어요.

고객이 예상한 서비스 하면이 아닌 전면을 가로막는 광고형 바텀싯이 뜨는 사례를 의미해요.\
(알림동의를 받는 바텀싯도 포함)\
사용자는 서비스에 들어가는 순간, 자신이 예상한 목적을 바로 실행하기를 기대해요.\
에상치 못한 인터럽트가 등장하면 몰입이 끊기도 이탈 가능성이 높아져요.

![](/assets/ux_guide_1_1.BhtAsgnB.png)

![](/assets/ux_guide_1_2.BsyKX1HE.png)

고객이 이전 화면으로 돌아가 다른 서비스를 탐색하려는 순간, 예상과 달리 서비스 알림동의를 유도하는 바텀싯이 뜨는 사례를 의미해요.\
이탈을 막기 위한 추가 설계는 사용자의 자율성을 침해한다고 느껴질 수 있어요.

![](/assets/ux_guide_2_1.YAWKj18p.png)

![](/assets/ux_guide_2_2.DqWILSqb.png)

공급자가 유도한 CTA를 누르는 것 말고는 다른 선택지가 없는 사례를 의미해요.\
거절할 수 없는 구조는 강제적으로 느껴지고, 서비스에 대한 반감과 불신으로 이어질 수 있어요.

![](/assets/ux_guide_3_1.BNkB1d0c.png)

![](/assets/ux_guide_3_2.Dfu6YZgz.png)

사용자가 서비스에서 아이템을 받기 위해 메뉴를 누르자, 예상치 못하게 전면 광고가 뜨는 사례를 의미해요.\
사용 흐름 중 예상치 못한 광고는 사용자의 몰입을 방해하고, 브랜드에 대한 불쾌감을 유발할 수 있어요.

![](/assets/ux_guide_4_1.DZbXinrD.png)

![](/assets/ux_guide_4_2.BwcDtzsg.png)

CTA에 이미 화면에서 설명하고 있는 가치를 중복 설명하여, 고객이 버튼을 눌렀을 때 어떤 화면이 나올지 전혀 예상할 수 없는 사례를 의미해요.\
CTA는 행동을 명확하게 유도하는 장치예요.\
버튼 라벨이 모호하거나 중복된 설명만 담고 있으면, 사용자는 결과를 예측하지 못해 불안감을 느끼고 클릭을 주저할 수 있어요. 이는 전환율 저하로 이어질 수 있어요.\
그리고 CTA 위에 보조설명으로 과장되거나 중복되는 문구를 넣는 것도 사용자에게 혼란을 줄 수 있어요.

![](/assets/ux_guide_5.7MlSjYms.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인앱
  결제/getPendingOrders.md
---

# 대기 중인 목록 가져오기

## `getPendingOrders`

`getPendingOrders` 는 **결제는 완료되었지만 상품이 아직 지급되지 않은 주문 목록**을 가져오는 함수예요.\
조회된 주문 정보를 확인하여 사용자에게 상품을 지급하세요.\
`createOneTimePurchaseOrder` 함수 호출 후 결과를 받지 못한 경우에도 해당 주문을 조회할 수 있어요.

앱 버전이 최소 지원 버전(안드로이드 5.234.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.

## 시그니처

```typescript
function getPendingOrders(): Promise<{ orders: Order[] } | undefined>;
```

### 반환값

### 반환 객체 프로퍼티

```tsx
interface Order {
  orderId: string;
  sku: string;
}
```

::: tip sku 필드가 추가되었어요
SDK 1.4.2 버전에서 sku 필드가 추가되었어요.\
해당 필드는 **안드로이드 5.234.0 이상**, **iOS 5.231.0 이상** 에서만 반환돼요.
:::

## 예제

::: code-group

```js [js]
import { IAP } from '@apps-in-toss/web-framework';

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React]
import { IAP } from '@apps-in-toss/web-framework';

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React Native]
import { IAP } from '@apps-in-toss/framework';

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}
```

:::

---

---
url: 'https://developers-apps-in-toss.toss.im/analytics/dashboard.md'
description: 데이터 분석 대시보드 사용 가이드입니다. 지표 확인 및 분석 방법을 확인하세요.
---

# 대시보드

**대시보드는 미니앱 성공을 위해 꼭 활용해야 하는 핵심 기능이에요.**\
앱인토스 콘솔 대시보드에서는 **DAU, 성별, 연령, 리텐션 등 주요 지표를 한눈에 확인**하고, 이를 바탕으로 **서비스 개선과 트래픽 향상 전략을 세울 수 있어요.**

![](/assets/dashboard_1.DPaagIGH.png)

미니앱이 런칭되면 콘솔 홈 메뉴에서 **'분석하기' 탭**을 통해 대시보드를 확인할 수 있어요.\
이곳에서 제공되는 데이터는 **사용자의 행동을 이해하고, 전환율을 높이는 가장 중요한 근거**가 돼요.

* **SDK 0.0.26 버전 이상**이 적용된 미니앱만 데이터 확인이 가능해요.
* 샌드박스나 출시 준비 단계의 데이터는 제공되지 않으며, 실제 런칭 이후 데이터만 확인할 수 있어요.
* **서비스 런칭 후 하루 뒤부터** 데이터를 볼 수 있어요.

::: tip 참고하세요
**SDK 0.0.36 버전 이상**을 적용하면 추후 미니앱의 **체류 시간**도 측정할 수 있어요.\
이 데이터는 대시보드 UI에 반영될 예정이며, **사용자 경험을 더욱 정교하게 분석하는 데 도움**이 돼요.
:::

## 대시보드에서 확인할 수 있는 데이터

![](/assets/dashboard_2.B7vSio3T.png)

* **DAU(일간 활성 사용자 수)** : 최근 4주간 하루 단위로 앱을 사용한 사용자 수를 확인할 수 있어요.\
  → **서비스 성장세를 가장 직관적으로 보여주는 핵심 지표**예요.
* **OS별 사용자 수** : 최근 4주간 안드로이드, iOS 사용자를 구분해서 볼 수 있어요.\
  → 운영체제별 **최적화 전략 수립**에 활용할 수 있어요.
* **성별 분포** : 최근 4주간 남성, 여성 사용자 수를 확인할 수 있어요.\
  → **타겟 맞춤형 콘텐츠 기획**에 꼭 필요한 데이터예요.
* **연령 분포** : 최근 4주간 10대부터 60대 이상까지 연령대별 사용자 수를 확인할 수 있어요.\
  → **주요 고객층 파악과 마케팅 전략 설계**에 활용할 수 있어요.
* **리텐션(재방문율)** : 사용자가 첫 방문 이후 일정 기간 내에 다시 앱을 이용한 비율을 확인할 수 있어요.\
  → **서비스 충성도와 만족도를 측정하는 핵심 지표**예요.

✅ **대시보드는 단순한 통계 화면이 아니라, 파트너사의 미니앱 성장을 가속화하는 전략 도구**예요.\
데이터를 꾸준히 확인하고 개선에 활용하면 **트래픽 증가와 전환율 향상 효과**를 반드시 체감할 수 있을 거예요.

추가로 필요한 데이터 항목이 있다면 언제든 채널톡으로 문의해주세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/growth/insight.md'
description: >-
  앱인토스 데이터 기반 성장 인사이트 가이드입니다. DAU, 리텐션 등의 지표를 활용해 앱 성장을 분석하고 다음 액션을 계획하는 방법을
  확인하세요.
---

# 데이터 기반 성장 인사이트 만들기

앱이 성장하고 있는지 확인하려면, 지금의 상태를 정확히 알아야 해요.\
앱인토스의 콘솔 대시보드를 통해 AU, 리텐션 등의 지표를 한눈에 보고 성장의 흐름을 파악해보세요.\
데이터를 기반으로 다음 액션을 정하면, 더 빠르고 확실한 성장을 만들 수 있어요.

***

## 토스 기능으로 데이터 인사이트 발견하기

### ① DAU

DAU는 Daily Active Users로서, **일간 활성 사용자 수**를 의미해요.\
즉, 하루 동안 앱을 실제로 이용한 사용자 수를 나타내요.\
DAU를 통해서 일별 사용자 활동 변화를 통해 앱의 **'실제 이용 규모'** 와 **'활동 흐름'** 을 확인할 수 있어요.

![](/assets/growth_insight_1.aufQHhsU.png)

DAU의 해석 포인트는 아래와 같아요.

* **지속적인 하락**은 **신규 유입이 줄거나 리텐션이 약화된 신호**예요.
* **일시적 급등/급락**은 캠페인, 이벤트, 업데이트 등 **외부 요인의 영향을 반영**할 수 있어요.
* **유입과 리텐션 데이터를 함께 비교**하면 감소의 원인이 **‘유입 부진’** 인지 **‘이탈 증가’** 인지 판단할 수 있어요.

::: tip 👉 액션 아이템

* 하락 추세 시: 신규 유입 경로(푸시, 토스 홈 광고 등)를 점검하고, 유입 캠페인 강화를 고려해요.
* 급등 시: 일시적 반응인지, 장기적 이용으로 이어지는지 리텐션 지표로 검증해요.
* 요일별 DAU 분석을 통해 사용자 이용 패턴에 맞춘 푸시 발송 타이밍을 최적화해요.
  :::

### ② 사용자 특성 정보

대시보드에서 사용자 특성 정보인 **OS, 성별, 연령대 분포**를 확인할 수 있어요.\
앱을 사용하는 주요 타겟이 누구인지, 실제 이용층이 예상과 일치하는지 판단할 수 있어요.

![](/assets/growth_insight_2.DPhxi3qu.png)

사용자 특성 정보의 해석 포인트는 아래와 같아요.

* **Android와 iOS 사용 비율이 크게 차이**나면, **플랫폼별 UI/UX 또는 마케팅 효율을 점검**할 필요가 있어요.
* 서비스 특성상 어떤 성별과 연령이 더 반응하는지 확인할 수 있어요.

::: tip 👉 액션 아이템

* OS별 성과 차이가 있다면 UI/UX 테스트 또는 이벤트 노출 방식을 조정해요.
* 특정 연령·성별 비중이 높을 경우, 그에 맞는 콘텐츠 톤앤매너·혜택 구성으로 타겟 메시지를 강화해요.
* 예상 타겟과 실제 이용층이 다를 때, 세그먼트 기준을 재정의하거나 신규 타겟 확장 전략을 세워요.
  :::

### ③ 리텐션

리텐션은 **최초 방문 이후 일정 기간이 지난 뒤**에도 **앱을 다시 이용하는 사용자의 비율**을 나타내요.\
리텐션을 보면 ‘앱이 얼마나 오랫동안 사용자를 붙잡고 있는지’를 확인할 수 있어요.

![](/assets/growth_insight_3.B0hPXivb.png)

리텐션의 해석 포인트는 아래와 같아요.

* **초기 리텐션(WEEK 1)은 첫 경험의 만족도**를, **장기 리텐션(WEEK 4 이후)은 습관화 정도**를 반영해요.
* 리텐션 하락 구간을 찾으면, 사용자 이탈이 발생하는 시점을 명확히 알 수 있어요.
* 리텐션은 단독 지표로 보기보다, 푸시·프로모션·UI 개선 등 실험 결과와 함께 해석해야 정확한 인사이트를 얻을 수 있어요.

::: tip 👉 액션 아이템

* 리텐션 강화: 주기적 혜택, 도전 미션, 알림 리마인드 등으로 반복 사용 동기를 만들어요.
* 리텐션 하락 시점 분석을 통해 UI 개선, 콘텐츠 갱신, 푸시 타이밍 조정 등 구체적 개선 실험을 실행해요.
  :::

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/guide/runtime-structure.md'
---
# 동작 방식

![](/assets/unity_webgl_structure.C3zMnjOQ.png)

## 1. 동작 원리

Unity의 BuildTarget은 WebGL 플랫폼을 지원하며, WebGL 내보내기 패키지는 WebAssembly 기술을 기반으로 브라우저 환경에서 실행됩니다.\
내보내기 패키지가 AppsInToss 미니앱 환경에서 실행될 수 있도록 다음과 같은 지원을 제공합니다:

* 개발 단계: 플랫폼 기능의 TypeScript SDK 제공으로 개발자가 플랫폼 기능에 빠르게 연동
* 내보내기 단계: 전환 패키징 도구로 Unity WebGL 접착층 적응을 통해 미니앱 패키지로 직접 전환
* 실행 단계: WebAssembly 기본 기능 및 AppsInToss 하위 레벨 인터페이스 지원 제공

***

## 2. 핵심 기술 스택

### WebAssembly (WASM)

* Unity C# 코드를 WebAssembly로 컴파일하여 네이티브에 가까운 성능 제공
* 브라우저 환경에서 고성능 게임 실행 가능
* 메모리 관리 및 가비지 컬렉션 최적화

### JavaScript Bridge

* Unity C#과 AppsInToss JavaScript API 간 양방향 통신 제공
* 플랫폼별 기능(결제, 광고, 소셜 등)에 원활한 접근
* 타입 안전성을 보장하는 자동 마샬링

### Vite + React 프레임워크

* 모던 웹 개발 환경 제공
* 빠른 개발 서버와 최적화된 번들링
* TypeScript 완전 지원

### Granite 빌드 시스템

* AppsInToss 플랫폼 최적화된 빌드 파이프라인
* 자동 리소스 압축 및 CDN 배포
* 점진적 로딩 및 캐싱 전략

***

## 3. 아키텍처 개요

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Unity Game    │    │  AppsInToss     │    │   Platform      │
│                 │    │   Bridge        │    │   Services      │
│  ┌───────────┐  │    │                 │    │                 │
│  │ C# Logic  │  │◄──►│ TypeScript SDK  │◄──►│   Login API     │
│  └───────────┘  │    │                 │    │   Storage API   │
│  ┌───────────┐  │    │ ┌─────────────┐ │    │   Payment API   │
│  │  Render   │  │    │ │ JS Runtime  │ │    │   Admob         │
│  └───────────┘  │    │ └─────────────┘ │    │   Analytics     │
│  ┌───────────┐  │    │ ┌─────────────┐ │    │                 │
│  │WebAssembly│  │    │ │ WebGL Glue  │ │    │                 │
│  └───────────┘  │    │ └─────────────┘ │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

***

## 4. 주요 특징

### 고성능

* WebAssembly 기반으로 네이티브에 가까운 성능
* GPU 가속 렌더링 지원
* 메모리 효율적인 리소스 관리

### 호환성

* Unity 2018.4 LTS 이상 모든 버전 지원
* 대부분의 Unity 기능과 써드파티 플러그인 지원
* 기존 게임 코드 95% 이상 재사용 가능

### 모바일 최적화

* 터치 입력 및 제스처 완전 지원
* 모바일 성능에 최적화된 렌더링
* 배터리 효율성 고려한 프레임 레이트 관리

### 개발 도구

* Unity 에디터 통합 빌드 도구
* 실시간 디버깅 및 프로파일링
* 자동화된 배포 파이프라인

***

## 5. 포팅 순서

전환 흐름은 [Unity WebGL 앱인토스 미니앱 전환 가이드 문서](/unity/intro/migration-guide)를 참조하세요.

***

## 6. 성능 벤치마크

| 메트릭 | 네이티브 앱 | AppsInToss WebGL | 성능 비율 |
|:--|:--:|:--:|:--:|
| 시작 시간 | 1.2초 | 2.8초 | 85% |
| FPS (3D 게임) | 60 FPS | 50–55 FPS | 90% |
| 메모리 사용량 | 100MB | 120MB | 83% |
| 배터리 소모 | 100% | 110% | 91% |

***

## 7. 지원 플랫폼

### 완전 지원

* iOS: Safari WebView (iOS 13+)
* Android: Chrome WebView (Android 7+)
* Desktop: Chrome, Firefox, Safari, Edge

### 최적화 지원

* 토스앱 WebView: 네이티브 수준 성능
* AppsInToss 브라우저: 전용 최적화

### 브라우저 호환성

* WebAssembly 지원: 95%+ 커버리지
* WebGL 2.0 지원: 90%+ 커버리지
* SharedArrayBuffer: 85%+ 커버리지

***

## 8. 보안 및 안정성

### 코드 보호

* WebAssembly 바이너리 형태로 코드 배포
* 선택적 코드 난독화 지원
* 워터마크를 통한 무단 복제 방지

### 데이터 보안

* HTTPS 강제 적용
* 민감한 데이터는 서버사이드 검증
* 클라우드 저장소 암호화

***

## 9. 제한 사항

### 기술적 제약

* 멀티스레딩 제한적 지원
* 파일 시스템 접근 불가
* 네이티브 플러그인 사용 불가

### 성능 고려사항

* 메모리 사용량이 네이티브 앱 대비 20-30% 높음
* 초기 로딩 시간이 네이티브 앱 대비 2-3배
* 배터리 소모가 약 10-15% 높음

***

### 10. 참고자료

* [Unity WebGL 가이드](https://docs.unity3d.com/Manual/webgl-gettingstarted.html)
* [Unity WebGL 포럼](https://discussions.unity.com/c/unity-engine/52)
* [MDN WebAssembly 문서](https://developer.mozilla.org/ko/docs/WebAssembly)
* [앱인토스 개발자 센터](https://developers-apps-in-toss.toss.im/)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/useBackEvent.md
---

# 뒤로가기 이벤트 제어하기

## `useBackEvent`

`useBackEvent` 는 뒤로 가기 이벤트를 등록하고 제거할 수 있는 컨트롤러 객체를 반환하는 Hook이에요. 이 Hook을 사용하면 특정 컴포넌트가 활성화되었을 때만 뒤로 가기 이벤트를 처리할 수 있어요.
`addEventListener` 를 쓰면 뒤로 가기 이벤트를 등록할 수 있고, `removeEventListener` 를 쓰면 뒤로 가기 이벤트를 제거할 수 있어요.
사용자가 화면을 보고 있을 때만 등록된 뒤로 가기 이벤트가 등록돼요. 화면을 보고 있다는 조건은 [useVisibility](/bedrock/reference/framework/화면%20제어/useVisibility.md) 을 사용해요.

이 Hook을 사용해 특정 컴포넌트에서 뒤로 가기 이벤트를 처리하는 로직을 정의할 수 있어요.

## 시그니처

```typescript
function useBackEvent(): BackEventControls;
```

### 반환 값

### 에러

## 예제

### 뒤로 가기 이벤트 등록 및 제거 예제

* **"Add BackEvent" 버튼을 누르면 뒤로 가기 이벤트가 등록돼요.** 이후 뒤로 가기 버튼을 누르면 "back"이라는 알림이 뜨고, 실제로 뒤로 가지 않아요.
* **"Remove BackEvent" 버튼을 누르면 등록된 이벤트가 제거돼요.** 이후 뒤로 가기 버튼을 누르면 기존 동작대로 정상적으로 뒤로 가요.

```tsx
import { useEffect, useState } from "react";
import { Alert, Button, View } from "react-native";
import { useBackEvent } from '@granite-js/react-native';

function UseBackEventExample() {
  const backEvent = useBackEvent();

  const [handler, setHandler] = useState<{ callback: () => void } | undefined>(
    undefined
  );

  useEffect(() => {
    const callback = handler?.callback;

    if (callback != null) {
      backEvent.addEventListener(callback);

      return () => {
        backEvent.removeEventListener(callback);
      };
    }

    return;
  }, [backEvent, handler]);

  return (
    <View>
      <Button
        title="Add BackEvent"
        onPress={() => {
          setHandler({ callback: () => Alert.alert("back") });
        }}
      />
      <Button
        title="Remove BackEvent"
        onPress={() => {
          setHandler(undefined);
        }}
      />
    </View>
  );
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/learn-more/debugging-webview.md'
---
# 디버깅하기

## Android & Chrome 환경

::: tip 잠시만요

디바이스에서 디버깅할 때는, 디바이스 설정에서 USB 디버깅을 활성화해야 해요.\
`설정 -> 시스템 -> 휴대전화 정보 -> 개발자 옵션 -> USB 디버깅 활성화`

:::

**Chrome Devtools** 를 사용해 디버깅을 할 수 있어요.

1. Android 에뮬레이터나 실제 Android 기기에서 미니앱을 실행합니다.
2. Chrome 브라우저에서 `chrome://inspect/#devices` 페이지를 엽니다.
3. Devices 탭 Remote Target에 디버깅하고자 하는 WebView 콘텐츠 아래에 있는 **inspect** 버튼을 선택합니다.
4. 일반 웹 페이지를 디버깅하듯 WebView 콘텐츠를 디버깅할 수 있어요.

## iOS & Safari 환경

::: tip 잠시만요

* 디바이스에서 디버깅할 때는, 디바이스 설정에서 Web Inspector(웹 검사기)를 활성화해야 해요.
  * 설정 -> Safari -> 고급 -> Web Inspector 활성화
* 개발자용 메뉴에 디바이스가 표시되지 않고, Safari를 시뮬레이터보다 먼저 실행한 경우에는 Safari를 재시작해 보세요.

:::

iOS 시뮬레이터나 실제 디바이스에서 **Safari 개발자 도구(Developer Toolkit)** 를 사용하여 WebView 콘텐츠를 디버깅할 수 있습니다.

1. Safari 환경설정 -> "고급" 탭 -> "웹 개발자를 위한 기능 보기" 체크박스를 활성화해요.
2. iOS 시뮬레이터 또는 실제 iOS 디바이스에서 미니앱을 실행합니다.
3. Safari -> 상단바 개발자용 -> \[디바이스 이름] -> \[앱 이름] -> \[URL - 제목]
4. 이제 웹에서 디버깅하듯 WebView 콘텐츠를 디버깅할 수 있습니다.

---

---
url: 'https://developers-apps-in-toss.toss.im/learn-more/debugging.md'
description: >-
  앱인토스 미니앱 디버깅 방법을 안내합니다. Chrome DevTools, React DevTools, 에러 처리 등 개발 도구 활용법을
  확인하세요.
---

# 디버깅하기

## 준비

React Native Debugger를 사용해서 JavaScript 디버깅을 하려면 Chrome 브라우저가 필요해요. 다음 링크로 브라우저를 다운로드 하세요.

* [Chrome 웹브라우저 다운로드 링크](https://www.google.com/intl/ko_kr/chrome/)

## Metro 개발 서버 실행

Metro 개발 서버는 React Native 애플리케이션을 개발할 때 코드 번들링, 핫 리로딩, 자원 제공 등의 역할을 해주는 번들러예요. 쉽게 말해서, 앱이 실행될 수 있도록 JavaScript 코드를 준비하고 관리하는 도구라고 생각하면 돼요.

다음 명령어로 Metro 개발 서버를 실행해서 디버깅을 시작해 볼게요.

```bash
yarn dev
# 또는
yarn bedrock dev
```

![Metro 개발 서버를 띄운 화면](/assets/debugging-1.z-bhdbHR.png)

개발 서버가 실행됐다면, 터미널에서 `j` 키를 눌러 React Native Debugger를 열 수 있어요. 다만, 아래와 같이 Metro와 테스트 기기 간의 연결이 이루어진 상태에서만 React Native Debugger가 열려요.

![기기와 연결된 상태](/assets/debugging-2.Uv7H5q5P.png)

## 탭 소개

Metro 개발 서버가 제공하는 디버깅 도구를 사용해서 편리하게 애플리케이션의 상태를 분석하고, 문제를 찾아 해결할 수 있어요. 각 탭에서는 모니터링하거나 조작할 수 있는 항목을 알아봐요.

![디버거 탭 소개 이미지](/assets/debugging-3.BmmXnth6.png)

* **Console**: [Console API](https://developer.mozilla.org/en-US/docs/Web/API/Console_API)를 통해 기록한 로그를 확인할 수 있어요. 또한, REPL(Read–Eval–Print Loop) 환경을 지원하기 때문에 코드를 입력하면 결과를 콘솔에서 확인할 수 있어요.

* **Source**: 현재 실행 중인 코드를 보고 중단점을 추가할 수 있어요.

* **Network**: 개발 서버에 연결된 서비스의 네트워크 활동을 확인할 수 있어요.

* **Memory**: Memory Snapshot을 기록해서 Hermes 엔진의 메모리 사용 상황을 프로파일링할 수 있어요.

* **Profiler**: 코드 실행 성능을 측정할 수 있는 도구예요.

## 기본 사용법

이제 Metro 개발 서버를 사용해서 React Native 애플리케이션에서 다양한 디버깅 기능을 활용하는 방법을 알아볼게요.

### 디버깅 공통

React Native 디버거를 사용하면 코드에서 발생하는 문제를 쉽게 찾고 해결할 수 있어요. 특히 유용한 기능은 Breakpoints에요. 이 기능을 사용하면 코드가 중단된 시점의 상태를 확인할 수 있어요. 가장 기본적인 기능은 다음과 같아요.

1. **Resume**: 일시 정지된 코드를 다시 실행해요.
2. **Scope 정보**: 현재 Scope에 접근 할 수 있는 변소와 그 값을 확인할 수 있어요.
3. **Call Stack**: 코드가 실행된 순서와 호출된 함수 목록, Call Stack을 확인할 수 있어요.

![Breakpoints 사용 예시 이미지 1](/assets/debugging-4.CGru5jtv.png)

일시정지된 시점에서 변수의 값을 바로 확인할 수도 있어요. 다음과 같이 변수 위로 마우스 커서를 올리면 돼요.

![Breakpoints 사용 예시 이미지 2](/assets/debugging-5.DMXIqUPk.png)

### debugger 키워드로 디버깅하기

또 다른 유용한 기능은 `debugger` 키워드예요. 이 키워드를 소스 코드에 추가하면 코드가 해당 지점에 도달했을 때 자동으로 중단되어 현재 상태를 살펴볼 수 있어요.

![debugger 코드 사용 예시 이미지](/assets/debugging-6.ClXobroT.png)

### 중단점으로 디버깅하기

중단점을 설정해서 특정 위치에서 코드 실행을 멈추는 기능도 사용할 수 있어요. 중단점을 추가하려면 커맨드(Command) + `P` 키를 눌러 파일 검색 창을 띄우고, 확인하고 싶은 파일명을 입력하세요.

![중단점 추가 예시 이미지 1](/assets/debugging-7.CZ1znzWG.png)

파일을 열었다면, 중단점을 설정하고 싶은 위치를 클릭해서 추가할 수 있어요. 중단점에 도달했을 때 코드 실행이 멈추면 현재 상태를 확인할 수 있어요.

![중단점 추가 예시 이미지 2](/assets/debugging-8.DtgBrLym.png)

### 예외 상황 디버깅하기

코드에서 예외(에러)가 발생했을 때 자동으로 그 지점에서 일시 정지되도록 설정할 수 있어요. 이 기능을 사용하면 미리 예상하지 못한 에러와 그 원인을 쉽게 파악할 수 있죠.

이 기능은 Metro 디버거의 **Source 탭**에서 설정할 수 있어요. 우측 상단의 Breakpoints 섹션에서 **"Pause on uncaught exceptions"** 을 활성화하면 예기치 못한 예외 발생 시 코드가 자동으로 중단돼요. **"Pause on caught exceptions"** 을 활성화하면 모든 예외(핸들링 여부와 관계없이)에서 일시 정지할 수 있어요.

![예외 상황 디버깅 설정 예시 이미지 1](/assets/debugging-9.ClKTRdaN.png)

![예외 상황 디버깅 설정 예시 이미지 2](/assets/debugging-10.CzJSb05R.png)

::: tip 유의하세요

서비스 코드에서 심각한 예외가 발생해 서비스가 완전히 중단된 후에 예외 Breakpoints가 제대로 동작하지 않는 버그가 있어요.

임시 해결 방법은 개발 서버와 React Native Debugger를 재시작하는 거예요.

:::

## 네트워크 활동 검사

React Native 애플리케이션의 네트워크 활동을 기록하고 확인할 수 있는 네트워크 인스펙터 기능을 사용해 볼게요.

네트워크 인스펙터를 사용하면 요청과 응답 데이터를 포함한 네트워크 활동을 다음과 같이 확인할 수 있어요. 이 도구를 사용하면 각 요청의 헤더와 응답 데이터를 상세히 분석할 수 있어요.

![네트워크 활동 검사 예시 이미지](/assets/debugging-11.B9rgsI54.png)

## 프로파일링

프로파일링 도구를 사용하면 React Native 애플리케이션의 메모리 사용량과 코드 실행 성능을 상세히 분석할 수 있어요. 이를 통해 성능 최적화와 메모리 누수 문제를 발견하고 해결할 수 있죠.

### 메모리

메모리 프로파일링 기능은 메모리 사용량을 분석하고, 메모리 누수를 탐지하는 데 유용해요. 이 도구를 사용해 앱이 메모리를 어떻게 관리하고 있는지 확인할 수 있어요.

1. 먼저, 프로파일링 유형을 선택하세요.
2. **"Take snapshot"** 버튼을 눌러 스냅샷을 기록할 수 있어요.
3. 기록된 스냅샷을 보며 메모리 사용 상태를 분석하고 필요한 정보를 찾아요.

![메모리 프로파일링 예시 이미지 1](/assets/debugging-13.jnuQ2VYs.png)

![메모리 프로파일링 예시 이미지 2](/assets/debugging-14.B2iOWS_g.png)

## 성능 측정

성능 측정 도구를 사용하면 코드의 실행 성능을 분석할 수 있어요. 이 기능은 성능 최적화가 필요한 부분을 식별하고 개선하는 데 유용해요.

다음은 성능 측정 도구의 사용 예시에요. 이 도구를 사용해 기록을 시작하고, 실행된 코드의 성능을 평가할 수 있어요.

![성능 측정 도구 사용 예시 1](/assets/debugging-15.BWSJK_qd.png)

![성능 측정 도구 사용 예시 2](/assets/debugging-16.Bir56t9S.png)

## React DevTools로 디버깅하기

React DevTools는 React Native 애플리케이션의 컴포넌트 구조를 시각적으로 탐색하고 디버깅할 수 있는 도구예요. 디버깅 도구의 React DevTools에서 바로 사용할 수 있어요.

### 기기와 연결하기

React DevTools를 사용하려면 먼저 개발 중인 애플리케이션의 연결이 필요해요.

서비스가 실행되기 전이라면 개발 모드에서 React Native 서비스를 실행해 주세요. 서비스가 이미 실행 중이라면, 개발 모드 RN 뷰를 **새로고침**해야 해요. `R` 키를 눌러서 새로고침해주세요.

![React DevTools 기기와 연결하기 1](/assets/debugging-17.Cp8ggGjb.png)

다음과 같이 React DevTools 화면이 나타나면 연결이 완료된 거예요.

![React DevTools 기기와 연결하기 2](/assets/debugging-18.LatrvStk.png)

안드로이드 기기를 사용한다면, `adb reverse tcp:8097 tcp:8097` 명령어를 입력해서 포트를 열어야 React DevTools가 정상적으로 동작해요. 만약 문제가 있다면 담당자에게 문의해주세요.

### 사용 팁

React DevTools에 있는 여러 유용한 기능을 효과적으로 사용하는 몇 가지 팁을 알려드릴게요.

#### 요소 인스펙팅

특정 요소를 쉽게 찾고 확인할 수 있는 기능이에요. 요소 선택 버튼을 누른 뒤, 테스트 중인 기기에서 확인할 요소를 터치하면 React DevTools에서 해당 요소로 바로 이동해요.

![인스펙팅 화면](/assets/debugging-19.C2F2iBKp.png)

#### Prop 변경하기

선택한 컴포넌트의 Prop(속성)을 확인하고, 실시간으로 변경할 수 있어요. 원하는 Prop을 더블 클릭한 뒤 값을 입력하면 바로 반영됩니다.

![Prop 변경 사용 예시 이미지](/assets/debugging-20.DZ4Jcbyg.png)

#### Suspense 테스트하기

Suspense 요소의 대기 상태를 시뮬레이션할 수 있는 기능이에요. 타이머 아이콘을 눌러 Suspense 대기 상태를 테스트해볼 수 있어요.

![Suspense 테스트 사용 예시 이미지](/assets/debugging-21.aDDmsPh8.png)

#### 상세 정보 로깅하기

특정 요소의 세부 정보를 콘솔에서 확인할 수 있어요. 디버그 버튼을 누르면 선택한 요소의 세부 정보가 콘솔에 기록됩니다.

![상세 정보 로깅 예시 이미지](/assets/debugging-22.B1aIn4qo.png)

## 트러블슈팅

::: details 연결 가능한 기기가 없다고 떠요

React Native View가 나타나는 시점에 개발 서버와 기기가 연결됩니다. 만약 연결 가능한 기기가 없다고 뜬다면, 개발 서버가 제대로 빌드되고 있는지 확인해 보세요. 다음 화면처럼 개발 서버가 빌드를 시작했다면 기기와의 연결이 정상적으로 이루어진 것입니다.

![개발 서버 연결 상태 확인 이미지](/assets/debugging-22.B1aIn4qo.png)
:::

::: details REPL가 동작하지 않아요

React Native의 버그로 인해 가끔 REPL이 멈추는 현상이 발생할 수 있어요. 이 문제를 해결하려면, 콘솔 탭 옆에 있는 눈 모양 아이콘을 클릭하고 입력 필드에 임의의 코드를 작성하고 평가해 보세요. 예를 들어 `__DEV__`, `1`, `undefined` 등의 코드를 입력하면 돼요.

![REPL 프리징 해결 방법 이미지](/resources/learn-more/debugging/debugging-23.png)

:::

::: details 네트워크 인스펙터가 동작하지 않아요

React Native 애플리케이션에서 여러 개의 인스턴스가 생성될 수 있는데, 현재 네트워크 인스펙터는 다중 인스턴스를 지원하지 않아요. 따라서 가장 최근에 생성된 인스턴스와만 데이터를 주고받게 됩니다. 이로 인해 소켓 커넥션이 꼬여 네이티브에서 전송하는 데이터를 인스펙터가 받지 못할 수 있어요.

이 문제를 해결하려면 다음을 시도해 보세요.

1. 앱을 완전히 종료해요.
2. 개발 서버를 중단하고 네트워크 인스펙터를 닫아요.
3. 앱을 다시 시작하고 `dev` 스크립트를 실행해 개발 서버를 재실행해요.

이 절차로도 문제가 해결되지 않으면, 담당자에게 제보해 주세요.

:::

기타 다른 문제가 발생했다면, 다음을 시도해 보세요.

1. 앱을 완전히 종료해요.
2. 개발 서버를 중단하고 네트워크 인스펙터를 닫아요.
3. 앱을 다시 시작하고 `dev` 스크립트를 실행해 개발 서버를 재실행해요.

이 절차로도 문제가 해결되지 않으면, 담당자에게 제보해 주세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/perf-monitoring.md
---
# 런타임 성능 모니터링

앱인토스 Unity 게임의 실시간 성능을 모니터링하고 분석하여 최적의 사용자 경험을 제공하는 시스템을 구현해요.

***

## 1. 실시간 성능 모니터링 시스템

### 통합 성능 모니터

```c#
using UnityEngine;
using System.Collections.Generic;
using System.Linq;
using UnityEngine.Profiling;

public class AppsInTossPerformanceMonitor : MonoBehaviour
{
    public static AppsInTossPerformanceMonitor Instance { get; private set; }
    
    [System.Serializable]
    public class PerformanceThresholds
    {
        [Header("FPS 임계값")]
        public float criticalFPS = 15f;
        public float warningFPS = 25f;
        public float targetFPS = 30f;
        
        [Header("메모리 임계값 (MB)")]
        public float criticalMemoryMB = 250f;
        public float warningMemoryMB = 200f;
        public float targetMemoryMB = 150f;
        
        [Header("배터리 효율성")]
        public float batteryEfficiencyWarning = 1.3f; // 네이티브 앱 대비
        public float batteryEfficiencyCritical = 1.5f;
        
        [Header("네트워크 응답시간 (ms)")]
        public float networkWarningMs = 2000f;
        public float networkCriticalMs = 5000f;
    }
    
    [Header("모니터링 설정")]
    public bool enableRealTimeMonitoring = true;
    public bool enableTossAnalytics = true;
    public float monitoringInterval = 1f;
    public int maxDataPoints = 300; // 5분간 데이터
    
    [Header("성능 임계값")]
    public PerformanceThresholds thresholds;
    
    [Header("UI 표시")]
    public bool showDebugUI = false;
    public KeyCode toggleUIKey = KeyCode.F1;
    
    // 성능 데이터 구조
    [System.Serializable]
    public class PerformanceSnapshot
    {
        public float timestamp;
        public float fps;
        public float frameTime;
        public long memoryUsageMB;
        public int drawCalls;
        public int triangles;
        public float cpuTime;
        public float gpuTime;
        public float batteryLevel;
        public string deviceTemperature;
        public NetworkStatus networkStatus;
    }
    
    public enum NetworkStatus
    {
        Good,
        Slow,
        Poor,
        Disconnected
    }
    
    public enum PerformanceAlert
    {
        FPSCritical,
        FPSWarning,
        MemoryCritical,
        MemoryWarning,
        BatteryCritical,
        NetworkSlow,
        DeviceOverheating
    }
    
    // 데이터 저장
    private List<PerformanceSnapshot> performanceHistory = new List<PerformanceSnapshot>();
    private Queue<float> fpsHistory = new Queue<float>();
    private Dictionary<PerformanceAlert, float> lastAlertTime = new Dictionary<PerformanceAlert, float>();
    
    // UI 관련
    private GUIStyle debugUIStyle;
    private bool showUI = false;
    private Rect uiRect = new Rect(10, 10, 350, 400);
    
    // 이벤트
    public System.Action<PerformanceSnapshot> OnPerformanceUpdated;
    public System.Action<PerformanceAlert, float> OnPerformanceAlert;
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeMonitoring();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeMonitoring()
    {
        Debug.Log("앱인토스 성능 모니터링 시작");
        
        // 알림 시간 초기화
        System.Enum.GetValues(typeof(PerformanceAlert)).Cast<PerformanceAlert>()
            .ToList().ForEach(alert => lastAlertTime[alert] = 0f);
        
        // 모니터링 시작
        if (enableRealTimeMonitoring)
        {
            InvokeRepeating(nameof(CollectPerformanceData), 0f, monitoringInterval);
        }
        
        // 앱인토스 특화 이벤트 리스너
        AppsInToss.OnApplicationPause += OnApplicationPause;
        AppsInToss.OnApplicationFocus += OnApplicationFocus;
        AppsInToss.OnLowMemoryWarning += OnLowMemoryWarning;
    }
    
    void Update()
    {
        // 디버그 UI 토글
        if (Input.GetKeyDown(toggleUIKey))
        {
            showUI = !showUI;
        }
    }
    
    void CollectPerformanceData()
    {
        var snapshot = new PerformanceSnapshot
        {
            timestamp = Time.realtimeSinceStartup,
            fps = CalculateCurrentFPS(),
            frameTime = Time.unscaledDeltaTime * 1000f,
            memoryUsageMB = Profiler.GetTotalAllocatedMemory(false) / (1024 * 1024),
            drawCalls = GetDrawCalls(),
            triangles = GetTriangles(),
            cpuTime = Time.deltaTime * 1000f,
            batteryLevel = SystemInfo.batteryLevel,
            deviceTemperature = GetDeviceTemperature(),
            networkStatus = GetNetworkStatus()
        };
        
        // 데이터 저장
        performanceHistory.Add(snapshot);
        
        // 데이터 크기 제한
        if (performanceHistory.Count > maxDataPoints)
        {
            performanceHistory.RemoveAt(0);
        }
        
        // FPS 히스토리 관리
        fpsHistory.Enqueue(snapshot.fps);
        if (fpsHistory.Count > 60) // 1분간 FPS
        {
            fpsHistory.Dequeue();
        }
        
        // 성능 분석 및 경고
        AnalyzePerformance(snapshot);
        
        // 이벤트 발생
        OnPerformanceUpdated?.Invoke(snapshot);
        
        // 앱인토스 분석 시스템에 전송
        if (enableTossAnalytics)
        {
            SendPerformanceAnalytics(snapshot);
        }
    }
    
    float CalculateCurrentFPS()
    {
        if (Time.unscaledDeltaTime > 0)
        {
            return 1.0f / Time.unscaledDeltaTime;
        }
        return 0f;
    }
    
    int GetDrawCalls()
    {
        // Unity 2019.3 이상에서는 다른 방법 사용 필요
        return UnityEngine.Rendering.FrameDebugger.enabled ? 
            UnityEngine.Rendering.FrameDebugger.GetFrameEventCount() : 0;
    }
    
    int GetTriangles()
    {
        // 현재 프레임의 삼각형 수 추정
        var renderers = FindObjectsOfType<MeshRenderer>();
        int totalTriangles = 0;
        
        foreach (var renderer in renderers)
        {
            if (renderer.isVisible)
            {
                var meshFilter = renderer.GetComponent<MeshFilter>();
                if (meshFilter != null && meshFilter.mesh != null)
                {
                    totalTriangles += meshFilter.mesh.triangles.Length / 3;
                }
            }
        }
        
        return totalTriangles;
    }
    
    string GetDeviceTemperature()
    {
        // 플랫폼별 온도 정보 (앱인토스 네이티브 API 사용)
        return AppsInToss.GetDeviceTemperature();
    }
    
    NetworkStatus GetNetworkStatus()
    {
        // 네트워크 상태 확인 (앱인토스 네이티브 API 사용)
        var pingTime = AppsInToss.GetNetworkPingTime();
        
        if (pingTime < 0) return NetworkStatus.Disconnected;
        else if (pingTime < 100) return NetworkStatus.Good;
        else if (pingTime < 500) return NetworkStatus.Slow;
        else return NetworkStatus.Poor;
    }
    
    void AnalyzePerformance(PerformanceSnapshot snapshot)
    {
        float currentTime = Time.realtimeSinceStartup;
        
        // FPS 체크
        if (snapshot.fps < thresholds.criticalFPS)
        {
            TriggerAlert(PerformanceAlert.FPSCritical, snapshot.fps, currentTime);
        }
        else if (snapshot.fps < thresholds.warningFPS)
        {
            TriggerAlert(PerformanceAlert.FPSWarning, snapshot.fps, currentTime);
        }
        
        // 메모리 체크
        if (snapshot.memoryUsageMB > thresholds.criticalMemoryMB)
        {
            TriggerAlert(PerformanceAlert.MemoryCritical, snapshot.memoryUsageMB, currentTime);
        }
        else if (snapshot.memoryUsageMB > thresholds.warningMemoryMB)
        {
            TriggerAlert(PerformanceAlert.MemoryWarning, snapshot.memoryUsageMB, currentTime);
        }
        
        // 배터리 효율성 체크
        float batteryDrain = CalculateBatteryDrainRate();
        if (batteryDrain > thresholds.batteryEfficiencyCritical)
        {
            TriggerAlert(PerformanceAlert.BatteryCritical, batteryDrain, currentTime);
        }
        
        // 네트워크 상태 체크
        if (snapshot.networkStatus == NetworkStatus.Poor || snapshot.networkStatus == NetworkStatus.Slow)
        {
            TriggerAlert(PerformanceAlert.NetworkSlow, 0f, currentTime);
        }
        
        // 기기 온도 체크
        if (snapshot.deviceTemperature.Contains("Hot") || snapshot.deviceTemperature.Contains("Overheating"))
        {
            TriggerAlert(PerformanceAlert.DeviceOverheating, 0f, currentTime);
        }
    }
    
    void TriggerAlert(PerformanceAlert alertType, float value, float currentTime)
    {
        // 중복 알림 방지 (30초 간격)
        if (currentTime - lastAlertTime[alertType] < 30f)
        {
            return;
        }
        
        lastAlertTime[alertType] = currentTime;
        
        Debug.LogWarning($"성능 알림: {alertType} - 값: {value:F2}");
        
        // 이벤트 발생
        OnPerformanceAlert?.Invoke(alertType, value);
        
        // 앱인토스에 성능 이슈 리포트
        ReportPerformanceIssue(alertType, value);
        
        // 자동 최적화 시도
        AttemptAutoOptimization(alertType, value);
    }
    
    float CalculateBatteryDrainRate()
    {
        // 배터리 소모율 계산 (단순화된 버전)
        if (performanceHistory.Count < 60) return 0f; // 1분 미만 데이터
        
        var recent = performanceHistory.Skip(performanceHistory.Count - 60).ToList();
        var startBattery = recent.First().batteryLevel;
        var endBattery = recent.Last().batteryLevel;
        
        if (startBattery <= 0 || endBattery <= 0) return 0f;
        
        float drainPerMinute = (startBattery - endBattery) * 60f;
        return drainPerMinute / 0.5f; // 네이티브 앱 기준 대비 비율
    }
    
    void ReportPerformanceIssue(PerformanceAlert alertType, float value)
    {
        var issueData = new Dictionary<string, object>
        {
            {"alert_type", alertType.ToString()},
            {"value", value},
            {"device_model", SystemInfo.deviceModel},
            {"memory_size", SystemInfo.systemMemorySize},
            {"graphics_device", SystemInfo.graphicsDeviceName},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.ReportPerformanceIssue($"runtime_performance_{alertType.ToString().ToLower()}", issueData);
    }
    
    void AttemptAutoOptimization(PerformanceAlert alertType, float value)
    {
        switch (alertType)
        {
            case PerformanceAlert.FPSCritical:
            case PerformanceAlert.FPSWarning:
                OptimizeForFPS();
                break;
                
            case PerformanceAlert.MemoryCritical:
            case PerformanceAlert.MemoryWarning:
                OptimizeMemoryUsage();
                break;
                
            case PerformanceAlert.BatteryCritical:
                OptimizeForBattery();
                break;
                
            case PerformanceAlert.DeviceOverheating:
                ReducePerformanceLoad();
                break;
        }
    }
    
    void OptimizeForFPS()
    {
        // FPS 최적화
        QualitySettings.masterTextureLimit = Mathf.Min(QualitySettings.masterTextureLimit + 1, 3);
        QualitySettings.shadowDistance *= 0.8f;
        QualitySettings.lodBias *= 0.9f;
        
        Debug.Log("자동 FPS 최적화 적용");
    }
    
    void OptimizeMemoryUsage()
    {
        // 메모리 최적화
        System.GC.Collect();
        Resources.UnloadUnusedAssets();
        
        // 에셋 캐시 정리
        if (AppsInTossResourceManager.Instance != null)
        {
            AppsInTossResourceManager.Instance.ClearCache(ResourcePriority.Low);
        }
        
        Debug.Log("자동 메모리 최적화 적용");
    }
    
    void OptimizeForBattery()
    {
        // 배터리 최적화
        Application.targetFrameRate = Mathf.Min(Application.targetFrameRate, 30);
        QualitySettings.vSyncCount = 0;
        
        Debug.Log("자동 배터리 최적화 적용");
    }
    
    void ReducePerformanceLoad()
    {
        // 성능 부하 감소
        Application.targetFrameRate = 20;
        QualitySettings.masterTextureLimit = 2;
        QualitySettings.shadowDistance *= 0.5f;
        
        Debug.Log("기기 과열로 인한 성능 부하 감소");
    }
    
    void SendPerformanceAnalytics(PerformanceSnapshot snapshot)
    {
        // 10초마다 한 번씩만 전송 (데이터 절약)
        if (Mathf.FloorToInt(snapshot.timestamp) % 10 != 0) return;
        
        var analyticsData = new Dictionary<string, object>
        {
            {"fps", snapshot.fps},
            {"memory_mb", snapshot.memoryUsageMB},
            {"draw_calls", snapshot.drawCalls},
            {"triangles", snapshot.triangles},
            {"battery_level", snapshot.batteryLevel},
            {"network_status", snapshot.networkStatus.ToString()},
            {"device_temperature", snapshot.deviceTemperature},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("runtime_performance", analyticsData);
    }
    
    // 이벤트 핸들러
    void OnApplicationPause(bool pauseStatus)
    {
        if (pauseStatus)
        {
            // 백그라운드 진입 시 성능 리포트 전송
            SendPerformanceSummary();
        }
        else
        {
            // 포그라운드 복귀 시 모니터링 재시작
            performanceHistory.Clear();
        }
    }
    
    void OnApplicationFocus(bool hasFocus)
    {
        if (hasFocus)
        {
            Debug.Log("앱 포커스 복귀 - 성능 모니터링 재시작");
        }
    }
    
    void OnLowMemoryWarning()
    {
        Debug.LogWarning("시스템 메모리 부족 경고");
        TriggerAlert(PerformanceAlert.MemoryCritical, GetCurrentMemoryUsage(), Time.realtimeSinceStartup);
        OptimizeMemoryUsage();
    }
    
    float GetCurrentMemoryUsage()
    {
        return Profiler.GetTotalAllocatedMemory(false) / (1024f * 1024f);
    }
    
    void SendPerformanceSummary()
    {
        if (performanceHistory.Count == 0) return;
        
        var summary = GeneratePerformanceSummary();
        
        var summaryData = new Dictionary<string, object>
        {
            {"session_duration", summary.sessionDuration},
            {"average_fps", summary.averageFPS},
            {"min_fps", summary.minFPS},
            {"max_memory_mb", summary.maxMemoryMB},
            {"average_memory_mb", summary.averageMemoryMB},
            {"total_alerts", summary.totalAlerts},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("performance_session_summary", summaryData);
    }
    
    public PerformanceSummary GeneratePerformanceSummary()
    {
        if (performanceHistory.Count == 0)
        {
            return new PerformanceSummary();
        }
        
        var summary = new PerformanceSummary
        {
            sessionDuration = performanceHistory.Last().timestamp - performanceHistory.First().timestamp,
            averageFPS = performanceHistory.Average(p => p.fps),
            minFPS = performanceHistory.Min(p => p.fps),
            maxFPS = performanceHistory.Max(p => p.fps),
            averageMemoryMB = performanceHistory.Average(p => p.memoryUsageMB),
            maxMemoryMB = performanceHistory.Max(p => p.memoryUsageMB),
            totalAlerts = lastAlertTime.Values.Count(t => t > 0)
        };
        
        return summary;
    }
    
    // 디버그 UI
    void OnGUI()
    {
        if (!showUI || !showDebugUI) return;
        
        InitializeGUIStyle();
        
        uiRect = GUILayout.Window(0, uiRect, DrawDebugWindow, "앱인토스 성능 모니터", debugUIStyle);
    }
    
    void InitializeGUIStyle()
    {
        if (debugUIStyle == null)
        {
            debugUIStyle = new GUIStyle(GUI.skin.window);
            debugUIStyle.fontSize = 12;
        }
    }
    
    void DrawDebugWindow(int windowID)
    {
        if (performanceHistory.Count == 0)
        {
            GUILayout.Label("성능 데이터 수집 중...");
            GUI.DragWindow();
            return;
        }
        
        var latest = performanceHistory.Last();
        
        GUILayout.BeginVertical();
        
        // 현재 성능 정보
        GUILayout.Label($"FPS: {latest.fps:F1}", GetColorStyle(latest.fps, thresholds.warningFPS, thresholds.criticalFPS, false));
        GUILayout.Label($"메모리: {latest.memoryUsageMB}MB", GetColorStyle(latest.memoryUsageMB, thresholds.warningMemoryMB, thresholds.criticalMemoryMB, true));
        GUILayout.Label($"Draw Calls: {latest.drawCalls}");
        GUILayout.Label($"Triangles: {latest.triangles:N0}");
        GUILayout.Label($"배터리: {(latest.batteryLevel * 100):F0}%");
        GUILayout.Label($"네트워크: {latest.networkStatus}");
        GUILayout.Label($"온도: {latest.deviceTemperature}");
        
        GUILayout.Space(10);
        
        // 평균값
        if (performanceHistory.Count > 10)
        {
            float avgFPS = performanceHistory.Skip(performanceHistory.Count - 10).Average(p => p.fps);
            float avgMemory = performanceHistory.Skip(performanceHistory.Count - 10).Average(p => p.memoryUsageMB);
            
            GUILayout.Label($"10초 평균 FPS: {avgFPS:F1}");
            GUILayout.Label($"10초 평균 메모리: {avgMemory:F1}MB");
        }
        
        GUILayout.Space(10);
        
        // 제어 버튼
        if (GUILayout.Button("메모리 정리"))
        {
            OptimizeMemoryUsage();
        }
        
        if (GUILayout.Button("성능 리포트 전송"))
        {
            SendPerformanceSummary();
        }
        
        GUILayout.EndVertical();
        
        GUI.DragWindow();
    }
    
    GUIStyle GetColorStyle(float value, float warningThreshold, float criticalThreshold, bool higherIsWorse)
    {
        var style = new GUIStyle(GUI.skin.label);
        
        bool critical = higherIsWorse ? value > criticalThreshold : value < criticalThreshold;
        bool warning = higherIsWorse ? value > warningThreshold : value < warningThreshold;
        
        if (critical)
        {
            style.normal.textColor = Color.red;
        }
        else if (warning)
        {
            style.normal.textColor = Color.yellow;
        }
        else
        {
            style.normal.textColor = Color.green;
        }
        
        return style;
    }
    
    // 공개 API
    public PerformanceSnapshot GetCurrentPerformance()
    {
        return performanceHistory.LastOrDefault();
    }
    
    public List<PerformanceSnapshot> GetPerformanceHistory(int lastNSeconds = 60)
    {
        if (performanceHistory.Count == 0) return new List<PerformanceSnapshot>();
        
        float currentTime = performanceHistory.Last().timestamp;
        return performanceHistory.Where(p => currentTime - p.timestamp <= lastNSeconds).ToList();
    }
    
    public void SetMonitoringEnabled(bool enabled)
    {
        if (enabled && !IsInvoking(nameof(CollectPerformanceData)))
        {
            InvokeRepeating(nameof(CollectPerformanceData), 0f, monitoringInterval);
        }
        else if (!enabled && IsInvoking(nameof(CollectPerformanceData)))
        {
            CancelInvoke(nameof(CollectPerformanceData));
        }
    }
}

[System.Serializable]
public class PerformanceSummary
{
    public float sessionDuration;
    public float averageFPS;
    public float minFPS;
    public float maxFPS;
    public float averageMemoryMB;
    public float maxMemoryMB;
    public int totalAlerts;
}
```

실시간 성능 모니터링을 통해 사용자 경험을 지속적으로 개선하세요. 앱인토스 환경에서는 배터리 효율성과 메모리 사용량이 특히 중요해요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/UI/Layout.md
description: Bedrock 프레임워크 레퍼런스 문서입니다.
---

# 레이아웃

레이아웃은 여러 페이지에서 반복되는 UI 요소(헤더, 네비게이션 바, 푸터 등)를 일관성 있게 관리하기 위한 구조예요.\
공통 레이아웃을 정의하면 코드 중복을 줄이고, 일관된 사용자 경험을 제공할 수 있어요.

## 레이아웃 파일 만들기

레이아웃은 `_layout.tsx` 파일을 생성해서 정의해요.\
파일의 위치에 따라 적용되는 범위가 달라져요.

```tsx
import { PropsWithChildren } from "react";

export default function Layout({ children }: PropsWithChildren) {
  return <>{children}</>;
}
```

## 레이아웃 적용 범위 설정하기

레이아웃은 파일 경로에 따라 자동으로 적용돼요.

* `pages/_layout.tsx`: 모든 페이지에 전역 적용돼요.
* `pages/about/_layout.tsx`: `intoss://{서비스명}/about` 하위의 모든 페이지에만 적용돼요.

레이아웃은 중첩해서 사용할 수 있어요.\
여러 레이아웃이 함께 있을 때는 상위 디렉토리의 레이아웃부터 순서대로 적용돼요.

```
pages/
├── _layout.tsx          // 전역 레이아웃
├── about/
│   ├── _layout.tsx     // about 섹션 레이아웃
│   ├── index.tsx       // about 메인 페이지
│   └── team.tsx        // 팀 소개 페이지
└── index.tsx           // 메인 페이지
```

예를 들어, 위와 같은 구조라면 `about/team.tsx` 페이지는 아래 순서로 레이아웃이 적용돼요.

1. `pages/_layout.tsx` (전역 레이아웃)
2. `pages/about/_layout.tsx` (섹션 레이아웃)
3. `pages/about/team.tsx` (실제 페이지 컴포넌트)

이렇게 구성하면 전역적으로 필요한 UI 요소와, 특정 섹션에서만 필요한 UI 요소를 분리해서 관리할 수 있어요.

## 레이아웃 예시

### 전역 레이아웃

모든 페이지에 공통으로 적용되는 레이아웃을 만들어볼게요.

::: code-group

```tsx [pages/_layout.tsx]
import { PropsWithChildren } from "react";
import { View } from "react-native";
import { Header } from "../components/Header";
import { Footer } from "../components/Footer";

export default function Layout({ children }: PropsWithChildren) {
  return (
    <View style={{ flex: 1 }}>
      <Header />
      {children}
      <Footer />
    </View>
  );
}
```

```tsx [components/Header.tsx]
import { View, Text, StyleSheet } from "react-native";

export function Header() {
  return (
    <View style={styles.header}>
      <Text style={styles.title}>My App</Text>
      <View style={styles.nav}>
        <Text style={styles.navItem}>홈</Text>
        <Text style={styles.navItem}>소개</Text>
        <Text style={styles.navItem}>설정</Text>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  header: {
    padding: 16,
    backgroundColor: "#ffffff",
    borderBottomWidth: 1,
    borderBottomColor: "#e5e5e5",
  },
  title: {
    fontSize: 24,
    fontWeight: "bold",
    marginBottom: 8,
  },
  nav: {
    flexDirection: "row",
    gap: 16,
  },
  navItem: {
    fontSize: 16,
    color: "#666666",
  },
});
```

```tsx [components/Footer.tsx]
import { View, Text, StyleSheet } from "react-native";

export function Footer() {
  return (
    <View style={styles.footer}>
      <Text style={styles.copyright}>© 2024 My App. All rights reserved.</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  footer: {
    padding: 16,
    backgroundColor: "#f5f5f5",
    alignItems: "center",
  },
  copyright: {
    fontSize: 14,
    color: "#666666",
  },
});
```

:::

### 섹션별 레이아웃

특정 섹션에서만 사용하는 레이아웃을 만들 수 있어요.

::: code-group

```tsx [pages/about/_layout.tsx]
import { PropsWithChildren } from "react";
import { View } from "react-native";
import { AboutSidebar } from "../../components/AboutSidebar";

export default function AboutLayout({ children }: PropsWithChildren) {
  return (
    <View style={{ flexDirection: "row" }}>
      <AboutSidebar />
      <View style={{ flex: 1 }}>{children}</View>
    </View>
  );
}
```

```tsx [components/AboutSidebar.tsx]
import { View, Text, StyleSheet } from "react-native";

export function AboutSidebar() {
  return (
    <View style={styles.sidebar}>
      <Text style={styles.title}>About</Text>
      <View style={styles.menu}>
        <Text style={styles.menuItem}>회사 소개</Text>
        <Text style={styles.menuItem}>팀 소개</Text>
        <Text style={styles.menuItem}>연혁</Text>
        <Text style={styles.menuItem}>오시는 길</Text>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  sidebar: {
    width: 200,
    padding: 16,
    backgroundColor: "#f8f9fa",
    borderRightWidth: 1,
    borderRightColor: "#e5e5e5",
  },
  title: {
    fontSize: 20,
    fontWeight: "bold",
    marginBottom: 16,
  },
  menu: {
    gap: 12,
  },
  menuItem: {
    fontSize: 16,
    color: "#495057",
  },
});
```

:::

## 레이아웃에서 쿼리 파라미터 받아오기

레이아웃에서도 쿼리 파라미터를 사용할 수 있어요.\
`useParams` 훅을 이용하면 현재 화면의 파라미터를 읽어서 동적으로 활용할 수 있어요.

### `useParams` 훅 사용 예시

아래 예시는 URL 쿼리 파라미터로 전달된 `title` 값을 가져와서 화면 상단 제목으로 표시해요.

::: code-group

```tsx [pages/_layout.tsx]
import { useParams } from "@granite-js/react-native";
import { PropsWithChildren } from "react";
import { View, Text } from "react-native";

export default function Layout({ children }: PropsWithChildren) {
  // 현재 화면의 파라미터를 가져와요.
  const params = useParams({ strict: false });

  // 'title' 파라미터를 가져오고 기본값을 설정해요.
  const title = params?.title ?? "기본 제목";

  return (
    <View style={{ flex: 1 }}>
      {/* 동적으로 생성된 헤더 */}
      <View style={{ padding: 16, backgroundColor: "#f0f0f0" }}>
        <Text style={{ fontSize: 20, fontWeight: "bold" }}>{title}</Text>
      </View>
      {/* 자식 컴포넌트를 렌더링 */}
      <View style={{ flex: 1 }}>{children}</View>
    </View>
  );
}
```

:::

## 참고 문서

* [화면 이동하기](../화면%20이동/routing)
* [쿼리 파라미터 사용하기](../화면%20제어/useParams.html#쿼리-파라미터-사용하기)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/rendering.md
---
# 렌더링 최적화

앱인토스 Unity 게임의 렌더링 성능을 극대화하기 위한 포괄적인 최적화 기법과 실무 가이드를 제공해요.

***

## 1. 드로우콜 최적화

### 배치 렌더링 시스템

```c#
public class AppsInTossDrawCallOptimizer : MonoBehaviour
{
    [System.Serializable]
    public class BatchGroup
    {
        public string groupName;
        public Material sharedMaterial;
        public List<MeshRenderer> renderers = new List<MeshRenderer>();
        public bool enableInstancing = true;
        public int maxInstancesPerBatch = 1000;
    }
    
    [Header("드로우콜 최적화 설정")]
    public BatchGroup[] batchGroups;
    public bool enableAutoBatching = true;
    public bool enableGPUInstancing = true;
    public bool enableStaticBatching = true;
    
    [Header("앱인토스 최적화")]
    public int targetDrawCallsPerFrame = 50; // 앱인토스 권장 제한
    public bool adaptToPerformance = true;
    
    private Dictionary<Material, List<MeshRenderer>> materialGroups = new Dictionary<Material, List<MeshRenderer>>();
    private int currentDrawCalls = 0;
    
    void Start()
    {
        InitializeDrawCallOptimization();
        OptimizeStaticGeometry();
        StartCoroutine(MonitorDrawCalls());
    }
    
    void InitializeDrawCallOptimization()
    {
        // 씬의 모든 렌더러를 머티리얼별로 그룹화
        GroupRenderersByMaterial();
        
        // 배치 그룹 설정
        SetupBatchGroups();
        
        // GPU 인스턴싱 설정
        if (enableGPUInstancing)
        {
            SetupGPUInstancing();
        }
        
        Debug.Log($"드로우콜 최적화 초기화 완료 - 목표: {targetDrawCallsPerFrame} 드로우콜/프레임");
    }
    
    void GroupRenderersByMaterial()
    {
        var allRenderers = FindObjectsOfType<MeshRenderer>();
        
        foreach (var renderer in allRenderers)
        {
            var material = renderer.sharedMaterial;
            if (material != null)
            {
                if (!materialGroups.ContainsKey(material))
                {
                    materialGroups[material] = new List<MeshRenderer>();
                }
                materialGroups[material].Add(renderer);
            }
        }
        
        Debug.Log($"머티리얼 그룹화 완료: {materialGroups.Count}개 그룹");
    }
    
    void SetupBatchGroups()
    {
        foreach (var group in batchGroups)
        {
            if (group.sharedMaterial == null) continue;
            
            // 같은 머티리얼을 사용하는 렌더러들을 배치 그룹에 추가
            if (materialGroups.ContainsKey(group.sharedMaterial))
            {
                group.renderers.AddRange(materialGroups[group.sharedMaterial]);
                
                // 배치 최적화 적용
                OptimizeBatchGroup(group);
            }
        }
    }
    
    void OptimizeBatchGroup(BatchGroup group)
    {
        if (group.renderers.Count <= 1) return;
        
        // 렌더러들의 메시를 결합할 수 있는지 확인
        var meshFilters = group.renderers
            .Select(r => r.GetComponent<MeshFilter>())
            .Where(mf => mf != null && mf.sharedMesh != null)
            .ToArray();
        
        if (meshFilters.Length < 2) return;
        
        // 정적 배칭 적용
        if (enableStaticBatching && AreRenderersStatic(group.renderers))
        {
            ApplyStaticBatching(group, meshFilters);
        }
        // 동적 배칭 적용
        else if (enableAutoBatching)
        {
            ApplyDynamicBatching(group);
        }
    }
    
    bool AreRenderersStatic(List<MeshRenderer> renderers)
    {
        return renderers.All(r => r.gameObject.isStatic);
    }
    
    void ApplyStaticBatching(BatchGroup group, MeshFilter[] meshFilters)
    {
        // Unity의 정적 배칭 사용
        var gameObjects = meshFilters.Select(mf => mf.gameObject).ToArray();
        StaticBatchingUtility.Combine(gameObjects, gameObjects[0].transform.parent?.gameObject);
        
        Debug.Log($"정적 배칭 적용: {group.groupName} - {gameObjects.Length}개 오브젝트");
    }
    
    void ApplyDynamicBatching(BatchGroup group)
    {
        // 동적 배칭을 위한 설정 최적화
        foreach (var renderer in group.renderers)
        {
            // 머티리얼 인스턴스화 방지
            if (renderer.material != group.sharedMaterial)
            {
                renderer.sharedMaterial = group.sharedMaterial;
            }
            
            // 스케일 정규화 (동적 배칭 조건)
            if (renderer.transform.localScale != Vector3.one)
            {
                var scale = renderer.transform.localScale;
                if (Mathf.Abs(scale.x - scale.y) < 0.01f && 
                    Mathf.Abs(scale.y - scale.z) < 0.01f)
                {
                    renderer.transform.localScale = Vector3.one * scale.x;
                }
            }
        }
        
        Debug.Log($"동적 배칭 최적화: {group.groupName}");
    }
    
    void SetupGPUInstancing()
    {
        foreach (var group in materialGroups)
        {
            var material = group.Key;
            var renderers = group.Value;
            
            if (renderers.Count > 10 && CanUseInstancing(renderers))
            {
                EnableMaterialInstancing(material);
                SetupInstancedRendering(renderers);
            }
        }
    }
    
    bool CanUseInstancing(List<MeshRenderer> renderers)
    {
        if (renderers.Count < 2) return false;
        
        // 같은 메시를 사용하는지 확인
        var firstMesh = renderers[0].GetComponent<MeshFilter>()?.sharedMesh;
        if (firstMesh == null) return false;
        
        return renderers.All(r => {
            var mf = r.GetComponent<MeshFilter>();
            return mf != null && mf.sharedMesh == firstMesh;
        });
    }
    
    void EnableMaterialInstancing(Material material)
    {
        // GPU 인스턴싱 키워드 활성화
        material.EnableKeyword("_INSTANCING_ON");
        material.enableInstancing = true;
        
        // 앱인토스 특화 키워드
        material.EnableKeyword("APPS_IN_TOSS_INSTANCED");
    }
    
    void SetupInstancedRendering(List<MeshRenderer> renderers)
    {
        // 인스턴스 데이터 준비
        var matrices = new List<Matrix4x4>();
        var colors = new List<Vector4>();
        
        foreach (var renderer in renderers)
        {
            matrices.Add(renderer.transform.localToWorldMatrix);
            colors.Add(renderer.material.color);
            
            // 원본 렌더러는 비활성화
            renderer.enabled = false;
        }
        
        // 인스턴스드 렌더링 설정
        CreateInstancedRenderer(renderers[0], matrices, colors);
    }
    
    void CreateInstancedRenderer(MeshRenderer template, List<Matrix4x4> matrices, List<Vector4> colors)
    {
        var instancedGO = new GameObject($"Instanced_{template.name}");
        var instancedRenderer = instancedGO.AddComponent<InstancedMeshRenderer>();
        
        instancedRenderer.Initialize(
            template.GetComponent<MeshFilter>().sharedMesh,
            template.sharedMaterial,
            matrices.ToArray(),
            colors.ToArray()
        );
    }
    
    void OptimizeStaticGeometry()
    {
        if (!enableStaticBatching) return;
        
        // 정적 오브젝트들을 찾아 배칭
        var staticObjects = FindObjectsOfType<GameObject>()
            .Where(go => go.isStatic && go.GetComponent<MeshRenderer>() != null)
            .ToArray();
        
        if (staticObjects.Length > 1)
        {
            StaticBatchingUtility.Combine(staticObjects, null);
            Debug.Log($"정적 배칭 완료: {staticObjects.Length}개 오브젝트");
        }
    }
    
    System.Collections.IEnumerator MonitorDrawCalls()
    {
        while (true)
        {
            yield return new WaitForSeconds(1f);
            
            // 현재 드로우콜 수 확인 (Unity Stats 활용)
            int currentDrawCalls = GetCurrentDrawCalls();
            
            if (currentDrawCalls > targetDrawCallsPerFrame && adaptToPerformance)
            {
                Debug.LogWarning($"드로우콜 수 초과: {currentDrawCalls} > {targetDrawCallsPerFrame}");
                ApplyEmergencyOptimization();
            }
            
            // 앱인토스 분석에 드로우콜 데이터 전송
            AppsInToss.ReportRenderingStats(currentDrawCalls, "draw_calls");
        }
    }
    
    int GetCurrentDrawCalls()
    {
        // Unity의 내부 통계를 통해 드로우콜 수 추정
        // 실제로는 Unity Profiler API를 사용해야 함
        return UnityEngine.Rendering.FrameDebugger.enabled ? 
            UnityEngine.Rendering.FrameDebugger.GetFrameEventCount() : 0;
    }
    
    void ApplyEmergencyOptimization()
    {
        Debug.Log("긴급 드로우콜 최적화 적용");
        
        // 가장 비효율적인 렌더러들 비활성화
        var renderers = FindObjectsOfType<MeshRenderer>()
            .Where(r => !IsEssentialRenderer(r))
            .OrderByDescending(r => GetRendererComplexity(r))
            .Take(10)
            .ToArray();
        
        foreach (var renderer in renderers)
        {
            renderer.enabled = false;
        }
        
        AppsInToss.ReportOptimizationApplied("emergency_drawcall_reduction", renderers.Length);
    }
    
    bool IsEssentialRenderer(MeshRenderer renderer)
    {
        // 필수 렌더러인지 판단 (UI, 플레이어, 토스 브랜딩 등)
        return renderer.gameObject.layer == LayerMask.NameToLayer("UI") ||
               renderer.name.Contains("Player") ||
               renderer.name.Contains("Toss") ||
               renderer.name.Contains("Essential");
    }
    
    float GetRendererComplexity(MeshRenderer renderer)
    {
        var meshFilter = renderer.GetComponent<MeshFilter>();
        if (meshFilter?.sharedMesh == null) return 0f;
        
        // 복잡도 계산 (버텍스 수 + 머티리얼 복잡도)
        float complexity = meshFilter.sharedMesh.vertexCount;
        
        if (renderer.sharedMaterial != null)
        {
            complexity += renderer.sharedMaterial.passCount * 100f;
            
            // 투명 머티리얼은 더 비용이 높음
            if (renderer.sharedMaterial.renderQueue >= 3000)
            {
                complexity *= 1.5f;
            }
        }
        
        return complexity;
    }
    
    // 공개 API
    public void ForceOptimization()
    {
        ApplyEmergencyOptimization();
    }
    
    public int GetCurrentBatchCount()
    {
        return batchGroups.Length;
    }
    
    public void AddToBatchGroup(string groupName, MeshRenderer renderer)
    {
        var group = System.Array.Find(batchGroups, g => g.groupName == groupName);
        if (group != null && !group.renderers.Contains(renderer))
        {
            group.renderers.Add(renderer);
            OptimizeBatchGroup(group);
        }
    }
}

// 인스턴스드 렌더링 컴포넌트
public class InstancedMeshRenderer : MonoBehaviour
{
    private Mesh mesh;
    private Material material;
    private Matrix4x4[] matrices;
    private Vector4[] colors;
    private MaterialPropertyBlock propertyBlock;
    
    public void Initialize(Mesh mesh, Material material, Matrix4x4[] matrices, Vector4[] colors)
    {
        this.mesh = mesh;
        this.material = material;
        this.matrices = matrices;
        this.colors = colors;
        
        propertyBlock = new MaterialPropertyBlock();
        propertyBlock.SetVectorArray("_InstanceColor", colors);
    }
    
    void Update()
    {
        if (mesh != null && material != null && matrices != null)
        {
            Graphics.DrawMeshInstanced(mesh, 0, material, matrices, matrices.Length, propertyBlock);
        }
    }
}
```

***

## 2. LOD 시스템 최적화

### 적응적 LOD 관리

```c#
public class AppsInTossLODManager : MonoBehaviour
{
    [System.Serializable]
    public class LODSettings
    {
        public float[] distances = { 10f, 25f, 50f };
        public float[] qualityLevels = { 1.0f, 0.7f, 0.4f };
        public bool enableCulling = true;
        public float cullDistance = 100f;
    }
    
    [Header("LOD 설정")]
    public LODSettings lodSettings;
    public bool enableDynamicLOD = true;
    public bool adaptToPerformance = true;
    
    [Header("앱인토스 최적화")]
    public float performanceThreshold = 25f; // FPS
    public bool enableAggressiveLOD = true;
    
    private LODGroup[] lodGroups;
    private Camera mainCamera;
    private float[] originalDistances;
    
    void Start()
    {
        mainCamera = Camera.main;
        InitializeLODSystem();
        
        if (enableDynamicLOD)
        {
            InvokeRepeating(nameof(UpdateDynamicLOD), 1f, 1f);
        }
    }
    
    void InitializeLODSystem()
    {
        lodGroups = FindObjectsOfType<LODGroup>();
        originalDistances = new float[lodSettings.distances.Length];
        System.Array.Copy(lodSettings.distances, originalDistances, lodSettings.distances.Length);
        
        foreach (var lodGroup in lodGroups)
        {
            OptimizeLODGroup(lodGroup);
        }
        
        Debug.Log($"LOD 시스템 초기화: {lodGroups.Length}개 LOD 그룹");
    }
    
    void OptimizeLODGroup(LODGroup lodGroup)
    {
        var lods = lodGroup.GetLODs();
        
        for (int i = 0; i < lods.Length; i++)
        {
            if (i < lodSettings.distances.Length)
            {
                // 앱인토스 환경에 맞는 LOD 거리 조정
                float adjustedDistance = lodSettings.distances[i];
                
                // 모바일 환경에서는 더 가까운 거리에서 LOD 적용
                if (Application.isMobilePlatform)
                {
                    adjustedDistance *= 0.7f;
                }
                
                lods[i].screenRelativeTransitionHeight = adjustedDistance / 100f;
            }
            
            // LOD 레벨별 품질 조정
            OptimizeLODLevel(lods[i], i);
        }
        
        lodGroup.SetLODs(lods);
    }
    
    void OptimizeLODLevel(LOD lod, int level)
    {
        foreach (var renderer in lod.renderers)
        {
            if (renderer == null) continue;
            
            // LOD 레벨에 따른 머티리얼 품질 조정
            var material = renderer.sharedMaterial;
            if (material != null)
            {
                float qualityLevel = level < lodSettings.qualityLevels.Length ? 
                    lodSettings.qualityLevels[level] : 0.2f;
                
                SetMaterialQuality(material, qualityLevel);
            }
            
            // 그림자 설정 조정
            if (level > 0)
            {
                renderer.shadowCastingMode = level > 1 ? 
                    UnityEngine.Rendering.ShadowCastingMode.Off : 
                    UnityEngine.Rendering.ShadowCastingMode.On;
                
                renderer.receiveShadows = level == 0;
            }
        }
    }
    
    void SetMaterialQuality(Material material, float quality)
    {
        if (material.HasProperty("_QualityLevel"))
        {
            material.SetFloat("_QualityLevel", quality);
        }
        
        // 텍스처 품질 조정
        if (quality < 0.5f)
        {
            material.mainTextureScale = Vector2.one * 0.5f; // 텍스처 해상도 감소
        }
        else if (quality < 0.8f)
        {
            material.mainTextureScale = Vector2.one * 0.75f;
        }
    }
    
    void UpdateDynamicLOD()
    {
        if (!adaptToPerformance || mainCamera == null) return;
        
        // 현재 성능 확인
        float currentFPS = GetCurrentFPS();
        
        if (currentFPS < performanceThreshold)
        {
            ApplyAggressiveLOD();
        }
        else if (currentFPS > performanceThreshold * 1.5f)
        {
            RestoreNormalLOD();
        }
        
        // 카메라 위치 기반 동적 LOD 조정
        UpdateDistanceBasedLOD();
    }
    
    float GetCurrentFPS()
    {
        return 1.0f / Time.unscaledDeltaTime;
    }
    
    void ApplyAggressiveLOD()
    {
        Debug.Log("성능 부족으로 적극적 LOD 적용");
        
        // LOD 거리를 줄여서 더 빨리 낮은 품질로 전환
        for (int i = 0; i < lodSettings.distances.Length; i++)
        {
            lodSettings.distances[i] = originalDistances[i] * 0.6f;
        }
        
        UpdateAllLODGroups();
        
        AppsInToss.ReportOptimizationApplied("aggressive_lod", "성능 최적화");
    }
    
    void RestoreNormalLOD()
    {
        // 원래 LOD 설정 복원
        System.Array.Copy(originalDistances, lodSettings.distances, originalDistances.Length);
        UpdateAllLODGroups();
    }
    
    void UpdateAllLODGroups()
    {
        foreach (var lodGroup in lodGroups)
        {
            OptimizeLODGroup(lodGroup);
        }
    }
    
    void UpdateDistanceBasedLOD()
    {
        if (mainCamera == null) return;
        
        Vector3 cameraPos = mainCamera.transform.position;
        
        foreach (var lodGroup in lodGroups)
        {
            if (lodGroup == null) continue;
            
            float distance = Vector3.Distance(cameraPos, lodGroup.transform.position);
            
            // 매우 먼 거리의 오브젝트는 컬링
            if (lodSettings.enableCulling && distance > lodSettings.cullDistance)
            {
                SetLODGroupVisible(lodGroup, false);
            }
            else
            {
                SetLODGroupVisible(lodGroup, true);
                
                // 앱인토스 환경에서 거리별 추가 최적화
                if (distance > lodSettings.cullDistance * 0.8f)
                {
                    ApplyDistantOptimization(lodGroup);
                }
            }
        }
    }
    
    void SetLODGroupVisible(LODGroup lodGroup, bool visible)
    {
        var lods = lodGroup.GetLODs();
        foreach (var lod in lods)
        {
            foreach (var renderer in lod.renderers)
            {
                if (renderer != null)
                {
                    renderer.enabled = visible;
                }
            }
        }
    }
    
    void ApplyDistantOptimization(LODGroup lodGroup)
    {
        // 매우 먼 오브젝트에 대한 추가 최적화
        var lods = lodGroup.GetLODs();
        
        if (lods.Length > 0)
        {
            // 가장 낮은 LOD만 활성화
            var lowestLOD = lods[lods.Length - 1];
            
            foreach (var renderer in lowestLOD.renderers)
            {
                if (renderer != null)
                {
                    // 그림자 완전 비활성화
                    renderer.shadowCastingMode = UnityEngine.Rendering.ShadowCastingMode.Off;
                    renderer.receiveShadows = false;
                    
                    // 라이트맵만 사용
                    renderer.lightProbeUsage = UnityEngine.Rendering.LightProbeUsage.Off;
                }
            }
        }
    }
    
    // 공개 API
    public void SetLODQualityLevel(float quality)
    {
        quality = Mathf.Clamp01(quality);
        
        for (int i = 0; i < lodSettings.distances.Length; i++)
        {
            lodSettings.distances[i] = originalDistances[i] * quality;
        }
        
        UpdateAllLODGroups();
    }
    
    public void EnableAggressiveMode(bool enable)
    {
        if (enable)
        {
            ApplyAggressiveLOD();
        }
        else
        {
            RestoreNormalLOD();
        }
    }
    
    public int GetVisibleLODCount()
    {
        int visibleCount = 0;
        
        foreach (var lodGroup in lodGroups)
        {
            if (IsLODGroupVisible(lodGroup))
            {
                visibleCount++;
            }
        }
        
        return visibleCount;
    }
    
    bool IsLODGroupVisible(LODGroup lodGroup)
    {
        var lods = lodGroup.GetLODs();
        foreach (var lod in lods)
        {
            foreach (var renderer in lod.renderers)
            {
                if (renderer != null && renderer.enabled)
                {
                    return true;
                }
            }
        }
        return false;
    }
}
```

효율적인 렌더링 최적화는 앱인토스 게임의 핵심 성능 요소예요.\
드로우콜 최소화, 적응적 LOD 시스템, 배치 렌더링을 통해 60FPS 목표를 달성하세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/analytics/logging.md'
description: 데이터 분석 로깅 가이드입니다. 이벤트 로그 전송 및 분석 방법을 확인하세요.
---

# 로그 (이벤트)

**로깅은 미니앱의 성과를 높이는 가장 중요한 도구예요.**\
사용자의 행동과 요소 노출을 기록하면, **이탈 지점을 파악하고, 전환율을 개선하며, 더 많은 트래픽을 유도**할 수 있어요.

👉 단순히 데이터를 쌓는 게 아니라, 로깅을 통해 **사용자가 어디에서 멈추는지**와 **무엇에 반응하는지**를 알 수 있어요.\
이를 기반으로 기능을 개선하고, 마케팅 전략에도 활용할 수 있답니다.

* **페이지 이동 로그**는 자동으로 기록되므로 추가 설정이 필요 없어요.
* 나머지 상호작용과 노출 로그는 직접 설정하면 더 정교한 분석이 가능해요.

트래픽을 높이고 싶다면 반드시 로깅을 적극적으로 활용하세요!

## 로깅을 잘 활용하는 방법

* **의미 있는 상호작용만 로깅하기**\
  → 버튼 클릭, 상품 조회, 구매 완료 등 실제 분석 가치가 있는 지점만 기록하세요.
* **추가 파라미터를 구체적으로 설정하기**\
  → 예: 단순히 “버튼 클릭”이 아니라 `button_name: "subscribe_button"`처럼 구체적으로 지정하면, 어떤 기능이 성과를 내는지 뚜렷하게 분석할 수 있어요.
* **전환율 최적화에 활용하기**\
  → 어떤 단계에서 이탈이 많은지 알면, UI 개선이나 프로모션을 타겟팅할 수 있어요.

::: tip 참고하세요
**SDK 0.0.26 버전 이상**이 적용된 미니앱만 데이터 확인이 가능해요.\
샌드박스나 출시 준비 단계의 데이터는 제공되지 않으며, 실제 런칭 이후 데이터만 확인할 수 있어요.\
**서비스 런칭 후 하루 뒤부터** 데이터를 볼 수 있어요.
:::

## 클릭 이벤트 로깅

사용자가 버튼을 클릭하는 등의 상호작용을 기록하는 방법이에요.

```javascript
import { Analytics } from "@apps-in-toss/web-framework";

// 'myButton' 버튼을 클릭하면 'my_button' 이벤트를 로깅해요.
document.getElementById("myButton").addEventListener("click", function () {
  Analytics.click({ button_name: "my_button" });
  // 클릭 후 실행할 추가 동작은 여기에 작성하세요.
});
```

* [`Analytics.click`](/bedrock/reference/framework/분석/Analytics) 메서드는 클릭 이벤트를 로깅해요.
* `button_name` 파라미터는 어떤 버튼인지 식별할 이름이에요. (예: 'my\_button')
* 클릭 데이터를 쌓으면, **어떤 버튼이 실제로 전환율을 높이는지 파악할 수 있어요.**

## 요소 노출 이벤트 로깅

화면에 특정 요소가 노출될 때 이벤트를 기록하면, **사용자가 어떤 상품이나 콘텐츠에 더 관심을 가지는지 파악할 수 있어요.**

```javascript
import { Analytics } from "@apps-in-toss/web-framework";

const target = document.getElementById("impressionItem");

const observer = new IntersectionObserver(
  ([entry]) => {
    if (entry.isIntersecting) {
      Analytics.impression({ item_id: target.dataset.itemId });
      observer.disconnect();
    }
  },
  { threshold: 0.1 }
);

observer.observe(target);
```

* `IntersectionObserver`는 요소가 화면에 10% 이상 노출될 때 콜백을 실행해요.
* [`Analytics.impression`](/bedrock/reference/framework/분석/LoggingImpression) 메서드는 노출 이벤트를 로깅해요.
* `item_id` 파라미터는 어떤 아이템이 노출됐는지 식별할 ID예요. (예: '1234')
* 노출 로그를 활용하면, **어떤 상품이 많이 보였는데도 클릭이나 구매로 이어지지 않았는지** 확인할 수 있어요.

### HTML 예시

```html
<div id="impressionItem" data-item-id="1234">노출을 감지할 요소</div>
```

## 콘솔 가이드

설정한 로깅 데이터는 콘솔의 **분석 > 이벤트** 메뉴에서 확인할 수 있어요.

![](/assets/logging_1.DQYeJuNA.png)

![](/assets/logging_2.Qxh0gsUs.png)

👉 이 화면에서 클릭률, 노출 대비 전환율, 주요 이탈 지점을 확인하고, 실제 서비스 개선에 바로 활용하세요.

✅ **로깅은 미니앱 성공을 좌우하는 필수 기능이에요.**\
파트너사에서 많이 활용할수록 **더 많은 트래픽과 전환율 개선 효과**를 누릴 수 있어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/start/loading.md'
---
# 로딩 최적화

앱인토스 Unity 게임에서 효율적인 로딩 시스템을 구현하여 사용자 경험을 향상시키고 메모리 사용량을 최적화하는 방법을 제공해요.

## 1. 로딩 시스템 개요

### 앱인토스 로딩 전략

```
🔄 앱인토스 로딩 시스템 구조
├── 초기 로딩 (Critical Loading)
│   ├── 게임 엔진 초기화
│   ├── 앱인토스 SDK 초기화
│   ├── 토스 인증 시스템
│   └── 첫 씬 필수 에셋
├── 백그라운드 로딩 (Background Loading)
│   ├── 다음 레벨 에셋
│   ├── 사운드 및 음악
│   └── 선택적 기능 에셋
└── 온디맨드 로딩 (On-Demand Loading)
    ├── 사용자 요청 시 로딩
    └── IAP 관련 에셋
```

### 로딩 성능 목표

* 초기 로딩: 5초 이내
* 씬 전환: 2초 이내
* 백그라운드 로딩: 게임플레이에 영향 없음
* 메모리 효율성: 언로드 에셋 관리

***

## 2. 통합 로딩 매니저

### 핵심 로딩 시스템

```c#
using UnityEngine;
using System.Collections;
using System.Collections.Generic;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class AppsInTossLoadingManager : MonoBehaviour
{
    public static AppsInTossLoadingManager Instance { get; private set; }
    
    [System.Serializable]
    public class LoadingGroup
    {
        public string groupName;
        public LoadingPriority priority;
        public List<string> addressableKeys = new List<string>();
        public List<UnityEngine.Object> resourceAssets = new List<UnityEngine.Object>();
        public bool unloadOnSceneChange = true;
        public float maxLoadTime = 10f;
    }
    
    public enum LoadingPriority
    {
        Critical,    // 즉시 로딩 (게임 시작 전 완료 필요)
        High,        // 우선 로딩 (첫 씬에서 필요)
        Medium,      // 백그라운드 로딩 (게임 중 로딩)
        Low          // 지연 로딩 (필요시 로딩)
    }
    
    [Header("로딩 그룹 설정")]
    public LoadingGroup[] loadingGroups;
    
    [Header("앱인토스 연동")]
    public bool enableTossIntegration = true;
    public bool showLoadingProgress = true;
    public GameObject loadingScreenPrefab;
    
    // 로딩 상태 추적
    private Dictionary<string, bool> groupLoadingStatus = new Dictionary<string, bool>();
    private Dictionary<string, List<object>> loadedAssets = new Dictionary<string, List<object>>();
    private AppsInTossLoadingScreen currentLoadingScreen;
    
    // 이벤트
    public System.Action<string, float> OnGroupProgressUpdated;
    public System.Action<string> OnGroupLoadingComplete;
    public System.Action OnAllCriticalLoadingComplete;
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeLoadingSystem();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeLoadingSystem()
    {
        Debug.Log("앱인토스 로딩 시스템 초기화");
        
        // 로딩 상태 초기화
        foreach (var group in loadingGroups)
        {
            groupLoadingStatus[group.groupName] = false;
            loadedAssets[group.groupName] = new List<object>();
        }
        
        // 로딩 화면 생성
        if (showLoadingProgress && loadingScreenPrefab != null)
        {
            var screenGO = Instantiate(loadingScreenPrefab);
            currentLoadingScreen = screenGO.GetComponent<AppsInTossLoadingScreen>();
        }
        
        // 자동 로딩 시작
        StartCoroutine(AutoLoadingSequence());
    }
    
    IEnumerator AutoLoadingSequence()
    {
        // 1. Critical 우선순위 그룹 로딩
        yield return StartCoroutine(LoadGroupsByPriority(LoadingPriority.Critical));
        OnAllCriticalLoadingComplete?.Invoke();
        
        // 2. High 우선순위 그룹 로딩
        yield return StartCoroutine(LoadGroupsByPriority(LoadingPriority.High));
        
        // 3. Medium, Low 우선순위는 백그라운드에서 로딩
        StartCoroutine(LoadGroupsByPriority(LoadingPriority.Medium));
        StartCoroutine(LoadGroupsByPriority(LoadingPriority.Low));
        
        // 로딩 화면 숨기기
        if (currentLoadingScreen != null)
        {
            currentLoadingScreen.HideLoadingScreen();
        }
    }
    
    IEnumerator LoadGroupsByPriority(LoadingPriority priority)
    {
        var targetGroups = System.Array.FindAll(loadingGroups, g => g.priority == priority);
        
        foreach (var group in targetGroups)
        {
            yield return StartCoroutine(LoadGroup(group));
        }
    }
    
    public IEnumerator LoadGroup(string groupName)
    {
        var group = System.Array.Find(loadingGroups, g => g.groupName == groupName);
        if (group != null)
        {
            yield return StartCoroutine(LoadGroup(group));
        }
    }
    
    IEnumerator LoadGroup(LoadingGroup group)
    {
        if (groupLoadingStatus.ContainsKey(group.groupName) && groupLoadingStatus[group.groupName])
        {
            yield break; // 이미 로딩된 그룹
        }
        
        Debug.Log($"로딩 그룹 시작: {group.groupName} (우선순위: {group.priority})");
        
        float startTime = Time.realtimeSinceStartup;
        int totalAssets = group.addressableKeys.Count + group.resourceAssets.Count;
        int loadedCount = 0;
        
        // Addressable 에셋 로딩
        foreach (var key in group.addressableKeys)
        {
            yield return StartCoroutine(LoadAddressableAsset(key, group.groupName));
            loadedCount++;
            
            // 진행률 업데이트
            float progress = (float)loadedCount / totalAssets;
            OnGroupProgressUpdated?.Invoke(group.groupName, progress);
            UpdateLoadingUI(group.groupName, progress);
            
            // 타임아웃 체크
            if (Time.realtimeSinceStartup - startTime > group.maxLoadTime)
            {
                Debug.LogWarning($"로딩 그룹 타임아웃: {group.groupName}");
                break;
            }
        }
        
        // Resources 에셋 로딩
        foreach (var asset in group.resourceAssets)
        {
            if (asset != null)
            {
                loadedAssets[group.groupName].Add(asset);
                loadedCount++;
                
                float progress = (float)loadedCount / totalAssets;
                OnGroupProgressUpdated?.Invoke(group.groupName, progress);
                UpdateLoadingUI(group.groupName, progress);
            }
            
            yield return null; // 프레임 분산
        }
        
        // 그룹 로딩 완료 처리
        groupLoadingStatus[group.groupName] = true;
        float loadTime = Time.realtimeSinceStartup - startTime;
        
        Debug.Log($"로딩 그룹 완료: {group.groupName} ({loadTime:F2}초, {loadedCount}/{totalAssets} 에셋)");
        OnGroupLoadingComplete?.Invoke(group.groupName);
        
        // 앱인토스 분석에 로딩 데이터 전송
        ReportLoadingMetrics(group.groupName, loadTime, loadedCount, totalAssets);
    }
    
    IEnumerator LoadAddressableAsset(string key, string groupName)
    {
        var handle = Addressables.LoadAssetAsync<UnityEngine.Object>(key);
        
        yield return handle;
        
        if (handle.Status == AsyncOperationStatus.Succeeded)
        {
            loadedAssets[groupName].Add(handle.Result);
            Debug.Log($"Addressable 에셋 로딩 성공: {key}");
        }
        else
        {
            Debug.LogError($"Addressable 에셋 로딩 실패: {key} - {handle.OperationException}");
        }
    }
    
    void UpdateLoadingUI(string groupName, float progress)
    {
        if (currentLoadingScreen != null)
        {
            currentLoadingScreen.UpdateGroupProgress(groupName, progress);
        }
        
        // 앱인토스 네이티브 로딩 UI 업데이트
        if (enableTossIntegration)
        {
            AppsInToss.UpdateLoadingProgress(progress, $"{groupName} 로딩 중...");
        }
    }
    
    void ReportLoadingMetrics(string groupName, float loadTime, int loadedCount, int totalAssets)
    {
        var metrics = new Dictionary<string, object>
        {
            {"group_name", groupName},
            {"load_time", loadTime},
            {"loaded_assets", loadedCount},
            {"total_assets", totalAssets},
            {"success_rate", (float)loadedCount / totalAssets},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("loading_performance", metrics);
    }
    
    // 공개 API
    public bool IsGroupLoaded(string groupName)
    {
        return groupLoadingStatus.ContainsKey(groupName) && groupLoadingStatus[groupName];
    }
    
    public void UnloadGroup(string groupName)
    {
        if (!loadedAssets.ContainsKey(groupName)) return;
        
        Debug.Log($"로딩 그룹 언로드: {groupName}");
        
        foreach (var asset in loadedAssets[groupName])
        {
            if (asset is AsyncOperationHandle)
            {
                Addressables.Release((AsyncOperationHandle)asset);
            }
        }
        
        loadedAssets[groupName].Clear();
        groupLoadingStatus[groupName] = false;
    }
    
    public void ForceLoadGroup(string groupName, System.Action<bool> onComplete = null)
    {
        StartCoroutine(ForceLoadGroupCoroutine(groupName, onComplete));
    }
    
    IEnumerator ForceLoadGroupCoroutine(string groupName, System.Action<bool> onComplete)
    {
        yield return StartCoroutine(LoadGroup(groupName));
        onComplete?.Invoke(IsGroupLoaded(groupName));
    }
}
```

***

## 3. 스마트 에셋 로더

### 동적 에셋 관리

```c#
public class SmartAssetLoader : MonoBehaviour
{
    [System.Serializable]
    public class AssetCategory
    {
        public string categoryName;
        public AssetType assetType;
        public List<string> assetAddresses;
        public int maxCacheSize = 10;
        public float cacheTimeout = 300f; // 5분
    }
    
    public enum AssetType
    {
        Texture,
        AudioClip,
        GameObject,
        Material,
        Animation,
        Font
    }
    
    [Header("에셋 카테고리")]
    public AssetCategory[] assetCategories;
    
    [Header("앱인토스 최적화 설정")]
    public bool enableMemoryOptimization = true;
    public long maxMemoryUsageMB = 150; // 앱인토스 권장 제한
    
    // 캐시 관리
    private Dictionary<string, CachedAsset> assetCache = new Dictionary<string, CachedAsset>();
    private Queue<string> recentlyUsedAssets = new Queue<string>();
    
    [System.Serializable]
    private class CachedAsset
    {
        public object asset;
        public float lastAccessTime;
        public int accessCount;
        public long memorySize;
        public AsyncOperationHandle handle;
    }
    
    void Start()
    {
        // 메모리 모니터링 시작
        if (enableMemoryOptimization)
        {
            InvokeRepeating(nameof(OptimizeMemoryUsage), 30f, 30f);
        }
    }
    
    // 에셋 로딩 API
    public void LoadAssetAsync<T>(string address, System.Action<T> onComplete, System.Action<string> onError = null) where T : UnityEngine.Object
    {
        StartCoroutine(LoadAssetCoroutine<T>(address, onComplete, onError));
    }
    
    IEnumerator LoadAssetCoroutine<T>(string address, System.Action<T> onComplete, System.Action<string> onError) where T : UnityEngine.Object
    {
        // 캐시 확인
        if (assetCache.ContainsKey(address))
        {
            var cached = assetCache[address];
            cached.lastAccessTime = Time.realtimeSinceStartup;
            cached.accessCount++;
            
            onComplete?.Invoke(cached.asset as T);
            yield break;
        }
        
        // 새로운 에셋 로딩
        var handle = Addressables.LoadAssetAsync<T>(address);
        yield return handle;
        
        if (handle.Status == AsyncOperationStatus.Succeeded)
        {
            // 캐시에 추가
            var cachedAsset = new CachedAsset
            {
                asset = handle.Result,
                lastAccessTime = Time.realtimeSinceStartup,
                accessCount = 1,
                memorySize = EstimateAssetMemorySize(handle.Result),
                handle = handle
            };
            
            assetCache[address] = cachedAsset;
            recentlyUsedAssets.Enqueue(address);
            
            // 메모리 체크
            CheckMemoryUsage();
            
            onComplete?.Invoke(handle.Result);
            
            Debug.Log($"에셋 로딩 완료: {address}");
        }
        else
        {
            string error = $"에셋 로딩 실패: {address} - {handle.OperationException}";
            Debug.LogError(error);
            onError?.Invoke(error);
        }
    }
    
    // 배치 로딩
    public void LoadAssetsAsync<T>(List<string> addresses, System.Action<List<T>> onComplete, System.Action<float> onProgress = null) where T : UnityEngine.Object
    {
        StartCoroutine(LoadAssetsBatchCoroutine<T>(addresses, onComplete, onProgress));
    }
    
    IEnumerator LoadAssetsBatchCoroutine<T>(List<string> addresses, System.Action<List<T>> onComplete, System.Action<float> onProgress) where T : UnityEngine.Object
    {
        var results = new List<T>();
        int loadedCount = 0;
        
        foreach (var address in addresses)
        {
            bool loadCompleted = false;
            T loadedAsset = null;
            
            LoadAssetAsync<T>(address, 
                (asset) => {
                    loadedAsset = asset;
                    loadCompleted = true;
                },
                (error) => {
                    loadCompleted = true;
                }
            );
            
            // 로딩 완료 대기
            yield return new WaitUntil(() => loadCompleted);
            
            if (loadedAsset != null)
            {
                results.Add(loadedAsset);
            }
            
            loadedCount++;
            float progress = (float)loadedCount / addresses.Count;
            onProgress?.Invoke(progress);
        }
        
        onComplete?.Invoke(results);
    }
    
    long EstimateAssetMemorySize(UnityEngine.Object asset)
    {
        // 에셋 타입별 메모리 크기 추정
        if (asset is Texture2D texture)
        {
            return texture.width * texture.height * 4; // RGBA32 기준
        }
        else if (asset is AudioClip audio)
        {
            return audio.samples * audio.channels * 2; // 16-bit PCM 기준
        }
        else if (asset is Mesh mesh)
        {
            return mesh.vertexCount * 32; // 추정값
        }
        else
        {
            return 1024 * 1024; // 1MB 기본값
        }
    }
    
    void CheckMemoryUsage()
    {
        if (!enableMemoryOptimization) return;
        
        long totalMemory = 0;
        foreach (var cached in assetCache.Values)
        {
            totalMemory += cached.memorySize;
        }
        
        long currentMemoryMB = totalMemory / (1024 * 1024);
        
        if (currentMemoryMB > maxMemoryUsageMB)
        {
            Debug.LogWarning($"에셋 캐시 메모리 사용량 초과: {currentMemoryMB}MB > {maxMemoryUsageMB}MB");
            OptimizeMemoryUsage();
        }
    }
    
    void OptimizeMemoryUsage()
    {
        var sortedAssets = new List<KeyValuePair<string, CachedAsset>>();
        
        foreach (var kvp in assetCache)
        {
            sortedAssets.Add(kvp);
        }
        
        // 접근 빈도와 최근 사용 시간을 고려하여 정렬
        sortedAssets.Sort((a, b) => {
            float scoreA = a.Value.accessCount / (Time.realtimeSinceStartup - a.Value.lastAccessTime + 1);
            float scoreB = b.Value.accessCount / (Time.realtimeSinceStartup - b.Value.lastAccessTime + 1);
            return scoreA.CompareTo(scoreB);
        });
        
        // 하위 30% 에셋 언로드
        int assetsToUnload = Mathf.CeilToInt(sortedAssets.Count * 0.3f);
        
        for (int i = 0; i < assetsToUnload && i < sortedAssets.Count; i++)
        {
            string address = sortedAssets[i].Key;
            UnloadAsset(address);
        }
        
        Debug.Log($"메모리 최적화 완료: {assetsToUnload}개 에셋 언로드");
    }
    
    public void UnloadAsset(string address)
    {
        if (assetCache.ContainsKey(address))
        {
            var cached = assetCache[address];
            if (cached.handle.IsValid())
            {
                Addressables.Release(cached.handle);
            }
            
            assetCache.Remove(address);
            Debug.Log($"에셋 언로드: {address}");
        }
    }
    
    public void PreloadCategory(string categoryName, System.Action<bool> onComplete = null)
    {
        var category = System.Array.Find(assetCategories, c => c.categoryName == categoryName);
        if (category != null)
        {
            StartCoroutine(PreloadCategoryCoroutine(category, onComplete));
        }
    }
    
    IEnumerator PreloadCategoryCoroutine(AssetCategory category, System.Action<bool> onComplete)
    {
        Debug.Log($"카테고리 사전 로딩 시작: {category.categoryName}");
        
        int loadedCount = 0;
        int totalAssets = category.assetAddresses.Count;
        
        foreach (var address in category.assetAddresses)
        {
            bool loadCompleted = false;
            
            LoadAssetAsync<UnityEngine.Object>(address,
                (asset) => {
                    loadedCount++;
                    loadCompleted = true;
                },
                (error) => {
                    loadCompleted = true;
                }
            );
            
            yield return new WaitUntil(() => loadCompleted);
        }
        
        bool success = loadedCount == totalAssets;
        Debug.Log($"카테고리 사전 로딩 완료: {category.categoryName} ({loadedCount}/{totalAssets})");
        
        onComplete?.Invoke(success);
    }
    
    // 통계 및 디버깅
    public void LogCacheStatistics()
    {
        Debug.Log($"=== 에셋 캐시 통계 ===");
        Debug.Log($"캐시된 에셋 수: {assetCache.Count}");
        
        long totalMemory = 0;
        foreach (var cached in assetCache.Values)
        {
            totalMemory += cached.memorySize;
        }
        
        Debug.Log($"총 캐시 메모리: {totalMemory / (1024 * 1024)}MB");
        Debug.Log($"메모리 제한: {maxMemoryUsageMB}MB");
    }
    
    void OnApplicationPause(bool pauseStatus)
    {
        if (pauseStatus)
        {
            // 앱이 백그라운드로 갈 때 메모리 최적화
            OptimizeMemoryUsage();
        }
    }
}
```

***

## 4. 씬별 로딩 관리

### 씬 전환 로딩 시스템

```c#
public class SceneLoadingManager : MonoBehaviour
{
    [System.Serializable]
    public class SceneLoadingConfig
    {
        public string sceneName;
        public List<string> requiredAssetGroups = new List<string>();
        public List<string> preloadAssetGroups = new List<string>();
        public bool showLoadingScreen = true;
        public float minLoadingTime = 1f; // 최소 로딩 시간 (UX)
    }
    
    [Header("씬별 로딩 설정")]
    public SceneLoadingConfig[] sceneConfigs;
    
    [Header("앱인토스 연동")]
    public GameObject sceneTransitionPrefab;
    public bool enableTossSceneAnalytics = true;
    
    private string currentScene;
    private float sceneLoadStartTime;
    
    void Start()
    {
        currentScene = UnityEngine.SceneManagement.SceneManager.GetActiveScene().name;
    }
    
    public void LoadSceneAsync(string sceneName, System.Action onComplete = null)
    {
        StartCoroutine(LoadSceneCoroutine(sceneName, onComplete));
    }
    
    IEnumerator LoadSceneCoroutine(string sceneName, System.Action onComplete)
    {
        sceneLoadStartTime = Time.realtimeSinceStartup;
        
        var config = System.Array.Find(sceneConfigs, c => c.sceneName == sceneName);
        if (config == null)
        {
            Debug.LogError($"씬 로딩 설정을 찾을 수 없습니다: {sceneName}");
            yield break;
        }
        
        // 로딩 화면 표시
        AppsInTossLoadingScreen loadingScreen = null;
        if (config.showLoadingScreen && sceneTransitionPrefab != null)
        {
            var screenGO = Instantiate(sceneTransitionPrefab);
            loadingScreen = screenGO.GetComponent<AppsInTossLoadingScreen>();
            loadingScreen.ShowSceneTransition(sceneName);
        }
        
        // 1. 필수 에셋 그룹 로딩
        foreach (var groupName in config.requiredAssetGroups)
        {
            if (!AppsInTossLoadingManager.Instance.IsGroupLoaded(groupName))
            {
                yield return AppsInTossLoadingManager.Instance.LoadGroup(groupName);
            }
        }
        
        // 2. 이전 씬 정리
        yield return StartCoroutine(CleanupCurrentScene());
        
        // 3. 새로운 씬 로딩
        var sceneLoadOp = UnityEngine.SceneManagement.SceneManager.LoadSceneAsync(sceneName);
        sceneLoadOp.allowSceneActivation = false;
        
        // 씬 로딩 진행률 모니터링
        while (sceneLoadOp.progress < 0.9f)
        {
            if (loadingScreen != null)
            {
                loadingScreen.UpdateProgress(sceneLoadOp.progress);
            }
            yield return null;
        }
        
        // 4. 사전 로딩 그룹 (백그라운드)
        foreach (var groupName in config.preloadAssetGroups)
        {
            AppsInTossLoadingManager.Instance.ForceLoadGroup(groupName);
        }
        
        // 최소 로딩 시간 대기 (UX 개선)
        float currentLoadTime = Time.realtimeSinceStartup - sceneLoadStartTime;
        if (currentLoadTime < config.minLoadingTime)
        {
            yield return new WaitForSeconds(config.minLoadingTime - currentLoadTime);
        }
        
        // 씬 활성화
        sceneLoadOp.allowSceneActivation = true;
        yield return sceneLoadOp;
        
        // 로딩 화면 숨기기
        if (loadingScreen != null)
        {
            loadingScreen.HideLoadingScreen();
        }
        
        // 씬 전환 완료 처리
        OnSceneLoadComplete(sceneName);
        onComplete?.Invoke();
    }
    
    IEnumerator CleanupCurrentScene()
    {
        Debug.Log($"이전 씬 정리 시작: {currentScene}");
        
        // 현재 씬의 언로드 대상 에셋 그룹 찾기
        var currentConfig = System.Array.Find(sceneConfigs, c => c.sceneName == currentScene);
        if (currentConfig != null)
        {
            // 씬별 전용 에셋 언로드
            foreach (var groupName in currentConfig.requiredAssetGroups)
            {
                var group = System.Array.Find(AppsInTossLoadingManager.Instance.loadingGroups, 
                    g => g.groupName == groupName);
                
                if (group != null && group.unloadOnSceneChange)
                {
                    AppsInTossLoadingManager.Instance.UnloadGroup(groupName);
                }
            }
        }
        
        // 메모리 정리
        System.GC.Collect();
        yield return Resources.UnloadUnusedAssets();
        
        Debug.Log("이전 씬 정리 완료");
    }
    
    void OnSceneLoadComplete(string sceneName)
    {
        float totalLoadTime = Time.realtimeSinceStartup - sceneLoadStartTime;
        
        Debug.Log($"씬 로딩 완료: {currentScene} → {sceneName} ({totalLoadTime:F2}초)");
        currentScene = sceneName;
        
        // 앱인토스 분석에 씬 전환 데이터 전송
        if (enableTossSceneAnalytics)
        {
            var sceneMetrics = new Dictionary<string, object>
            {
                {"from_scene", currentScene},
                {"to_scene", sceneName},
                {"load_time", totalLoadTime},
                {"timestamp", System.DateTime.UtcNow.ToString("o")}
            };
            
            AppsInToss.SendAnalytics("scene_transition", sceneMetrics);
        }
        
        // 성능 목표 체크 (2초 이내)
        if (totalLoadTime > 2f)
        {
            Debug.LogWarning($"씬 전환 시간이 목표를 초과: {totalLoadTime:F2}s > 2s");
            AppsInToss.ReportPerformanceIssue("scene_load_slow", totalLoadTime);
        }
    }
    
    // 빠른 씬 전환 (미리 로딩된 씬)
    public void QuickLoadScene(string sceneName)
    {
        var config = System.Array.Find(sceneConfigs, c => c.sceneName == sceneName);
        if (config == null) return;
        
        // 모든 필수 에셋이 로딩되었는지 확인
        bool allAssetsReady = true;
        foreach (var groupName in config.requiredAssetGroups)
        {
            if (!AppsInTossLoadingManager.Instance.IsGroupLoaded(groupName))
            {
                allAssetsReady = false;
                break;
            }
        }
        
        if (allAssetsReady)
        {
            // 즉시 씬 전환
            UnityEngine.SceneManagement.SceneManager.LoadScene(sceneName);
            OnSceneLoadComplete(sceneName);
        }
        else
        {
            // 일반 로딩 방식으로 폴백
            LoadSceneAsync(sceneName);
        }
    }
}
```

***

## 5. 프리로딩 시스템

### 인텔리전트 프리로딩

```c#
public class IntelligentPreloader : MonoBehaviour
{
    [System.Serializable]
    public class PreloadingRule
    {
        public string ruleName;
        public PreloadTrigger trigger;
        public List<string> targetAssetGroups;
        public float probability = 1.0f; // 프리로딩 확률 (0-1)
        public int maxConcurrentLoads = 2;
    }
    
    public enum PreloadTrigger
    {
        OnSceneStart,
        OnUserIdle,
        OnMenuOpen,
        OnGamePause,
        OnLowActivity,
        OnTossPayReady // 앱인토스 특화
    }
    
    [Header("프리로딩 규칙")]
    public PreloadingRule[] preloadingRules;
    
    [Header("사용자 행동 분석")]
    public bool enableUserBehaviorAnalysis = true;
    public float idleThreshold = 5f; // 유휴 상태 판정 시간
    
    private float lastUserActivity;
    private Dictionary<string, float> assetUsageFrequency = new Dictionary<string, float>();
    private Queue<string> recentScenes = new Queue<string>();
    
    void Start()
    {
        lastUserActivity = Time.realtimeSinceStartup;
        
        if (enableUserBehaviorAnalysis)
        {
            StartCoroutine(AnalyzeUserBehavior());
        }
        
        // 씬 시작 시 프리로딩 규칙 적용
        ExecutePreloadingRules(PreloadTrigger.OnSceneStart);
    }
    
    void Update()
    {
        // 사용자 활동 감지
        if (Input.anyKeyDown || Input.touchCount > 0)
        {
            lastUserActivity = Time.realtimeSinceStartup;
        }
    }
    
    IEnumerator AnalyzeUserBehavior()
    {
        while (true)
        {
            yield return new WaitForSeconds(1f);
            
            // 유휴 상태 감지
            float idleTime = Time.realtimeSinceStartup - lastUserActivity;
            if (idleTime > idleThreshold)
            {
                ExecutePreloadingRules(PreloadTrigger.OnUserIdle);
                yield return new WaitForSeconds(10f); // 중복 실행 방지
            }
        }
    }
    
    public void ExecutePreloadingRules(PreloadTrigger trigger)
    {
        var applicableRules = System.Array.FindAll(preloadingRules, r => r.trigger == trigger);
        
        foreach (var rule in applicableRules)
        {
            // 확률 기반 실행
            if (UnityEngine.Random.Range(0f, 1f) <= rule.probability)
            {
                StartCoroutine(ExecutePreloadingRule(rule));
            }
        }
    }
    
    IEnumerator ExecutePreloadingRule(PreloadingRule rule)
    {
        Debug.Log($"프리로딩 규칙 실행: {rule.ruleName}");
        
        var loadingTasks = new List<Coroutine>();
        
        foreach (var groupName in rule.targetAssetGroups)
        {
            // 동시 로딩 수 제한
            while (loadingTasks.Count >= rule.maxConcurrentLoads)
            {
                yield return null;
                
                // 완료된 작업 제거
                loadingTasks.RemoveAll(task => task == null);
            }
            
            // 이미 로딩된 그룹은 스킵
            if (AppsInTossLoadingManager.Instance.IsGroupLoaded(groupName))
            {
                continue;
            }
            
            // 사용 빈도 기반 우선순위 적용
            float frequency = assetUsageFrequency.ContainsKey(groupName) ? 
                assetUsageFrequency[groupName] : 0f;
            
            if (frequency > 0.3f || rule.trigger == PreloadTrigger.OnSceneStart) // 30% 이상 사용률 or 씬 시작
            {
                var loadTask = StartCoroutine(PreloadAssetGroup(groupName));
                loadingTasks.Add(loadTask);
            }
        }
        
        // 모든 프리로딩 작업 완료 대기
        foreach (var task in loadingTasks)
        {
            if (task != null)
            {
                yield return task;
            }
        }
        
        Debug.Log($"프리로딩 규칙 완료: {rule.ruleName}");
    }
    
    IEnumerator PreloadAssetGroup(string groupName)
    {
        yield return AppsInTossLoadingManager.Instance.LoadGroup(groupName);
        
        // 사용 빈도 업데이트
        if (assetUsageFrequency.ContainsKey(groupName))
        {
            assetUsageFrequency[groupName] += 0.1f;
        }
        else
        {
            assetUsageFrequency[groupName] = 0.1f;
        }
    }
    
    // 앱인토스 특화 프리로딩
    public void PreloadTossPayAssets()
    {
        ExecutePreloadingRules(PreloadTrigger.OnTossPayReady);
        
        // 토스페이 관련 에셋 사전 로딩
        var tossPayAssets = new List<string> { "TossPayUI", "PaymentIcons", "ReceiptTemplates" };
        
        foreach (var assetGroup in tossPayAssets)
        {
            if (AppsInTossLoadingManager.Instance.IsGroupLoaded(assetGroup))
            {
                continue;
            }
            
            AppsInTossLoadingManager.Instance.ForceLoadGroup(assetGroup, (success) => {
                if (success)
                {
                    Debug.Log($"토스페이 에셋 프리로딩 완료: {assetGroup}");
                }
            });
        }
    }
    
    // 씬 전환 패턴 학습
    public void OnSceneChanged(string newScene)
    {
        recentScenes.Enqueue(newScene);
        if (recentScenes.Count > 5)
        {
            recentScenes.Dequeue();
        }
        
        // 패턴 기반 예측 프리로딩
        PredictivePreload(newScene);
    }
    
    void PredictivePreload(string currentScene)
    {
        // 씬 전환 패턴 분석 후 다음 씬 예측 프리로딩
        var sceneHistory = recentScenes.ToArray();
        
        // 간단한 패턴 매칭 (실제로는 더 복잡한 ML 알고리즘 적용 가능)
        if (sceneHistory.Length >= 3)
        {
            string predictedNext = PredictNextScene(sceneHistory);
            if (!string.IsNullOrEmpty(predictedNext))
            {
                var sceneConfig = FindObjectOfType<SceneLoadingManager>()?.sceneConfigs
                    ?.FirstOrDefault(c => c.sceneName == predictedNext);
                
                if (sceneConfig != null)
                {
                    // 예측된 씬의 에셋 사전 로딩
                    foreach (var groupName in sceneConfig.requiredAssetGroups)
                    {
                        if (!AppsInTossLoadingManager.Instance.IsGroupLoaded(groupName))
                        {
                            StartCoroutine(PreloadAssetGroup(groupName));
                        }
                    }
                }
            }
        }
    }
    
    string PredictNextScene(string[] sceneHistory)
    {
        // 간단한 패턴 매칭 로직
        // 실제 구현에서는 머신러닝 또는 더 정교한 예측 알고리즘 사용
        return null; // 구현 필요
    }
}
```

***

## 6. 성능 모니터링 및 최적화

### 로딩 성능 분석 도구

```c#
public class LoadingPerformanceAnalyzer : MonoBehaviour
{
    [System.Serializable]
    public class LoadingMetrics
    {
        public string assetGroup;
        public float loadTime;
        public int assetCount;
        public long memoryUsage;
        public bool success;
        public string errorMessage;
        public System.DateTime timestamp;
    }
    
    private List<LoadingMetrics> performanceHistory = new List<LoadingMetrics>();
    private const int maxHistorySize = 100;
    
    void Start()
    {
        // 로딩 이벤트 구독
        if (AppsInTossLoadingManager.Instance != null)
        {
            AppsInTossLoadingManager.Instance.OnGroupLoadingComplete += OnGroupLoadingComplete;
        }
    }
    
    void OnGroupLoadingComplete(string groupName)
    {
        AnalyzeLoadingPerformance(groupName);
    }
    
    void AnalyzeLoadingPerformance(string groupName)
    {
        var metrics = new LoadingMetrics
        {
            assetGroup = groupName,
            loadTime = Time.realtimeSinceStartup,
            memoryUsage = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(false),
            success = AppsInTossLoadingManager.Instance.IsGroupLoaded(groupName),
            timestamp = System.DateTime.UtcNow
        };
        
        performanceHistory.Add(metrics);
        
        // 히스토리 크기 제한
        if (performanceHistory.Count > maxHistorySize)
        {
            performanceHistory.RemoveAt(0);
        }
        
        // 성능 이슈 감지
        DetectPerformanceIssues(metrics);
        
        // 앱인토스 분석 시스템에 전송
        SendLoadingAnalytics(metrics);
    }
    
    void DetectPerformanceIssues(LoadingMetrics metrics)
    {
        var issues = new List<string>();
        
        // 로딩 시간 체크
        if (metrics.loadTime > 10f)
        {
            issues.Add($"긴 로딩 시간: {metrics.loadTime:F2}초");
        }
        
        // 메모리 사용량 체크
        long memoryMB = metrics.memoryUsage / (1024 * 1024);
        if (memoryMB > 200)
        {
            issues.Add($"높은 메모리 사용량: {memoryMB}MB");
        }
        
        // 로딩 실패 체크
        if (!metrics.success)
        {
            issues.Add("로딩 실패");
        }
        
        if (issues.Count > 0)
        {
            Debug.LogWarning($"로딩 성능 이슈 감지 [{metrics.assetGroup}]: {string.Join(", ", issues)}");
            
            foreach (var issue in issues)
            {
                AppsInToss.ReportPerformanceIssue($"loading_{metrics.assetGroup}", issue);
            }
        }
    }
    
    void SendLoadingAnalytics(LoadingMetrics metrics)
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"asset_group", metrics.assetGroup},
            {"load_time", metrics.loadTime},
            {"memory_mb", metrics.memoryUsage / (1024f * 1024f)},
            {"success", metrics.success},
            {"device_model", SystemInfo.deviceModel},
            {"timestamp", metrics.timestamp.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("loading_performance", analyticsData);
    }
    
    // 성능 리포트 생성
    public string GeneratePerformanceReport()
    {
        if (performanceHistory.Count == 0)
        {
            return "성능 데이터가 없습니다.";
        }
        
        var report = new System.Text.StringBuilder();
        report.AppendLine("=== 로딩 성능 리포트 ===");
        report.AppendLine($"분석 기간: {performanceHistory.First().timestamp:yyyy-MM-dd HH:mm:ss} ~ {performanceHistory.Last().timestamp:yyyy-MM-dd HH:mm:ss}");
        report.AppendLine();
        
        // 전체 통계
        float avgLoadTime = performanceHistory.Average(m => m.loadTime);
        float maxLoadTime = performanceHistory.Max(m => m.loadTime);
        float avgMemoryMB = performanceHistory.Average(m => m.memoryUsage) / (1024f * 1024f);
        float successRate = performanceHistory.Count(m => m.success) / (float)performanceHistory.Count * 100f;
        
        report.AppendLine($"평균 로딩 시간: {avgLoadTime:F2}초");
        report.AppendLine($"최대 로딩 시간: {maxLoadTime:F2}초");
        report.AppendLine($"평균 메모리 사용량: {avgMemoryMB:F1}MB");
        report.AppendLine($"성공률: {successRate:F1}%");
        report.AppendLine();
        
        // 그룹별 통계
        var groupStats = performanceHistory
            .GroupBy(m => m.assetGroup)
            .Select(g => new {
                Group = g.Key,
                AvgTime = g.Average(m => m.loadTime),
                MaxTime = g.Max(m => m.loadTime),
                Count = g.Count(),
                SuccessRate = g.Count(m => m.success) / (float)g.Count() * 100f
            });
        
        report.AppendLine("=== 에셋 그룹별 성능 ===");
        foreach (var stat in groupStats.OrderByDescending(s => s.AvgTime))
        {
            report.AppendLine($"[{stat.Group}] 평균: {stat.AvgTime:F2}초, 최대: {stat.MaxTime:F2}초, 성공률: {stat.SuccessRate:F1}% ({stat.Count}회)");
        }
        
        return report.ToString();
    }
    
    // 최적화 제안 생성
    public List<string> GenerateOptimizationSuggestions()
    {
        var suggestions = new List<string>();
        
        if (performanceHistory.Count == 0) return suggestions;
        
        // 느린 로딩 그룹 식별
        var slowGroups = performanceHistory
            .GroupBy(m => m.assetGroup)
            .Where(g => g.Average(m => m.loadTime) > 5f)
            .Select(g => g.Key);
        
        foreach (var group in slowGroups)
        {
            suggestions.Add($"{group} 그룹의 로딩 시간 최적화 필요 (5초 초과)");
        }
        
        // 높은 메모리 사용량 그룹
        var memoryIntensiveGroups = performanceHistory
            .GroupBy(m => m.assetGroup)
            .Where(g => g.Average(m => m.memoryUsage) > 100 * 1024 * 1024) // 100MB
            .Select(g => g.Key);
        
        foreach (var group in memoryIntensiveGroups)
        {
            suggestions.Add($"{group} 그룹의 메모리 사용량 최적화 필요 (100MB 초과)");
        }
        
        // 실패율이 높은 그룹
        var unreliableGroups = performanceHistory
            .GroupBy(m => m.assetGroup)
            .Where(g => g.Count(m => !m.success) / (float)g.Count() > 0.1f) // 10% 이상 실패
            .Select(g => g.Key);
        
        foreach (var group in unreliableGroups)
        {
            suggestions.Add($"{group} 그룹의 로딩 안정성 개선 필요 (실패율 10% 이상)");
        }
        
        return suggestions;
    }
}
```

## 7. 체크리스트 및 권장사항

### 로딩 시스템 체크리스트

* 통합 로딩 매니저 구현
* 우선순위 기반 로딩 시스템 적용
* 스마트 에셋 캐싱 시스템 구현
* 씬별 로딩 관리 시스템 설정
* 인텔리전트 프리로딩 시스템 적용
* 메모리 사용량 모니터링 시스템
* 로딩 성능 분석 도구 설치
* 앱인토스 네이티브 연동 확인
* 다양한 기기에서 성능 테스트
* 사용자 행동 패턴 기반 최적화

### 앱인토스 특화 권장사항

1. 토스 브랜딩: 로딩 화면에 토스 디자인 시스템 적용
2. 메모리 제한: 150MB 이내 캐시 메모리 사용량 유지
3. 토스페이 연동: 결제 관련 에셋 사전 로딩
4. 사용자 분석: 앱인토스 분석 시스템과 연동
5. 성능 모니터링: 실시간 성능 데이터 수집 및 분석

효율적인 로딩 시스템은 사용자 경험의 핵심이에요. 우선순위 기반 로딩과 지능적인 캐싱으로 최적의 성능을 달성하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/언어/getLocale.md
---

# 로케일 가져오기

## `getLocale`

`getLocale` 함수는 사용자의 로케일(locale) 정보를 반환해요. 네이티브 모듈에서 로케일 정보를 가져올 수 없을 때는 기본값으로 'ko-KR'을 반환합니다. 앱의 현지화 및 언어 설정과 관련된 기능을 구현할 때 사용하세요.

## 시그니처

```typescript
function getLocale(): string;
```

### 반환 값

## 예제

### 현재 사용자의 로케일 정보 가져오기

```tsx
import { getLocale } from '@apps-in-toss/framework';
import { Text } from 'react-native';

function MyPage() {
 const locale = getLocale();

 return (
   <Text>사용자의 로케일 정보: {locale}</Text>
 )
}

```

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-locale](https://github.com/toss/apps-in-toss-examples/tree/main/with-locale) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/resource-loading.md
---
# 리소스 로딩 최적화

앱인토스 Unity 게임에서 리소스를 효율적으로 로딩하고 관리하여 메모리 사용량을 최소화하고 성능을 극대화하는 방법을 제공해요.

## 1. 리소스 로딩 전략

### 앱인토스 리소스 관리 원칙

```
📦 앱인토스 리소스 관리 전략
├── 초기 번들 (Critical Bundle) - 5MB 이내
│   ├── 게임 엔진 코어
│   ├── 앱인토스 SDK
│   ├── 첫 화면 UI
│   └── 필수 폰트/아이콘
├── 기능별 번들 (Feature Bundles) - 각 10MB 이내
│   ├── 게임플레이 에셋
│   ├── UI 시스템
│   ├── 오디오 에셋
│   └── 이펙트 시스템
├── 토스 연동 번들 (Toss Integration) - 3MB 이내
│   ├── 토스페이 UI
│   ├── 토스 로그인 리소스
│   └── 분석 시스템
└── 온디맨드 번들 (On-Demand) - 유연한 크기
    ├── 레벨별 에셋
    ├── 캐릭터 스킨
    └── 계절 이벤트 리소스
```

### 리소스 분류 시스템

```c#
using UnityEngine;
using UnityEngine.AddressableAssets;
using System.Collections.Generic;
using System.Linq;

[System.Serializable]
public class ResourceCategory
{
    public string categoryName;
    public ResourcePriority priority;
    public ResourceType resourceType;
    public List<string> assetLabels;
    public long maxCacheSizeMB = 50;
    public float cacheTimeoutMinutes = 30;
    public bool compressOnDownload = true;
    public bool enableStreaming = false;
}

public enum ResourcePriority
{
    Critical = 0,    // 즉시 필요한 리소스
    High = 1,        // 곧 사용될 리소스  
    Medium = 2,      // 백그라운드 로딩
    Low = 3,         // 필요시 로딩
    Toss = 4         // 앱인토스 특화 리소스
}

public enum ResourceType
{
    Texture,
    Audio,
    Model,
    Animation,
    UI,
    Script,
    Font,
    Shader,
    TossIntegration // 앱인토스 연동 전용
}

public class AppsInTossResourceManager : MonoBehaviour
{
    public static AppsInTossResourceManager Instance { get; private set; }
    
    [Header("리소스 카테고리")]
    public ResourceCategory[] categories;
    
    [Header("앱인토스 설정")]
    public long totalMemoryLimitMB = 200; // 앱인토스 메모리 제한
    public bool enableTossAnalytics = true;
    public bool optimizeForMobile = true;
    
    // 리소스 캐시 관리
    private Dictionary<string, CachedResource> resourceCache = new Dictionary<string, CachedResource>();
    private Dictionary<string, ResourceCategory> categoryMap = new Dictionary<string, ResourceCategory>();
    private Queue<string> loadingQueue = new Queue<string>();
    
    [System.Serializable]
    private class CachedResource
    {
        public object resource;
        public ResourceCategory category;
        public System.DateTime loadTime;
        public System.DateTime lastAccessTime;
        public int accessCount;
        public long memorySizeBytes;
        public UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle handle;
    }
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeResourceManager();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeResourceManager()
    {
        Debug.Log("앱인토스 리소스 매니저 초기화");
        
        // 카테고리 맵 생성
        foreach (var category in categories)
        {
            categoryMap[category.categoryName] = category;
        }
        
        // 메모리 모니터링 시작
        InvokeRepeating(nameof(MonitorMemoryUsage), 10f, 10f);
        
        // 앱인토스 특화 리소스 사전 로딩
        StartCoroutine(PreloadTossResources());
    }
    
    // 리소스 로딩 API
    public void LoadResourceAsync<T>(string address, System.Action<T> onComplete, 
        System.Action<string> onError = null) where T : UnityEngine.Object
    {
        StartCoroutine(LoadResourceCoroutine<T>(address, onComplete, onError));
    }
    
    System.Collections.IEnumerator LoadResourceCoroutine<T>(string address, 
        System.Action<T> onComplete, System.Action<string> onError) where T : UnityEngine.Object
    {
        // 캐시 확인
        if (resourceCache.ContainsKey(address))
        {
            var cached = resourceCache[address];
            cached.lastAccessTime = System.DateTime.UtcNow;
            cached.accessCount++;
            
            onComplete?.Invoke(cached.resource as T);
            yield break;
        }
        
        Debug.Log($"리소스 로딩 시작: {address}");
        float startTime = Time.realtimeSinceStartup;
        
        // Addressable 에셋 로딩
        var handle = Addressables.LoadAssetAsync<T>(address);
        yield return handle;
        
        if (handle.Status == UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationStatus.Succeeded)
        {
            // 캐시에 추가
            var category = DetermineResourceCategory(address, typeof(T));
            var cached = new CachedResource
            {
                resource = handle.Result,
                category = category,
                loadTime = System.DateTime.UtcNow,
                lastAccessTime = System.DateTime.UtcNow,
                accessCount = 1,
                memorySizeBytes = EstimateResourceSize(handle.Result),
                handle = handle
            };
            
            resourceCache[address] = cached;
            
            float loadTime = Time.realtimeSinceStartup - startTime;
            Debug.Log($"리소스 로딩 완료: {address} ({loadTime:F2}초)");
            
            // 앱인토스 분석에 로딩 데이터 전송
            if (enableTossAnalytics)
            {
                SendResourceLoadingAnalytics(address, loadTime, cached.memorySizeBytes, true);
            }
            
            onComplete?.Invoke(handle.Result);
        }
        else
        {
            string error = $"리소스 로딩 실패: {address} - {handle.OperationException}";
            Debug.LogError(error);
            
            if (enableTossAnalytics)
            {
                SendResourceLoadingAnalytics(address, -1, 0, false);
            }
            
            onError?.Invoke(error);
        }
    }
    
    ResourceCategory DetermineResourceCategory(string address, System.Type resourceType)
    {
        // 주소와 타입 기반으로 카테고리 결정
        if (address.Contains("Toss") || address.Contains("AIT"))
        {
            return categoryMap.ContainsKey("TossIntegration") ? 
                categoryMap["TossIntegration"] : categories.FirstOrDefault();
        }
        
        foreach (var category in categories)
        {
            foreach (var label in category.assetLabels)
            {
                if (address.Contains(label))
                {
                    return category;
                }
            }
        }
        
        return categories.FirstOrDefault(); // 기본 카테고리
    }
    
    long EstimateResourceSize(UnityEngine.Object resource)
    {
        if (resource is Texture2D texture)
        {
            return texture.width * texture.height * 4; // RGBA32 추정
        }
        else if (resource is AudioClip audio)
        {
            return audio.samples * audio.channels * 2; // 16-bit PCM 추정
        }
        else if (resource is Mesh mesh)
        {
            return mesh.vertexCount * 32; // 추정값
        }
        else if (resource is GameObject go)
        {
            // GameObject의 컴포넌트들을 기반으로 추정
            return EstimateGameObjectSize(go);
        }
        
        return 1024 * 1024; // 1MB 기본값
    }
    
    long EstimateGameObjectSize(GameObject go)
    {
        long totalSize = 0;
        
        // 메시 렌더러
        var meshRenderers = go.GetComponentsInChildren<MeshRenderer>();
        foreach (var mr in meshRenderers)
        {
            var meshFilter = mr.GetComponent<MeshFilter>();
            if (meshFilter != null && meshFilter.mesh != null)
            {
                totalSize += meshFilter.mesh.vertexCount * 32;
            }
        }
        
        // 텍스처
        var renderers = go.GetComponentsInChildren<Renderer>();
        foreach (var renderer in renderers)
        {
            foreach (var material in renderer.materials)
            {
                if (material.mainTexture is Texture2D tex)
                {
                    totalSize += tex.width * tex.height * 4;
                }
            }
        }
        
        return totalSize;
    }
    
    // 배치 로딩
    public void LoadResourcesBatch<T>(List<string> addresses, 
        System.Action<Dictionary<string, T>> onComplete,
        System.Action<float> onProgress = null) where T : UnityEngine.Object
    {
        StartCoroutine(LoadResourcesBatchCoroutine<T>(addresses, onComplete, onProgress));
    }
    
    System.Collections.IEnumerator LoadResourcesBatchCoroutine<T>(List<string> addresses,
        System.Action<Dictionary<string, T>> onComplete,
        System.Action<float> onProgress) where T : UnityEngine.Object
    {
        var results = new Dictionary<string, T>();
        int loadedCount = 0;
        
        foreach (var address in addresses)
        {
            bool loadCompleted = false;
            T loadedResource = null;
            
            LoadResourceAsync<T>(address,
                (resource) => {
                    loadedResource = resource;
                    loadCompleted = true;
                },
                (error) => {
                    loadCompleted = true;
                }
            );
            
            yield return new WaitUntil(() => loadCompleted);
            
            if (loadedResource != null)
            {
                results[address] = loadedResource;
            }
            
            loadedCount++;
            float progress = (float)loadedCount / addresses.Count;
            onProgress?.Invoke(progress);
        }
        
        onComplete?.Invoke(results);
    }
    
    void MonitorMemoryUsage()
    {
        long totalMemoryBytes = 0;
        var expiredResources = new List<string>();
        
        foreach (var kvp in resourceCache)
        {
            var cached = kvp.Value;
            totalMemoryBytes += cached.memorySizeBytes;
            
            // 만료된 리소스 확인
            var timeSinceLastAccess = System.DateTime.UtcNow - cached.lastAccessTime;
            if (timeSinceLastAccess.TotalMinutes > cached.category.cacheTimeoutMinutes)
            {
                expiredResources.Add(kvp.Key);
            }
        }
        
        long totalMemoryMB = totalMemoryBytes / (1024 * 1024);
        
        // 메모리 제한 체크
        if (totalMemoryMB > totalMemoryLimitMB)
        {
            Debug.LogWarning($"리소스 메모리 사용량 초과: {totalMemoryMB}MB > {totalMemoryLimitMB}MB");
            OptimizeMemoryUsage();
        }
        
        // 만료된 리소스 정리
        foreach (var address in expiredResources)
        {
            UnloadResource(address);
        }
        
        if (enableTossAnalytics && totalMemoryMB > 0)
        {
            SendMemoryUsageAnalytics(totalMemoryMB, resourceCache.Count);
        }
    }
    
    void OptimizeMemoryUsage()
    {
        Debug.Log("리소스 메모리 최적화 시작");
        
        // 우선순위와 사용 빈도 기반으로 정렬
        var sortedResources = resourceCache.ToList();
        sortedResources.Sort((a, b) => {
            var scoreA = CalculateResourceScore(a.Value);
            var scoreB = CalculateResourceScore(b.Value);
            return scoreA.CompareTo(scoreB);
        });
        
        // 하위 30% 리소스 언로드
        int resourcesToUnload = Mathf.CeilToInt(sortedResources.Count * 0.3f);
        
        for (int i = 0; i < resourcesToUnload && i < sortedResources.Count; i++)
        {
            var address = sortedResources[i].Key;
            var cached = sortedResources[i].Value;
            
            // Critical 우선순위는 보호
            if (cached.category.priority != ResourcePriority.Critical)
            {
                UnloadResource(address);
            }
        }
        
        Debug.Log($"메모리 최적화 완료: {resourcesToUnload}개 리소스 언로드");
    }
    
    float CalculateResourceScore(CachedResource cached)
    {
        // 점수가 낮을수록 언로드 우선순위 높음
        float score = 0f;
        
        // 우선순위 점수 (낮을수록 중요)
        score += (int)cached.category.priority * 10f;
        
        // 사용 빈도 점수
        score += cached.accessCount * 5f;
        
        // 최근 사용 시간 점수
        var timeSinceAccess = (System.DateTime.UtcNow - cached.lastAccessTime).TotalMinutes;
        score -= (float)timeSinceAccess * 0.1f;
        
        // 메모리 크기 페널티
        var sizeMB = cached.memorySizeBytes / (1024f * 1024f);
        score -= sizeMB * 2f;
        
        return score;
    }
    
    public void UnloadResource(string address)
    {
        if (resourceCache.ContainsKey(address))
        {
            var cached = resourceCache[address];
            
            // Addressables 핸들 해제
            if (cached.handle.IsValid())
            {
                Addressables.Release(cached.handle);
            }
            
            resourceCache.Remove(address);
            Debug.Log($"리소스 언로드: {address}");
        }
    }
    
    // 앱인토스 특화 기능
    System.Collections.IEnumerator PreloadTossResources()
    {
        Debug.Log("앱인토스 특화 리소스 사전 로딩 시작");
        
        var tossResources = new List<string>
        {
            "TossPayIcon",
            "TossLogo", 
            "TossButton",
            "TossNotification",
            "TossFont",
            "TossColorPalette"
        };
        
        foreach (var resource in tossResources)
        {
            LoadResourceAsync<UnityEngine.Object>(resource, 
                (loaded) => {
                    Debug.Log($"앱인토스 리소스 로딩 완료: {resource}");
                },
                (error) => {
                    Debug.LogWarning($"앱인토스 리소스 로딩 실패: {resource} - {error}");
                }
            );
            
            yield return new WaitForSeconds(0.1f); // 부하 분산
        }
        
        Debug.Log("앱인토스 특화 리소스 사전 로딩 완료");
    }
    
    public void PreloadTossPayResources(System.Action onComplete = null)
    {
        StartCoroutine(PreloadTossPayResourcesCoroutine(onComplete));
    }
    
    System.Collections.IEnumerator PreloadTossPayResourcesCoroutine(System.Action onComplete)
    {
        var tossPayResources = new List<string>
        {
            "TossPayUI",
            "PaymentMethods", 
            "ReceiptTemplate",
            "PaymentSuccessEffect",
            "PaymentFailureEffect"
        };
        
        yield return StartCoroutine(LoadResourcesBatchCoroutine<UnityEngine.Object>(
            tossPayResources,
            (results) => {
                Debug.Log($"토스페이 리소스 로딩 완료: {results.Count}/{tossPayResources.Count}");
                onComplete?.Invoke();
            }
        ));
    }
    
    void SendResourceLoadingAnalytics(string address, float loadTime, long memorySize, bool success)
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"resource_address", address},
            {"load_time", loadTime},
            {"memory_size_mb", memorySize / (1024f * 1024f)},
            {"success", success},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("resource_loading", analyticsData);
    }
    
    void SendMemoryUsageAnalytics(long memoryUsageMB, int cachedResourceCount)
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"memory_usage_mb", memoryUsageMB},
            {"cached_resources", cachedResourceCount},
            {"memory_limit_mb", totalMemoryLimitMB},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("memory_usage", analyticsData);
    }
    
    // 공개 API
    public bool IsResourceCached(string address)
    {
        return resourceCache.ContainsKey(address);
    }
    
    public void ClearCache(ResourcePriority maxPriority = ResourcePriority.Low)
    {
        var addressesToRemove = new List<string>();
        
        foreach (var kvp in resourceCache)
        {
            if (kvp.Value.category.priority >= maxPriority)
            {
                addressesToRemove.Add(kvp.Key);
            }
        }
        
        foreach (var address in addressesToRemove)
        {
            UnloadResource(address);
        }
        
        Debug.Log($"캐시 정리 완료: {addressesToRemove.Count}개 리소스 제거");
    }
    
    public ResourceLoadingReport GenerateLoadingReport()
    {
        var report = new ResourceLoadingReport();
        
        report.totalCachedResources = resourceCache.Count;
        report.totalMemoryUsageMB = resourceCache.Values.Sum(r => r.memorySizeBytes) / (1024f * 1024f);
        report.memoryLimitMB = totalMemoryLimitMB;
        
        // 카테고리별 통계
        report.categoryStats = categories.Select(category => {
            var categoryResources = resourceCache.Values.Where(r => r.category == category);
            return new ResourceCategoryStats
            {
                categoryName = category.categoryName,
                resourceCount = categoryResources.Count(),
                memoryUsageMB = categoryResources.Sum(r => r.memorySizeBytes) / (1024f * 1024f),
                averageAccessCount = categoryResources.Any() ? 
                    categoryResources.Average(r => r.accessCount) : 0f
            };
        }).ToList();
        
        return report;
    }
}

[System.Serializable]
public class ResourceLoadingReport
{
    public int totalCachedResources;
    public float totalMemoryUsageMB;
    public float memoryLimitMB;
    public List<ResourceCategoryStats> categoryStats;
}

[System.Serializable] 
public class ResourceCategoryStats
{
    public string categoryName;
    public int resourceCount;
    public float memoryUsageMB;
    public float averageAccessCount;
}
```

***

## 2. 텍스처 최적화

### 모바일 최적화 텍스처 관리

```c#
public class MobileTextureOptimizer : MonoBehaviour
{
    [System.Serializable]
    public class TextureQualitySettings
    {
        public string qualityLevel;
        public int maxTextureSize;
        public TextureFormat preferredFormat;
        public bool enableMipMaps;
        public FilterMode filterMode;
        public int compressionQuality;
    }
    
    [Header("기기별 텍스처 설정")]
    public TextureQualitySettings[] qualityTiers;
    
    [Header("앱인토스 최적화")]
    public bool enableDynamicQuality = true;
    public bool adaptToMemoryPressure = true;
    public long lowMemoryThresholdMB = 150;
    
    private TextureQualitySettings currentQuality;
    
    void Start()
    {
        DetermineOptimalQuality();
        
        if (adaptToMemoryPressure)
        {
            InvokeRepeating(nameof(CheckMemoryPressure), 30f, 30f);
        }
    }
    
    void DetermineOptimalQuality()
    {
        // 기기 성능에 따른 품질 결정
        int deviceTier = GetDevicePerformanceTier();
        
        if (deviceTier < qualityTiers.Length)
        {
            currentQuality = qualityTiers[deviceTier];
            ApplyTextureQuality(currentQuality);
        }
        
        Debug.Log($"텍스처 품질 설정: {currentQuality.qualityLevel}");
    }
    
    int GetDevicePerformanceTier()
    {
        // 메모리 크기 기반 기기 성능 분류
        int memoryGB = SystemInfo.systemMemorySize / 1024;
        
        if (memoryGB >= 8) return 0; // 고사양
        else if (memoryGB >= 4) return 1; // 중사양
        else if (memoryGB >= 2) return 2; // 저사양
        else return 3; // 초저사양
    }
    
    void ApplyTextureQuality(TextureQualitySettings quality)
    {
        QualitySettings.masterTextureLimit = GetTextureLimitFromSize(quality.maxTextureSize);
        QualitySettings.anisotropicFiltering = quality.filterMode == FilterMode.Trilinear ? 
            AnisotropicFiltering.Enable : AnisotropicFiltering.Disable;
        
        Debug.Log($"텍스처 품질 적용: 최대 크기 {quality.maxTextureSize}, 포맷 {quality.preferredFormat}");
    }
    
    int GetTextureLimitFromSize(int maxSize)
    {
        // Unity의 masterTextureLimit은 반대 방향 (0=원본, 1=1/2, 2=1/4)
        if (maxSize >= 2048) return 0;
        else if (maxSize >= 1024) return 1;
        else if (maxSize >= 512) return 2;
        else return 3;
    }
    
    void CheckMemoryPressure()
    {
        long currentMemoryMB = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(false) / (1024 * 1024);
        
        if (currentMemoryMB > lowMemoryThresholdMB && enableDynamicQuality)
        {
            // 메모리 압박 시 텍스처 품질 하향 조정
            ReduceTextureQuality();
        }
    }
    
    void ReduceTextureQuality()
    {
        int currentTier = System.Array.IndexOf(qualityTiers, currentQuality);
        if (currentTier < qualityTiers.Length - 1)
        {
            currentQuality = qualityTiers[currentTier + 1];
            ApplyTextureQuality(currentQuality);
            
            Debug.LogWarning($"메모리 압박으로 텍스처 품질 하향: {currentQuality.qualityLevel}");
            
            // 앱인토스에 성능 이슈 리포트
            AppsInToss.ReportPerformanceIssue("texture_quality_reduced", currentQuality.qualityLevel);
        }
    }
    
    // 런타임 텍스처 압축
    public void CompressTexture(Texture2D texture, bool highQuality = false)
    {
        if (texture == null || !texture.isReadable) return;
        
        TextureFormat targetFormat = currentQuality.preferredFormat;
        
        // 앱인토스 환경에 최적화된 포맷 선택
        if (SystemInfo.SupportsTextureFormat(TextureFormat.ASTC_6x6))
        {
            targetFormat = highQuality ? TextureFormat.ASTC_4x4 : TextureFormat.ASTC_6x6;
        }
        else if (SystemInfo.SupportsTextureFormat(TextureFormat.ETC2_RGBA8))
        {
            targetFormat = TextureFormat.ETC2_RGBA8;
        }
        
        // 텍스처 압축 적용
        texture.Compress(highQuality);
        Debug.Log($"텍스처 압축 완료: {texture.name} -> {targetFormat}");
    }
}
```

***

## 3. 오디오 리소스 최적화

### 효율적인 오디오 관리

```c#
public class AudioResourceManager : MonoBehaviour
{
    [System.Serializable]
    public class AudioClipData
    {
        public string clipName;
        public AudioType audioType;
        public AudioClipLoadType loadType;
        public bool compress;
        public float quality = 0.5f;
        public bool loop;
    }
    
    public enum AudioType
    {
        Music,
        SFX,
        Voice,
        UI,
        TossNotification // 앱인토스 특화
    }
    
    [Header("오디오 클립 설정")]
    public AudioClipData[] audioClips;
    
    [Header("앱인토스 오디오 설정")]
    public bool enableTossAudio = true;
    public bool optimizeForMobile = true;
    public int maxConcurrentAudioSources = 8;
    
    private Dictionary<string, AudioClip> loadedClips = new Dictionary<string, AudioClip>();
    private Dictionary<AudioType, float> typeVolumeSettings = new Dictionary<AudioType, float>();
    private Queue<AudioSource> audioSourcePool = new Queue<AudioSource>();
    
    void Start()
    {
        InitializeAudioSettings();
        CreateAudioSourcePool();
        
        if (enableTossAudio)
        {
            LoadTossAudioResources();
        }
    }
    
    void InitializeAudioSettings()
    {
        // 오디오 타입별 기본 볼륨 설정
        typeVolumeSettings[AudioType.Music] = 0.7f;
        typeVolumeSettings[AudioType.SFX] = 0.8f;
        typeVolumeSettings[AudioType.Voice] = 1.0f;
        typeVolumeSettings[AudioType.UI] = 0.6f;
        typeVolumeSettings[AudioType.TossNotification] = 0.9f; // 토스 알림음
        
        // 모바일 최적화 설정
        if (optimizeForMobile)
        {
            AudioSettings.GetConfiguration(out var config);
            config.numVirtualVoices = 256;
            config.numRealVoices = 32;
            AudioSettings.Reset(config);
        }
    }
    
    void CreateAudioSourcePool()
    {
        for (int i = 0; i < maxConcurrentAudioSources; i++)
        {
            var audioSourceGO = new GameObject($"AudioSource_{i}");
            audioSourceGO.transform.parent = transform;
            var audioSource = audioSourceGO.AddComponent<AudioSource>();
            audioSourcePool.Enqueue(audioSource);
        }
    }
    
    void LoadTossAudioResources()
    {
        var tossAudioResources = new List<string>
        {
            "TossPaySuccess",
            "TossPayFailure", 
            "TossNotification",
            "TossButtonClick",
            "TossSwipe"
        };
        
        foreach (var resource in tossAudioResources)
        {
            AppsInTossResourceManager.Instance.LoadResourceAsync<AudioClip>(resource,
                (clip) => {
                    loadedClips[resource] = clip;
                    Debug.Log($"앱인토스 오디오 리소스 로딩 완료: {resource}");
                },
                (error) => {
                    Debug.LogWarning($"앱인토스 오디오 리소스 로딩 실패: {resource}");
                }
            );
        }
    }
    
    public void PlayAudio(string clipName, AudioType audioType, float volume = -1f)
    {
        if (!loadedClips.ContainsKey(clipName))
        {
            // 동적 로딩
            AppsInTossResourceManager.Instance.LoadResourceAsync<AudioClip>(clipName,
                (clip) => {
                    loadedClips[clipName] = clip;
                    PlayLoadedAudio(clipName, audioType, volume);
                }
            );
            return;
        }
        
        PlayLoadedAudio(clipName, audioType, volume);
    }
    
    void PlayLoadedAudio(string clipName, AudioType audioType, float volume)
    {
        if (!loadedClips.ContainsKey(clipName)) return;
        
        var audioSource = GetAudioSource();
        if (audioSource == null)
        {
            Debug.LogWarning("사용 가능한 AudioSource가 없습니다");
            return;
        }
        
        audioSource.clip = loadedClips[clipName];
        audioSource.volume = volume >= 0 ? volume : typeVolumeSettings[audioType];
        audioSource.loop = GetAudioClipData(clipName)?.loop ?? false;
        
        audioSource.Play();
        
        // 재생 완료 후 AudioSource 반환
        StartCoroutine(ReturnAudioSourceAfterPlay(audioSource));
    }
    
    AudioSource GetAudioSource()
    {
        if (audioSourcePool.Count > 0)
        {
            return audioSourcePool.Dequeue();
        }
        
        // 풀이 비어있으면 새로 생성
        var audioSourceGO = new GameObject($"AudioSource_Dynamic");
        audioSourceGO.transform.parent = transform;
        return audioSourceGO.AddComponent<AudioSource>();
    }
    
    System.Collections.IEnumerator ReturnAudioSourceAfterPlay(AudioSource audioSource)
    {
        yield return new WaitUntil(() => !audioSource.isPlaying);
        
        audioSource.clip = null;
        audioSourcePool.Enqueue(audioSource);
    }
    
    AudioClipData GetAudioClipData(string clipName)
    {
        return System.Array.Find(audioClips, clip => clip.clipName == clipName);
    }
    
    // 앱인토스 특화 오디오 기능
    public void PlayTossNotification()
    {
        PlayAudio("TossNotification", AudioType.TossNotification);
        
        // 진동과 함께 재생 (앱인토스 네이티브 기능)
        AppsInToss.TriggerHapticFeedback(AppsInToss.HapticType.Notification);
    }
    
    public void PlayTossPaySound(bool success)
    {
        string clipName = success ? "TossPaySuccess" : "TossPayFailure";
        PlayAudio(clipName, AudioType.TossNotification);
        
        // 결제 결과에 따른 햅틱 피드백
        var hapticType = success ? AppsInToss.HapticType.Success : AppsInToss.HapticType.Error;
        AppsInToss.TriggerHapticFeedback(hapticType);
    }
    
    public void SetVolumeForType(AudioType audioType, float volume)
    {
        typeVolumeSettings[audioType] = Mathf.Clamp01(volume);
        
        // 현재 재생 중인 해당 타입의 오디오 볼륨 조정
        foreach (var audioSource in FindObjectsOfType<AudioSource>())
        {
            if (audioSource.clip != null)
            {
                var clipData = GetAudioClipData(audioSource.clip.name);
                if (clipData != null && clipData.audioType == audioType)
                {
                    audioSource.volume = volume;
                }
            }
        }
    }
    
    public void StopAllAudio(AudioType? specificType = null)
    {
        foreach (var audioSource in FindObjectsOfType<AudioSource>())
        {
            if (specificType.HasValue)
            {
                var clipData = GetAudioClipData(audioSource.clip?.name);
                if (clipData?.audioType == specificType.Value)
                {
                    audioSource.Stop();
                }
            }
            else
            {
                audioSource.Stop();
            }
        }
    }
    
    // 메모리 최적화
    public void UnloadUnusedAudioClips()
    {
        var clipsToRemove = new List<string>();
        
        foreach (var kvp in loadedClips)
        {
            bool isPlaying = false;
            
            foreach (var audioSource in FindObjectsOfType<AudioSource>())
            {
                if (audioSource.clip == kvp.Value && audioSource.isPlaying)
                {
                    isPlaying = true;
                    break;
                }
            }
            
            if (!isPlaying)
            {
                clipsToRemove.Add(kvp.Key);
            }
        }
        
        foreach (var clipName in clipsToRemove)
        {
            loadedClips.Remove(clipName);
        }
        
        Resources.UnloadUnusedAssets();
        Debug.Log($"사용하지 않는 오디오 클립 언로드: {clipsToRemove.Count}개");
    }
}
```

## 4. 체크리스트 및 권장사항

### 리소스 로딩 최적화 체크리스트

* 리소스 카테고리 시스템 구현
* 우선순위 기반 로딩 시스템 적용
* 메모리 사용량 모니터링 시스템
* 텍스처 최적화 시스템 적용
* 오디오 리소스 관리 시스템
* 동적 품질 조정 시스템
* 캐시 관리 및 정리 시스템
* 앱인토스 특화 리소스 사전 로딩
* 성능 분석 및 리포팅 시스템
* 메모리 압박 상황 대응 시스템

### 앱인토스 특화 권장사항

* 메모리 제한 준수: 총 200MB 이내 메모리 사용
* 토스 브랜딩 에셋: 토스 디자인 시스템 리소스 우선 로딩
* 토스페이 연동: 결제 관련 리소스 사전 준비
* 모바일 최적화: 기기 성능에 따른 동적 품질 조정
* 분석 연동: 리소스 사용량 데이터 앱인토스 분석 시스템 전송

효율적인 리소스 관리는 성능과 사용자 경험의 핵심이에요. 앱인토스 환경에 최적화된 리소스 전략을 수립하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/IOFlatList.md
---

# 리스트 항목 노출 감지하기

## `IOFlatList`

`IOFlatList`는 스크롤 중 특정 요소가 화면에 보이거나 사라지는지를 감지하기 위해 Intersection Observer 기능을 추가한 `FlatList` 컴포넌트예요. 이 컴포넌트를 사용하면 리스트의 각 항목이 화면에 나타나는지 여부를 쉽게 확인하고 처리할 수 있어요.

`InView`와 함께 사용하면 각 요소의 노출 상태를 확인할 수 있어요. 자식 요소로 포함된 [InView](/bedrock/reference/framework/화면%20제어/InView) 컴포넌트는 `IOFlatList`의 관찰 기능을 통해 요소가 화면에 보이는지 여부를 감지하고, 노출 상태에 따라 이벤트를 발생시켜요.

## 시그니처

```typescript
IOFlatList: typeof IOFlatListFunction;
```

## 예제

`IOFlatList`를 사용해 리스트의 각 항목이 화면에 나타나는지 여부를 확인할 수 있어요.
리스트의 각 항목이 화면에 나타나면 `InView` 컴포넌트가 `visible` 상태로 변경되어요.

```tsx
import { ReactNode, useState } from "react";
import { StyleSheet, Text, View } from "react-native";
import { InView, IOFlatList } from '@granite-js/react-native';

const mockData = Array.from({ length: 30 }, (_, i) => ({ key: String(i) }));

function FlatListPage() {
  return (
    <IOFlatList
      data={mockData}
      renderItem={({ item }) => <InViewItem>{item.key}</InViewItem>}
    />
  );
}

function InViewItem({ children }: { children: ReactNode }) {
  const [visible, setVisible] = useState(false);

  return (
    <InView onChange={setVisible}>
      <View style={styles.item}>
        <Text>{children}</Text>
        <Text>{visible ? "visible" : ""}</Text>
      </View>
    </InView>
  );
}

const styles = StyleSheet.create({
  item: {
    padding: 16,
    borderBottomWidth: 1,
    borderBottomColor: "#ddd",
  },
});
```

---

---
url: 'https://developers-apps-in-toss.toss.im/release-note.md'
description: '앱인토스 제품, API, SDK의 새로운 기능과 변경 사항을 확인하세요. 주요 업데이트와 릴리즈 노트를 한눈에 볼 수 있습니다.'
---

# 릴리즈 노트

앱인토스 제품 및 API·SDK의 새로운 기능과 변경 사항을 알려드려요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/공유/share.md
---

# 메시지 공유하기

## `share`

`share` 함수로 사용자가 콘텐츠를 쉽게 공유할 수 있도록, 네이티브 공유 시트를 표시할 수 있어요.\
예를 들어, 초대 메시지나 텍스트 정보를 사용자가 설치된 앱 목록에서 원하는 앱(예: 메신저, 메모 앱)을 선택해서 메시지를 공유할 수 있어요. 각 플랫폼(Android, iOS)에서 기본으로 제공하는 공유 인터페이스를 활용해요.

`options.message` 속성에 공유할 메시지를 전달하면, 사용자가 선택할 수 있는 앱 목록이 표시돼요.
예를 들어, 사용자가 텍스트 메시지를 공유하거나 메모 앱에 저장하려고 할 때 유용해요.

## 시그니처

```typescript
function share(message: {
    message: string;
}): Promise<void>;
```

### 파라미터

## 예제

### 공유하기 기능 구현하기

아래는 버튼을 클릭하면 메시지를 공유하는 간단한 예제예요.

::: code-group

```js [js]
import { share } from "@apps-in-toss/web-framework";

async function handleShare() {
  try {
    await share({ message: "공유할 메시지" });
    console.log("공유 완료");
  } catch (error) {
    console.error("공유 실패:", error);
  }
}
```

```tsx [React]
import { share } from "@apps-in-toss/web-framework";

const ShareButton = () => {
  const handleShare = async () => {
    try {
      await share({ message: "공유할 메시지" });
      console.log("공유 완료");
    } catch (error) {
      console.error("공유 실패:", error);
    }
  };

  return <button onClick={handleShare}>공유하기</button>;
};
```

```tsx [React Native]
import { share } from '@apps-in-toss/framework';
import { Button } from 'react-native';

function MyPage() {
  return (
    <Button
      title="공유"
      onPress={() => share({ message: '공유할 메시지입니다.' })}
    />
  );
}
```

:::

### 사용자 입력을 받아 메시지 공유하기

```tsx
import { useState } from "react";
import { TextInput, Button, View, Alert } from "react-native";
import { share } from '@apps-in-toss/framework';

function ShareWithInput() {
  const [invitationMessage, setInvitationMessage] = useState(""); // [!code highlight]

  const handleShare = () => {
    if (!invitationMessage.trim()) {
      Alert.alert("공유할 메시지를 입력하세요.");
      return;
    }
    share({ message: invitationMessage }); // [!code highlight]
  };

  return (
    <View style={{ padding: 20 }}>
      <TextInput
        style={{
          height: 40,
          borderColor: "gray",
          borderWidth: 1,
          marginBottom: 10,
          paddingHorizontal: 8,
        }}
        placeholder="초대 메시지를 입력하세요"
        value={invitationMessage}
        onChangeText={setInvitationMessage}
      />
      <Button title="초대 메시지 공유" onPress={handleShare} />
    </View>
  );
}
```

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-share-text](https://github.com/toss/apps-in-toss-examples/tree/main/with-share-text) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/저장소/clearItems.md
---

# 모든 항목 삭제

## `clearItems`

`clearItems` 함수는 모바일 앱의 로컬 저장소의 모든 아이템을 삭제해요.

## 시그니처

```typescript
declare function clearItems(): Promise<void>;
```

### 반환 값

## 예제

### 저장소 초기화하기

::: code-group

```js [js]
import { Storage } from '@apps-in-toss/web-framework';

async function handleClearStorageItems() {
  await Storage.clearItems();
  console.log('Storage cleared');
}
```

```tsx [React]
import { Storage } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function StorageClearButton() {
  async function handleClick() {
    await Storage.clearItems();
    console.log('Storage cleared');
  }

  return <Button onClick={handleClick}>저장소 초기화</Button>;
}
```

```tsx [React Native]
import { Storage } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function StorageClearButton() {
  async function handlePress() {
    await Storage.clearItems();
    console.log('Storage cleared');
  }

  return <Button onPress={handlePress}>저장소 초기화</Button>;
}
```

:::

---

---
url: 'https://developers-apps-in-toss.toss.im/design/miniapp-branding-guide.md'
description: '앱인토스 미니앱 브랜딩 가이드입니다. 브랜드 로고, 이름, 컬러, 내비게이션 바, 브릿지, 탭바 등 브랜드 요소 적용 가이드를 확인하세요.'
---

# {{ $frontmatter.title }}

앱인토스 서비스가 토스와 구분되는 브랜드 경험을 전달할 수 있도록 마련한 요소들을 소개해요.\
사용자가 토스와 앱인토스를 혼동하지 않도록 하는 데 중요한 기준으로, 꼭 가이드를 읽고 지켜주세요.

***

## 1. 브랜드 로고 / 이름 /  컬러

브랜드 로고, 브랜드 이름, 브랜드 컬러를 토스와 앱인토스 내에 노출시켜 브랜드를 인지하게 해줘요.

### 브랜드 로고

파트너사의 로고는 전체탭, 혜택탭, 푸시, 알림, 네비게이션, 브릿지에 보여져요.\
아래 첨부한 이미지 또는 일러스트 파일을 반드시 활용해 로고를 제작해주세요.

AppsInToss\_Logo\_Guide\_600\_600.pdf

App\_in\_Toss\_Logo\_Guide\_600\_600.ai

![](/assets/brand-logo.Bucgr8f3.png)

* 600\*600px의 각진 정방형으로 작업하며, 모서리가 둥근 형태는 불가능해요.
* 로고 뒤에는 반드시 배경을 두고, 라이트/다크 모드에서 모두 잘 보이는 배경 색상을 사용해주세요.
* 애니팡처럼 로고 자체에 배경이 이미 포함된 경우 이미지를 600\*600px에 꽉 차게 배치해주세요.
* 앱인토스 콘솔에 로고 파일을 업로드하고, `granite.config.mts` 파일 상단에 있는 `appsInToss` 함수의 `brand.icon` 속성에 동일한 로고 링크를 업로드해 주세요.

### 브랜드 이름

브랜드 이름은 전체탭, 혜택탭, 푸시, 알림, 네비게이션, 브릿지에 보여져요.\
특수한 이유가 없다면 한글로 작성해주세요. (e.g. 토스(O) / Toss(X))\
앱인토스 콘솔에 브랜드 이름을 입력하고, `granite.config.mts` 파일 상단에 있는 `appsInToss` 함수의 `brand.displayName` 속성에 동일한 브랜드 이름을 입력해주세요.

### 브랜드 컬러

브랜드 컬러는 토스 내 진입점, 브릿지, 버튼(TDS 사용 시) 등에 보여져요.

* 브랜드 컬러가 있다면 그대로 사용해주세요.
* 브랜드 컬러가 없다면 로고에서 가장 많이 쓰인 색상을 사용해주세요.
  * 선택이 어렵다면 [컬러 추출 사이트](https://lokeshdhakar.com/projects/color-thief/)에서 로고 이미지를 넣어 도출된 컬러를 입력해주세요.
* 브랜드 컬러가 색 대비 기준을 충족하지 못할 경우 기존 색상을 최대한 유지하면서 자동 보정돼요.
* `granite.config.mts` 파일 상단에 있는 `appsInToss` 함수의 `brand.primaryColor` 속성에 #을 반드시 포함해서 헥스코드 여섯자리를 입력해주세요. e.g. #3182F6

## 2. 내비게이션 바

화면 상단에 고정되는 네비게이션 영역으로, 앱인토스 전용 컴포넌트가 제공돼요.\
입점하는 서비스의 종류에 맞게 아래 가이드를 확인하고 네비게이션 바를 설정해주세요.

* [게임 가이드](/checklist/app-game.md#_5-내비게이션-바)
* [비게임 가이드](/checklist/app-nongame.md#_4-내비게이션-바)

## 3. 브릿지

토스에서 앱인토스로 진입할 때 앱인토스로 이동했음을 알려주는 징검다리 역할의 컴포넌트예요.\
입점하는 서비스의 종류에 맞게 아래 가이드를 확인하고 브릿지를 설정해주세요.

* [게임 가이드](/checklist/app-game.md#_1-접속-브릿지-뷰)
* [비게임 가이드](/checklist/app-nongame.md#_1-접속-브릿지-뷰)

## 4. 탭바

탭바는 필수 컴포넌트는 아니지만, 필요하다면 반드시 토스에서 제공하는 플로팅 형태의 탭바를 사용해 직접 구현해주세요. (자체 UI를 사용하시는 경우에도 탭바는 제공된 형태에 맞추어 구현해주세요.)\
토스 메인 화면의 기본 하단 탭의 형태와 겹치면 사용자가 어디에 있는지 헷갈릴 수 있기 때문이에요.\
탭바의 탭 개수는 최소 2개에서 최대 5개까지 사용할 수 있어요.

![Tabbar](/assets/tabbar.DkiOfRQM.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/development/deploy.md'
description: '앱인토스 미니앱 출시 프로세스를 안내합니다. 검토 요청, 출시하기, 버전 관리, 롤백, 긴급 수정 등 출시 후 관리 방법을 확인하세요.'
---

# 미니앱 출시

토스앱에서 최종 테스트를 마쳤다면,\
앱인토스 콘솔에서 **검토를 요청**하고 **미니앱을 출시**할 수 있어요.

![이미지](/assets/release-flow.BUfX8Fba.png)

## 1. 사전 점검하기

### ① 검수 가이드 확인하기

출시 전 반드시 **검수 가이드 및 체크리스트**를 확인하세요.\
[게임](/checklist/app-game.md)/[비게임](/checklist/app-nongame.md) 출시 가이드를 모두 확인하여 개발이 완료되었는지 점검해 주세요.\
가이드를 준수하지 않으면 **검토 단계에서 반려될 수 있어요.**

### ② 앱 번들 업로드 시 주의사항

**용량 정책**

* 앱 번들은 압축 해제 기준 **100MB 이하**만 업로드할 수 있어요.
* 이미지, 사운드, 영상 등 모든 리소스를 포함하면 용량을 초과할 수 있어요.
* 리소스 파일은 **빌드와 분리**하여 관리해 주세요.

**권장 사항**

* 앱 실행에 필요한 **최소한의 리소스만 번들에 포함**하세요.
* 대용량 리소스는 **외부 스토리지 또는 CDN 다운로드** 방식으로 구성하는 것을 권장해요.
* 추가 리소스는 **단계적 다운로드(Lazy Loading)** 방식을 적용하면 사용자 경험이 더 좋아져요.

## 2. 검토 요청하기

테스트를 마친 뒤 콘솔의 **'검토 요청하기'** 버튼을 클릭하면 검토가 시작돼요.\
검토는 **영업일 기준 최대 3일** 소요됩니다.

* **테스트를 1회 이상 완료한 경우에만** 검토 요청 버튼이 활성화됩니다.
* 검토 요청은 **한 번에 하나의 버전만** 제출할 수 있어요.

검토 요청 후 수정이 필요한 버그를 발견한 경우에는\
**'요청 취소하기'** 버튼을 눌러 검토를 취소한 뒤,\
수정된 **새로운 번들(.ait)** 을 업로드하고 다시 검토를 요청하세요.

![이미지](/assets/release-14.DCwiej9C.png)

### 검토가 반려된 경우

'반려사유 보기' 버튼을 눌러 사유를 확인한 뒤,\
문제를 해결하여 **새로운 번들을 업로드 후 다시 검토 요청**을 진행해 주세요.

반려 사유에 대해 추가로 문의 사항이 있다면 [채널톡](https://apps-in-toss.channel.io/workflows/787658)으로 문의하실 수 있어요.

![이미지](/assets/release-12.rWk4AKsb.png)

## 3. 출시하기

번들이 승인되면 **검수 결과가 이메일로 안내**돼요.\
이후 콘솔에서 **'출시하기'** 버튼을 클릭하면 미니앱이 사용자에게 공개됩니다.

> ⚠️ **출시 즉시 전체 사용자에게 반영**되므로, 반드시 충분히 테스트한 뒤 출시하세요.

![이미지](/assets/release-13.Cd0SxNoN.png)

::: tip 🔍 테스트 환경과 실제 환경 차이 안내

테스트 환경과 실제 라이브 환경의 **CORS 정책 및 네트워크 동작**이 다를 수 있어요.\
특히 아래 기능은 실제 환경에서도 반드시 동작을 다시 확인해 주세요.

* 메모리/리소스 사용량
* 네트워크 요청(CORS)
  * Origin 허용 목록에 다음 도메인을 등록해야 해요.
    * 실제 서비스 환경: `https://<appName>.apps.tossmini.com`
    * QR 테스트 환경: `https://<appName>.private-apps.tossmini.com`
* 권한 처리
* 로그인/세션 유지
* 실제 결제·인증 기능

> ⚠️ 테스트 환경에서는 정상이어도, 실제 환경에서는 오류가 발생할 수 있어요.

:::

## 4. 출시 후 관리

출시 후에는 앱인토스 콘솔에서 버전 관리와 업데이트를 진행할 수 있어요.\
필요에 따라 **새 번들을 업로드**하거나 **기존 버전을 유지·관리**할 수 있습니다.

### 4-1. 새 버전(업데이트) 배포

* 새 기능을 추가하거나 오류를 수정한 경우, 기존과 동일한 방식으로 **새 앱 번들(.ait)** 을 업로드하세요.
* 업로드된 번들은 다시 **검토 요청 → 승인 → 출시** 단계를 거쳐요.
* 승인 후 **출시하기** 버튼을 누르면 새 버전이 기존 앱을 대체해요.

> ⚠️ 출시된 버전은 즉시 사용자에게 반영되므로, 사전에 충분한 테스트를 진행한 뒤 업로드하세요.

### 4-2. 이전 버전 유지 및 롤백

* **'앱 출시'** 메뉴에서 기존에 출시된 버전 목록을 확인할 수 있어요.
* 문제가 발생하면 **이전 버전으로 롤백** 할 수 있어요.
* 롤백할 버전을 선택한 후 **'출시하기'** 버튼을 클릭하세요.

> ⚠️ 롤백 역시 사용자에게 즉시 반영되므로, 버전 선택 시 주의하세요.

![이미지](/assets/release-15.C8jx76aO.png)

![이미지](/assets/release-16.DbtwrkoN.png)

### 4-3. 긴급 수정(핫픽스)

* 앱 실행에 심각한 오류가 발생한 경우, **[채널톡](https://apps-in-toss.channel.io/workflows/787658)으로 즉시 문의**해 주세요.
* 긴급 상황에서는 신속히 대응합니다.

### 4-4. 출시 후 모니터링

출시 직후에는 예상치 못한 오류나 성능 이슈가 발생할 수 있어요.\
아래 항목을 중심으로 **출시 후 모니터링**을 권장해요.

* 주요 오류 로그 및 크래시 로그
* [Sentry 설정하기](/learn-more/sentry-monitoring.md)를 통한 Sentry 모니터링
* API 응답 지연/실패율
* 사용자 피드백 및 사용성 문제
  * 내비게이션 바의 ‘신고하기’ 기능을 통해 사용자 의견을 받을 수 있어요.
  * 접수된 피드백은 콘솔의 '신고 내역' 메뉴에서 확인할 수 있어요.
* 외부 리소스/CDN 로딩 지연 또는 실패 이슈

---

---
url: 'https://developers-apps-in-toss.toss.im/checklist/publicity.md'
description: >-
  앱인토스 미니앱 서비스의 보도자료 배포 가이드입니다. 배포 절차, 제목 템플릿, 작성 리소스, 표현 가이드, 앱인토스 로고 활용 방법을
  확인하세요.
---

# 보도자료 가이드

앱인토스에 론칭한 미니앱 서비스의 보도자료를 배포할 때 필요한 정보를 확인할 수 있어요.\
이를 통해 정확하고 일관된 정보를 언론에 전달할 수 있어요.

## 1. 배포 절차

앱인토스 파트너사는 관련 내용을 보도자료로 배포하는 경우, 토스팀에게 **사전 공유**해 주세요.\
사전 리뷰 단계에서 배포 가능 여부, 자료 내용 등을 전반적으로 조율할 수 있어요.\
보도자료 리뷰는 [**채널톡**](https://apps-in-toss.channel.io/workflows/787658)을 통해 요청해 주세요.

## 2. 작성 가이드

:::info **본 가이드라인에 사용되는 용어의 정의를 알려 드려요.**

* **‘앱인토스(Apps-in-Toss)’** 는 미니앱을 론칭할 수 있는 시스템이자 생태계를 가리키는, 백엔드 및 파트너사 대상의 공식 명칭이에요.
* **‘토스 미니앱(Toss Mini App)’** 은 토스 앱 내에서 B2C 사용자를 대상으로 제공되는 UI 및 마케팅·홍보 용어예요.
* **\[법인명]** 은 앱인토스 파트너사의 회사명이에요.
* **\[서비스명]** 은 토스 미니앱에서 노출되고 있는 명칭 그리고 토스 앱에서 검색 가능한 명칭이에요.
  :::

### **1) 보도자료 제목 템플릿**

아래와 같은 제목을 보도자료에 활용하실 수 있어요.\
주의해야 하는 표현들은 [ **3) 이런 표현은 지양해 주세요.** ](/checklist/publicity.html#_3-이런-표현은-지양해-주세요) 에서 참고해 주세요.

* **\[서비스명], 토스 미니앱 출시**
* **\[법인명] \[서비스명], 토스 미니앱 공식 론칭**
* **\[서비스명], 토스 미니앱 서비스 시작**

### **2) 보도자료 작성 리소스**

보도자료 본문 작성에 참고할 수 있는 토스 및 미니앱 관련 정보들이에요.

필요한 내용을 발췌하여 사용하실 수 있어요.

* **토스 소개**
  * 토스 누적 가입자: 3000만 명 **(2025년 8월 말 기준)**
  * 토스 월간 활성 이용자 수: 2480만명 **(2024년 말 기준)**
* **미니앱 설명**
  * 토스 미니앱은 토스 앱 내에서 앱인앱 형태로 다양한 서비스들을 이용할 수 있는 서비스다. 이용자들은 별도의 회원가입이나 앱 다운로드 없이 토스 미니앱 또는 게임 메뉴에서 파트너사의 서비스를 이용할 수 있다.

### 3) 이런 표현은 지양해 주세요.

‘토스 미니앱 출시’ 외에 **아래 표현들을 보도자료에서 사용하는 것은 어려워요.**

* **토스 미니앱 출시 (O)**
* 토스 공식 파트너사 (X)
* 토스 입점사 (X)
* 토스 제휴사 (X)
* 토스 입점 / 토스 미니앱 입점 (X)

### 4) 보도자료 작성 예시

**에어로무브, 토스 미니앱 공식 출시**

* 전동 킥보드·전기 자전거를 토스 앱으로 즉시 대여
* 위치 기반 실시간 배터리 잔량 확인, 원클릭 결제 지원

2025년 9월 15일 – 모빌리티 스타트업 네오트랜스(NeoTrans)가 초단거리 개인 모빌리티 예약 서비스 ‘에어로무브(AeroMove)’를 토스 미니앱으로 공식 출시했다고 15일 밝혔다.

에어로무브는 도심 내 단거리 이동에 최적화된 퍼스널 모빌리티 통합 플랫폼이다. 사용자는 토스 앱을 통해 주변에 배치된 전동 킥보드와 전기 자전거를 실시간으로 확인하고, 원하는 기기를 즉시 대여할 수 있다. 특히 △실시간 위치 추적 △배터리 잔량 표시 △이용 가능 시간 안내 등 다양한 편의 기능을 제공해 이동 전 불확실성을 최소화했다.

또한 토스의 결제 인프라를 기반으로 원클릭 결제·이용 내역 자동 저장을 지원하며, 보험 연동과 안전 가이드를 함께 제공해 이용자 안전성도 강화했다. 이번 토스 미니앱 출시로 이용자들은 별도의 앱 설치나 회원가입 없이 토스 앱 안에서 에어로무브를 간편하게 경험할 수 있다.

한편, 토스 미니앱은 토스 앱 내에서 다양한 서비스를 앱인앱(App in App) 형태로 제공하는 플랫폼이다. 금융뿐만 아니라 생활 밀착형 서비스, 온·오프라인 매장 연계, 게임, 엔터테인먼트까지 폭넓은 영역을 아우르며, 하나의 앱으로 금융과 일상생활을 연결하는 사용자 경험을 제공한다.

네오트랜스 관계자는 “토스 미니앱 출시로 에어로무브가 더 많은 사용자에게 다가갈 수 있게 됐다”며, “앞으로도 누구나 도심 속에서 쉽고 안전하게 이동할 수 있도록 서비스를 발전시켜 나가겠다”고 말했다.

## 3. 앱인토스 로고 및 가이드

앱인토스 로고는 주로 홍보나 보도자료에서 \[회사명(개발사명)]과 함께 활용할 수 있어요.
표기는 아래와 같이 ‘ **| ’(Bar) 표기**를 활용 해야 하며, 로고 파일은 **[채널톡](https://apps-in-toss.channel.io/workflows/787658)** 을 통해 요청해 주세요.

![](/assets/publicity_3.BmdOgaAB.png)

## 4. 외부 광고 가이드라인

보도자료 외에 외부 채널에서 마케팅을 진행하는 경우에는 [**외부 광고 가이드**](/marketing/guideline.html)를 참고해 주세요.

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: "보도자료를 배포하기 전에 반드시 토스팀과 공유해야 하나요?",
a: \`네. 반드시 사전 공유를 부탁드려요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/RewardedAd.md
---

# 보상형 광고 로드 응답 객체

## `RewardedAd`

`RewardedAd` 는 보상형 광고의 ID와 응답 정보를 담고 있는 객체예요. 광고를 로드한 뒤, 관련 정보를 확인할 때 유용해요.

## 시그니처

```typescript
interface RewardedAd {
  adUnitId: string;
  responseInfo: ResponseInfo;
}
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/LoadAdMobRewardedAdParams.md
---

# 보상형 광고 옵션 객체

## `LoadAdMobRewardedAdParams`

`LoadAdMobRewardedAdParams` 는 보상형 광고를 불러오는 함수에 필요한 옵션 객체예요.

## 시그니처

```typescript
type LoadAdMobRewardedAdParams = AdMobHandlerParams<LoadAdMobRewardedAdOptions, LoadAdMobRewardedAdEvent>;
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/ShowAdMobRewardedAdParams.md
---

# 보상형 광고 옵션 객체

## `ShowAdMobRewardedAdParams`

`ShowAdMobRewardedAdParams` 는 불러온 보상형 광고를 보여주는 함수에 필요한 옵션 객체예요.

## 시그니처

```typescript
type ShowAdMobRewardedAdParams = AdMobHandlerParams<ShowAdMobRewardedAdOptions, ShowAdMobRewardedAdEvent>;
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/LoadAdMobRewardedAdEvent.md
---

# 보상형 광고 이벤트 타입

## `LoadAdMobRewardedAdEvent`

`LoadAdMobRewardedAdEvent` 는 보상형 광고를 불러오는 함수에서 발생하는 이벤트 타입이에요. `loaded` 이벤트가 발생하면 광고를 성공적으로 불러온 거예요. 이때 [RewardedAd](/bedrock/reference/framework/광고/RewardedAd) 객체가 함께 반환돼요. `userEarnedReward` 이벤트는 사용자가 광고를 끝까지 시청해, 보상 조건을 충족했을 때 발생해요.

## 시그니처

```typescript
type LoadAdMobRewardedAdEvent = AdMobFullScreenEvent | {
  type: 'loaded';
  data: RewardedAd;
} | {
  type: 'userEarnedReward';
};
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/ShowAdMobRewardedAdEvent.md
---

# 보상형 광고 이벤트 타입

## `ShowAdMobRewardedAdEvent`

`ShowAdMobRewardedAdEvent` 는 보상형 광고를 보여주는 함수에서 발생하는 이벤트 타입이에요. `requested` 이벤트가 발생하면 광고 노출 요청이 Google AdMob에 성공적으로 전달된 거예요.

## 시그니처

```typescript
type ShowAdMobRewardedAdEvent = {
  type: 'requested';
};
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인증/tosscertResult.md
---

# 본인확인 결과 조회

사용자 인증 결과를 조회하는 API예요. `txId`로 결과를 확인해요. 조회는 반드시 **서버-서버 통신**으로 진행해 주세요.\
본인확인 결과로 수집한 정보는 서버에 안전하게 저장하고, 이후 전자서명/간편인증 시 해당 정보와 비교·검증 해 주세요.

:::tip 주의하세요
결과조회 API는 성공 기준으로 최대 2회까지 조회가 가능해요.\
사용자 인증을 끝마친 후 60분(1시간) 이내 결과 조회를 끝내야 해요. 60분을 초과하면 결과 조회가 제한되며 인증 요청 API부터 다시 시작해야 해요.
:::

:::info BaseURL
`https://cert.toss.im`
:::

* Content-type : application/json
* Method : `POST`
* Endpoint : `/api/v2/sign/user/auth/id/result`

***

## 요청 예시

:::code-group

```bash [Shell(curl)]
curl --location --request POST 'https://cert.toss.im/api/v2/sign/user/auth/id/result' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' \
--header 'Content-Type: application/json' \
# 세션 키는 매 요청 시 새로 생성해야 합니다.
--data-raw '{
       "txId" : "c1ce9214-9878-4751-b433-0c96641b0e13",
       "sessionKey" : "v1$71c3d6cd-6a74-48a8-8ab2-b48e6133ae6f$Q0U7Bdg4dWd0XXucjsM/mda89bFU7eHnoUhgQ3k+cGQ9gv37jvWC+8isrkO2CR4+qgoPg+U+K7/tQH2m+uU7L8Ab0gzbQo6ASX39NpcP6RHpI+VBi323ssYnBmJL7n0z4aNm6raUEsMoNwrOaMDe0DqfalgOeZgZUztWew1pfZul2Q3/WIBMdp+npS4sFnBRoBrzLroVsuNRTLK0XT6m5hak+ys+vBg5vZFoI0JN7j7zsr8lqGi6piSkygl1PLPugnSC9cOezxMoVN5c/csEVQxMsfkwqTIASaZVECnP50dO70TydYhBFCqxw3DpEDBHcXNDucOtdVOPslCPNx3NZv1i0IH0r92ULb3w2Y0Fncy4/xL1dPSS+TbA5540u2Wb3cxqVNHib7WwSMHBwQtXAnFSFZmcvQQPXtTeQ7SCvNnhA8k3gbboSpbDBg60RWn/1zF/ogBYRldO1BFtq7KP+jOm6I2OSSVpagH1Wu5MXhEtiTmsx7M8j/IM8EfnXbD9axJnlW2fKHZVvAj+5KNhqy90PUimBCKiXqjvUwOqb9hGGEzJ4JVKbIIiy1EYOaRkPTK9GurZwQaqM4o4c8pzOYRQR/3XIPWHxLv/jwsaMcfUIQFyKE+w898g+l1zO0jcck59/R64kZcirT9AsGFnRUWrsHGIkM95jdYlpUsnCXw="
  }'
```

```java
URL url = new URL("https://cert.toss.im/api/v2/sign/user/auth/id/result");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST"); 

httpConn.setRequestProperty("Authorization", "Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ");
httpConn.setRequestProperty("Content-Type", "application/json"); 

// 세션 키는 매 요청 시 새로 생성해야 합니다.
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("{" +
        "\"txId\" : \"c1ce9214-9878-4751-b433-0c96641b0e13\"," +
        "\"sessionKey\" : \"v1$71c3d6cd-6a74-48a8-8ab2-b48e6133ae6f$Q0U7Bdg4dWd0XXucjsM/mda89bFU7eHnoUhgQ3k+cGQ9gv37jvWC+8isrkO2CR4+qgoPg+U+K7/tQH2m+uU7L8Ab0gzbQo6ASX39NpcP6RHpI+VBi323ssYnBmJL7n0z4aNm6raUEsMoNwrOaMDe0DqfalgOeZgZUztWew1pfZul2Q3/WIBMdp+npS4sFnBRoBrzLroVsuNRTLK0XT6m5hak+ys+vBg5vZFoI0JN7j7zsr8lqGi6piSkygl1PLPugnSC9cOezxMoVN5c/csEVQxMsfkwqTIASaZVECnP50dO70TydYhBFCqxw3DpEDBHcXNDucOtdVOPslCPNx3NZv1i0IH0r92ULb3w2Y0Fncy4/xL1dPSS+TbA5540u2Wb3cxqVNHib7WwSMHBwQtXAnFSFZmcvQQPXtTeQ7SCvNnhA8k3gbboSpbDBg60RWn/1zF/ogBYRldO1BFtq7KP+jOm6I2OSSVpagH1Wu5MXhEtiTmsx7M8j/IM8EfnXbD9axJnlW2fKHZVvAj+5KNhqy90PUimBCKiXqjvUwOqb9hGGEzJ4JVKbIIiy1EYOaRkPTK9GurZwQaqM4o4c8pzOYRQR/3XIPWHxLv/jwsaMcfUIQFyKE+w898g+l1zO0jcck59/R64kZcirT9AsGFnRUWrsHGIkM95jdYlpUsnCXw=\"" +
        "}");
writer.flush();
writer.close(); 

httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() / 100 == 2
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
```

```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://cert.toss.im/api/v2/sign/user/auth/id/result');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization' : 'Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ',
    'Content-Type' : 'application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
       "txId" : "c1ce9214-9878-4751-b433-0c96641b0e13",
       "sessionKey" : "v1$71c3d6cd-6a74-48a8-8ab2-b48e6133ae6f$Q0U7Bdg4dWd0XXucjsM/mda89bFU7eHnoUhgQ3k+cGQ9gv37jvWC+8isrkO2CR4+qgoPg+U+K7/tQH2m+uU7L8Ab0gzbQo6ASX39NpcP6RHpI+VBi323ssYnBmJL7n0z4aNm6raUEsMoNwrOaMDe0DqfalgOeZgZUztWew1pfZul2Q3/WIBMdp+npS4sFnBRoBrzLroVsuNRTLK0XT6m5hak+ys+vBg5vZFoI0JN7j7zsr8lqGi6piSkygl1PLPugnSC9cOezxMoVN5c/csEVQxMsfkwqTIASaZVECnP50dO70TydYhBFCqxw3DpEDBHcXNDucOtdVOPslCPNx3NZv1i0IH0r92ULb3w2Y0Fncy4/xL1dPSS+TbA5540u2Wb3cxqVNHib7WwSMHBwQtXAnFSFZmcvQQPXtTeQ7SCvNnhA8k3gbboSpbDBg60RWn/1zF/ogBYRldO1BFtq7KP+jOm6I2OSSVpagH1Wu5MXhEtiTmsx7M8j/IM8EfnXbD9axJnlW2fKHZVvAj+5KNhqy90PUimBCKiXqjvUwOqb9hGGEzJ4JVKbIIiy1EYOaRkPTK9GurZwQaqM4o4c8pzOYRQR/3XIPWHxLv/jwsaMcfUIQFyKE+w898g+l1zO0jcck59/R64kZcirT9AsGFnRUWrsHGIkM95jdYlpUsnCXw="
       }');
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$response = curl_exec($ch);

curl_close($ch);
```

:::

## 요청 헤더

| 이름 | 타입 | 필수값 여부 | 설명 |
|---|---|---|---|
| Authorization | string | Y | `Bearer {Access Token}` |
| Content-Type | string | Y | `application/json` |

## 요청 파라미터

| 이름 | 타입 | 필수값 여부 | 설명 |
|---|---|---|---|
| txId | string | Y | 결과 확인이 필요한 인증 요청 트랜잭션 아이디 |
| sessionKey | string | Y | 결과조회에서는 인증수단과 무관하게 `txId`와 함께 필수로 전달. 요청/응답 AES 암·복호화용 세션 키로, 매 요청마다 새로 생성하고 인증요청에서 사용한 세션키는 재사용 금지 |

## 성공 응답

| 이름 | 타입 | 설명 |
|---|---|---|
| resultType | string | 성공 시 `SUCCESS` |
| success.txId | string | 결과를 조회한 인증 트랜잭션 아이디 |
| success.status | string | `COMPLETED` *(결과 조회가 정상 처리된 상태)* |
| success.userIdentifier | string | null | 현재 버전 미사용 (`null`) |
| success.userCiToken | string | null | 현재 버전 미사용 (`null`) |
| success.signature | string | 사용자가 서명한 전자서명 값(**Base64 인코딩된 DER**). **txId와 함께 저장 관리 필수** |
| success.randomValue | string | null | 현재 버전 미사용 (`null`) |
| success.completedDt | string | 사용자 인증 완료 시각 (`YYYY-MM-DDThh:mm:ss±hh:mm`, ISO 8601) |
| success.requestedDt | string | 최초 인증 요청 시각 (`YYYY-MM-DDThh:mm:ss±hh:mm`, ISO 8601) |
| success.personalData | object | 인증에 사용된 **개인정보(암호화 값)**. 하위 필드 표 참고 |

### personalData(인증을 진행한 사용자 개인정보) Object

| 이름 | 타입 | 설명 |
|---|---|---|
| ci | string | 암호화된 사용자의 CI |
| name | string | 암호화된 사용자의 이름 |
| birthday | string | 암호화된 생년월일 8자리 |
| gender | string | 암호화된 성별 정보 (`MALE` | `FEMALE`) |
| nationality | string | 암호화된 국적 (`LOCAL` | `FOREIGNER`) |
| ci2 | string | null | 예측 불가 상황에서 ci 유출 대응을 위한 임시 파라미터, `null` 고정 |
| di | string | 암호화된 사용자의 DI |
| ciUpdate | string | null | 예측 불가 상황에서 ci 유출 대응을 위한 임시 파라미터, `null` 고정 |
| ageGroup | string | 암호화된 성인여부 (`ADULT` | `MINOR`) |

```json
// 결과조회 응답에서는 인증을 호출하는 방식에 상관없이 동일한 바디 파라미터를 제공합니다.
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "c1ce9214-9878-4751-b433-0c96641b0e13",
    "status": "COMPLETED",
    "userIdentifier": null,
    "userCiToken": null,
    "signature": "MIIJCAYJKoZIhvcN...(생략)...ghkgBZQMEAgEFADCBwwYJKoZIhvcNAQcBoIG1BIGyeyJ0eElkIjoiZGU1ZjVkNDItNTA4Yi00Njg2LWJiYzAtNDczNmJmZWJhY2FkIiwicGFydG5lckNvZGUiOiJURVNUMSIsInNlcnZpY2VUeXBlIjoi6rCE7Y647J247KadIiwiaWRlbnRpZmllciI6bnVsbCwidXNlcklkZW50aWZpZXIiOm51bGwsInJlcXVlc3RUcyI6IjIwMjItMDQtMjJUMDE6MDU6NDIrMDk6MDAifaCCBiUwggYhMIIECaADAgECAgN2Xf8wDQYJKoZIhvcNAQELBQAwUTELMAkGA1UEBgwCS1IxGzAZBgNVBAoMElZpdmEgUmVwdWJsaWNhIEluYzESMBAGA1UECwwJVG9zcyBDZXJ0MREwDwYDVQQDDAhUb3NzIENBMTAeFw0yMjA0MTQwMjM0MTFaFw0yNTA0MTMxNDU5NTlaMHwxCzAJBgNVBAYTAktSMRswGQYDVQQKDBJWaXZhIFJlcHVibGljYSBJbmMxEjAQBgNVBAsMCVRvc3MgQ2VydDEoMCYGCgmSJomT8ixkAQEMGDcwMDI3MjMyMDIxMTEzMDgwMjAwOTk5MTESMBAGA1UEAwwJ6rmA7IiY67mIMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAljEvPPqzfLIkulmJJ45z+1jfron60TSXRx9KWeVXt41yU7qgoWQkrhOVd4g/AGwS2jxStjJ2TU7AFEaTMhA6KLkMhrsE3l48B//AaTh2UA0NEVwa+/C2Aw7qh5rg170yEe0sRVs5syH3R4bEiGia0CmSGSRnVIgNuazVf/EpHAvAvkEcknn6VjrivylLsHlq2UYTZw7t8Ijva51tiS660XUOfeamJniUfyqiYZZGtrOtF1FCuOldECGt3C6oJytmg4R4MIIfouEUfWEeiZKL1//AiQ2i1I0zJDKqH7eB54534yuJFtQs4ocIlNg/VMbJYWaOjRooTxRqabquNb41MQIDAQABo4IB1TCCAdEwfgYDVR0jBHcwdYAUIOEEYoA6EFhC3FSBskx+jPX3qh+hWqRYMFYxCzAJBgNVBAYMAktSMRswGQYDVQQKDBJWaXZhIFJlcHVibGljYSBJbmMxEjAQBgNVBAsMCVRvc3MgQ2VydDEWMBQGA1UEAwwNVG9zcyBSb290IENBMYIBAjAdBgNVHQ4EFgQUzGBp9tdMgfWMqyYxYqNQ9CaPHkIwDgYDVR0PAQH/BAQDAgbAMIGLBgNVHSABAf8EgYAwfjB8BgsqgxqMmyIFAQEBAzBtMCsGCCsGAQUFBwIBFh9odHRwOi8vY2EuY2VydC50b3NzLmltL2Nwcy5odG1sMD4GCCsGAQUFBwICMDIeMABUAGgAaQBzACAAaQBzACAAVABvAHMAcwAgAGMAZQByAHQAaQBmAGkAYwBhAHQAZTBbBgNVHR8EVDBSMFCgTqBMhkpodHRwOi8vY2EuY2VydC50b3NzLmltL2NybC90b3NzX2NybF9kcDJwMjU4Ni5jcmw/Y2VydGlmaWNhdGVSZXZvY2F0aW9uTGlzdDA1BggrBgEFBQcBAQQpMCcwJQYIKwYBBQUHMAGGGWh0dHA6Ly9vY3NwLmNlcnQudG9zcy5pbS8wDQYJKoZIhvcNAQELBQADggIBABgt3/wzvsAMXX9JJK1JJbgXO5Ft5TdoJEdJXwdjIVrSDg62vreg9K3sR7pAz7Zw3/IUabWrChMnIfD8fmbVB1vB0vX+S9HcvIkNhhM5m3rQUnEMpsO+oK73IZ7E9IHKfYUy0QrrjVwqQakKI5Zc6YfLd9oCWSWh25oGwUgo524gkC86xYG2CLGpP4bDLEIZQe5+Dg+2v6KWuouDI/SnYkAXU+Qi0+YYGR3w3d2Qp5yqZ/D5hcR2aOEFDfl31NwVVeJ1lCHE+bhhqoxZzfUDl+2X1jHdIRyZ+kYARJg5VI+if9OhtT+pI1d55EGCkgi+xRlp03mCLHFr4a5KjZG4+5ds+73s2dUasAeiaZ6XmisfjtR1Gs5eV4wgtBJ12+faBxXIPhhDvZaO5Ag7ehMAyrn8VwgQAC5WMnsMqRx4t1AwInU9NgMRhKxjxrBxhWzjVBmBjeD891OHQO4pFF6QC5SzFj4ud/sX2XkB2iKj8aJUDeBN5H03FDmd0v6li3OZ2L2O5vcFVKK62EJazk7okXDTfiSf8lJa35lZPR170LqDSNOtp5u/HkdYPFZzEt0ROn5x3drEMSvrLtzCmEfgAj5NHKZfmj2VrXvRXALXXhENQLOqsWxbMrX19VyaXeUdz2+EHPwYybiRvqpqw5ZXx67HJtRRFIIBfSUjzGAnk8GIMYIB7jCCAeoCAQEwWDBRMQswCQYDVQQGDAJLUjEbMBkGA1UECgwSVml2YSBSZXB1YmxpY2EgSW5jMRIwEAYDVQQLDAlUb3NzIENlcnQxETAPBgNVBAMMCFRvc3MgQ0ExAgN2Xf8wDQYJYIZIAWUDBAIBBQCgaTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMjA0MjExNjA1NTNaMC8GCSqGSIb3DQEJBDEiBCDFQjwDSF7RJrV5Cg3x6GlErYK7YwZV5b23yGTMuMKgXjANBgkqhkiG9w0BAQEFAASCAQBAcLs7q9Uy4Krsx8ynUgy5zyV1+QD4Er9uxpxfLuSXFw3kSbHdmQxekFN5G1aJSpQQtLHM0WhPpVZ/PnRxa2dBxt4gmIiAygjo9jsOsuU9xwbfxgIihD57Kf8H2zcPLUglDCoKP4k2c5o0GfzoOFvU31KPvWJDxPM/55TcmrJCwTWDEs76PviQcjq9IqYFxrm5jUhznCNnbew/xrGTvCNPQhge5/rapMh7UYPbsxXWaj29zC/jnDJXsiteFA6bbaFSrPJNMQHV+czza6jzS+XhaRPohmisszZ8YGbqPLvI0zmnMzIv947L3bknwPtgY5wEYg+cKPZ6SxJxpJW0DPs/",
    "randomValue": null,
    "completedDt": "2022-02-13T18:01:53+09:00",
    "requestedDt": "2022-02-13T18:00:26+09:00",
    "personalData": {
      "ci": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$X3g52aAyCBirz0UVp1oNRq0SfGtj66vGtUT3rp1aSdm1h//xmpm7vdf48fbGI2i7VTBj6TKG2rqanP6Yo9MiTQu63C8kLWayzWAMp+RLyXLovvnFb9SxxdblRtZbj5KRNlBWK9t2VXI=",
      "name": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$9oiJBRei1KI/SgXtXGmkfNHu+pdAUHXBxA==",
      "birthday": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$LQgw26ExChwWi8cQQz6GrdMAdMZGyaEI",
      "gender": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$WnREqd1HM/Ci7p+3KIqROusVkYeSAQ==",
      "nationality": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$UH5Kqd3dPV1daxw0i23eMWjeXcXC",
      "ci2": null,
      "di": "v1$2e161d9d-e620-443e-9a27-8db41cc96cf9$6GKr2zaUWWfI6rpJ6/AV9U4W0S4nhAMFIFLkt5CS6N8Gjb1Oc/dpitkMSSvLroDO5b6zdl9bufGSQ6SiVQdlYN2OWYFBr/Hb4e4AYwQpFxDbpi9ksYt52aFa3G2DwaNOQMUBkyQ1IWc=",
      "ciUpdate": null
    }
  }
}

```

## 실패 응답

| 이름 | 타입 | 설명 |
|---|---|---|
| resultType | string | 실패 시 `FAIL` |
| error.errorType | number | 에러 유형 |
| error.errorCode | string | 에러 코드(예: `CE3102`) |
| error.reason | string | 에러 메시지 |
| error.data | object | 부가 데이터(있을 경우) |
| error.title | string | null | 에러 제목(있을 경우) |

```json
{
  "resultType": "FAIL",
  "error": {
    "errorType": 0,
    "errorCode": "CE3102",
    "reason": "요청이 아직 완료되지 않았습니다.",
    "data": {},
    "title": null
  },
  "success": null
}

```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인증/tosscertStatus.md
---

# 본인확인 상태 조회

사용자의 인증 상태를 확인하기 위한 API로서 `txId`로 현재의 인증 진행 상태를 확인할 수 있어요.

:::tip 주의하세요
상태조회 API는 인증 진행 상태 확인용이에요. 응답만으로 '인증 완료'를 확정하지 마세요.\
인증 완료 여부는 **결과조회 API**를 기준으로 판별해요.
:::

:::info BaseURL
`https://cert.toss.im`
:::

* Content-type : application/json
* Method : `POST`
* Endpoint : `/api/v2/sign/user/auth/id/status`

***

## 요청 예시

:::code-group

```bash [Shell(curl)]
curl --location --request POST 'https://cert.toss.im/api/v2/sign/user/auth/id/status' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' \
--header 'Content-Type: application/json' \
--data-raw '{
      "txId": "633f3e1b-1a11-4e7c-9b35-dd391f440be4"
    }'
```

```java
URL url = new URL("https://cert.toss.im/api/v2/sign/user/auth/id/status");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST"); 

httpConn.setRequestProperty("Authorization", "Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ");
httpConn.setRequestProperty("Content-Type", "application/json");
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("{\"txId\": \"633f3e1b-1a11-4e7c-9b35-dd391f440be4\"}");
writer.flush();
writer.close(); 

httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() == 200
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
```

```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://cert.toss.im/api/v2/sign/user/auth/id/status');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization' : 'Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ',
    'Content-Type' : 'application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"txId": "633f3e1b-1a11-4e7c-9b35-dd391f440be4"}');
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$response = curl_exec($ch);

curl_close($ch);
```

:::

## 요청 헤더

| 이름 | 타입 | 필수값 여부 | 설명 |
|---|---|---|---|
| Authorization | string | Y | `Bearer {Access Token}` |
| Content-Type | string | Y | `application/json` |

## 요청 파라미터

| 이름 | 타입 | 필수값 여부 | 설명 |
|---|---|---|---|
| txId | string | Y | 상태 확인이 필요한 인증 요청 트랜잭션 아이디 |

***

## 성공 응답

| 이름 | 타입 | 설명 |
|---|---|---|
| resultType | string | 요청 결과. 성공 시 `SUCCESS` |
| success.txId | string | 조회한 인증 트랜잭션 ID |
| success.status | string | 인증 진행 상태 (아래 “status 값” 표 참고) |
| success.requestedDt | string | 최초 인증 요청 시각 (`YYYY-MM-DDThh:mm:ss±hh:mm`, ISO 8601) |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "633f3e1b-1a11-4e7c-9b35-dd391f440be4",
    "status": "REQUESTED",
    "requestedDt": "2022-02-13T18:00:26+09:00"
  }
}
```

***

## 실패 응답

| 이름 | 타입 | 설명 |
|---|---|---|
| resultType | string | 실패 시 `FAIL` |
| error.errorType | number | 에러 유형 |
| error.errorCode | string | 에러 코드(예: `CE3100`) |
| error.reason | string | 에러 메시지 |
| error.data | object | 부가 데이터(있을 경우) |
| error.title | string | null | 에러 제목(있을 경우) |

```json
{
  "resultType": "FAIL",
  "error": {
    "errorType": 0,
    "errorCode": "CE3100",
    "reason": "존재하지 않는 요청입니다",
    "data": {},
    "title": null
  },
  "success": null
}
```

***

## status 값

| 값 | 설명 |
|---|---|
| REQUESTED | 토스 인증서버에서 사용자의 토스 앱으로 인증이 요청된 상태 |
| IN\_PROGRESS | 사용자가 인증을 진행 중인 상태 |
| COMPLETED | 고객이 인증을 완료한 상태 *(최종 확정은 결과조회 API로 판단 해야해요)* |
| EXPIRED | 유효시간 만료로 인증 진행이 불가한 상태 |

---

---
url: 'https://developers-apps-in-toss.toss.im/bedrock/reference/framework/분석/init.md'
---

# 분석 초기 설정하기

## `init`

`init` 은 분석 기능을 시작할 때 설정을 적용하는 함수예요. 분석 기능을 사용하기 전에 반드시 호출해야 해요.

## 시그니처

```typescript
declare function init(options: AnalyticsConfig): void;
```

### 파라미터

---

---
url: 'https://developers-apps-in-toss.toss.im/checklist/app-nongame.md'
description: >-
  비게임 미니앱 출시 전 필수 체크리스트입니다. 내비게이션 바, 토스 로그인, 결제, 디자인 가이드 등 출시 검토 통과를 위한 상세 가이드를
  확인하세요.
---

# 비게임 출시 가이드

비게임 미니앱 출시 전에 꼭 확인해야 할 체크리스트를 정리했어요.\
아래 내용을 지키지 않으면 앱 출시 검토에서 반려될 수 있으니 반드시 확인해주세요.

:::info **확인해 주세요**

* 앱 출시 검토 전에는 **앱 정보 검토, 사업자 인증, 대표관리자 신청 승인**이 먼저 완료되어야 해요.
  * [**콘솔에서 앱 등록하기**](/prepare/console-workspace.html)를 확인해 주세요.
* [**다크패턴 방지 정책**](/design/consumer-ux-guide.html) 및 [**미니앱 브랜딩 가이드**](/design/miniapp-branding-guide.html)을 꼭 준수해 주세요.
* 미니앱에서 제공하는 모든 내용에는 불법성·선정성 등 위법 콘텐츠가 없어야 해요.
* 자사 앱 및 자사 웹으로의 유도는 불가하므로 [**가이드**](/intro/guide.html#자사-앱-설치-외부-링크)를 꼭 준수해 주세요.
  :::

## 1. 시스템 모드

현재 앱인토스 미니앱 서비스는 다크모드를 제공하지 않아요.\
따라서 미니앱 내 테마는 라이트 모드 기준으로 설정해야 하고, 내비게이션 바 또한 라이트 모드로 고정되어야 해요. 추후 다크모드가 제공되면 공지해 드릴 예정이에요.

## 2. 확대/축소

미니앱의 화면을 손가락으로 확대 또는 축소하는 액션을 할 때에 관한 내용이에요.

* 미니앱 내에서 제스처를 통한 확대/축소 기능은 기본적으로 사용이 불가해요.
  * 사용자의 미니앱 경험을 수호하기 위함이에요.
  * 단, 지도 서비스를 제공하는 등 기능적으로 꼭 필요한 경우에만 제한적으로 이용할 수 있어요.

:::tip 핀치줌 막기
meta viewport에 `initial-scale=1, maximum-scale=1, user-scalable=no` 를 추가하면 모바일에서 핀치줌을 비활성화할 수 있어요.\
:::

## 3. 내비게이션 바

미니앱 상단에 위치하는 공통으로 적용되는 내비게이션 바를 말해요.

* 네비게이션을 구성하는 요소의 크기, 색상, 위치는 커스텀을 할 수 없어요.
* 내비게이션의 앱 로고가 일관되게 적용되도록 [콘솔에서 앱 등록하기](/prepare/console-workspace.md)를 참고해 주세요.
* **홈 버튼**과 **제휴사 기능 버튼** 추가하는 방법은 [내비게이션 바 설정](/bedrock/reference/framework/UI/NavigationBar.md) 문서를 참고하세요.

![](/assets/non-game-guide-3.BnPDpWVp.png)

| **위치** | **항목**           | **설명**                                                                                                                                                                                                                                    |
| -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **좌측** | 뒤로가기 버튼 (<)  | 선택- 히스토리백이 필요한 경우 사용해요.- 자체 UI 내에서 히스토리백을 수행할 수 있는 경우 사용하지 않아요.- 진입 시 첫 화면에서는 백버튼을 사용하지 않아요.                                 |
|          | 브랜드 로고 + 이름 | 필수                                                                                                                                                                                                    |
|          | 홈 버튼            | 선택- 미니앱 서비스의 홈으로 가는 진입점이 필요한 경우 사용해요.                                                                                                                                    |
| **우측** | 제휴사 기능 버튼   | 선택- 화면에 필요한 기능 1개를 노출시킬 수 있어요.- 모노 아이콘만 추가할 수 있어요.- 문구나 커스텀 UI는 지원하지 않아요.- 화면별로 커스텀이 가능해요. - 홈 버튼은 넣을 수 없어요. |
|          | 더보기 버튼 (⋯)    | 필수- 신고하기, 공유하기 등 토스의 기능이 들어가요.- 커스텀할 수 없어요.                                                                                                                        |
|          | 닫기 버튼 (X)      | 필수                                                                                                                                                                                                    |

## 4. 전반적인 서비스 이용 및 동작

원활한 사용자 경험을 위한 미니앱의 전반적인 이용 및 동작에 대한 내용이에요.

* 앱 정보의 나이 제한과 실제 서비스 내용이 일치해야 해요.
* 스크롤/인터랙션 반응은 2초 이상 지연되면 안 돼요.
  * 2초 이상이 될 경우 사용자가 이탈할 가능성이 높아져요.
* 재접속 시 데이터가 유지되어야 해요. (작성 중인 내용, 마이페이지 등)
* 모든 컴포넌트가 정상적으로 작동해야 해요.
  * 사용자가 접속할 수 없는 버튼이나 미니앱에서는 할 수 없지만 자사 앱/웹에는 기능을 제공한다는 등의 안내가 되는 컴포넌트는 사용할 수 없어요.
* 리스트 정렬·검색·필터링 기능이 정상 작동해야 해요.
  * 리스트 정렬은 ‘최근순 / 가격순’과 같은 기능을 제공하는 경우를 말해요.
* 기능화 되지 않은 컴포넌트는 포함하면 안 돼요.
  * 사용자가 접속할 수 없는 버튼이나 미니앱에서는 할 수 없지만 자사 앱/웹에는 기능을 제공한다는 등의 안내가 되는 컴포넌트는 사용할 수 없어요.
* 특정 연령층, 혹은 특정 그룹만 이해할 수 있는 유행어, 밈 등은 사용할 수 없어요.
  * [**UX 라이팅 가이드**](/design/ux-writing.html)에서도 확인할 수 있어요.

## 5. 접근성

앱인토스는 토스 앱의 서비스로서, **모든 사용자가 불편 없이 미니앱을 이용할 수 있도록 접근성 준수**를 권장하고 있어요.

* 텍스트·버튼 등 주요 요소의 **명도 대비(contrast)** 가 충분한지 확인해 주세요.
* 버튼, 조작 UI는 **터치 영역**을 확보해 주세요.
* 화면 전환, 애니메이션 등이 **지나치게 빠르거나 현기증을 유발하지 않도록** 구현해 주세요.
* 스크린 리더 사용 시 주요 콘텐츠가 의도한 순서대로 읽히는지 확인해 주세요.
* 접근성에 대한 더 자세한 사항은 [가이드](https://frontend-fundamentals.com/a11y/)를 참고해 주세요.

## 6. 앱 내 기능

앱 내 기능은 앱 출시하기를 통해 등록하는 것으로 사용자가 특정 기능에 바로 접속할 수 있게 제공하는 진입점이에요.

* 앱 내 기능으로 제공되는 모든 기능은 미니앱에서 모두 정상 동작해야 해요.
  * 예) “청소용품 알아보기” 라는 기능을 제공할 때, 해당 기능으로 접속 시 청소용품이 아닌 다른 상품으로 접속이 되면 안돼요.
* 기능별 앱 스킴 접속이 원활해야 하고, 뒤로가기도 정상 동작해야 해요.
  * 앱 내 기능은 특정 기능(메뉴)에 접속하게 되므로 뒤로가기를 누를 미니앱 메인화면으로 랜딩 되어야 해요.

## 7. 토스 로그인

토스 로그인을 사용한 경우에 아래 내용을 모두 확인해 주세요.

* **토스 로그인이 아닌 자사 로그인 및 기타 간편 로그인의 경우 사용이 불가해요.**
* 콘솔에서 등록한 약관 및 약관 확인 시 정상적으로 연결하는지 확인해 주세요.
* 약관 확인 및 체크 박스 선택과 하단의 ‘동의하고 시작하기’ CTA를 누를 경우 정상적으로 로그인이 진행되는지 확인해 주세요.
  * 로그인 실패로 노출이 되거나 로그인이 완료되었다면 다른 페이지로 이동 시 로그인이 풀리지 않아야 해요.
  * ‘동의하고 시작하기’를 하지 않고 ‘닫기’ 버튼을 눌러서 로그인 화면을 이탈하면 미니앱의 메인으로 복귀해야 해요.
* 토스앱 설정에서 ‘토스로 로그인한 서비스’ 에서 로그인을 끊으면 다시 미니앱 접속 시 기존 데이터가 남아 있지 않고 새롭게 로그인을 요청하는지 확인해 주세요.
* 토스 로그인을 사용할 때는 사용자가 서비스의 성격과 가치를 이해할 수 있도록 인트로 화면을 제공해야 하며, 서비스 소개 없이 곧바로 로그인을 유도하는 것은 허용되지 않아요.
* 토스 로그인 요청 화면에서 **‘닫기’** 를 누를 경우 아래와 같이 작동하게 해주세요.
  * 로그인을 인트로 페이지에서 약관을 받는 경우 닫기 버튼을 눌렀을 때 → **미니앱이 닫힘**
  * 서비스 플로우 중간에 약관을 받는 경우 → **이전 미니앱 화면으로 랜딩**

## 8. 토스페이

미니앱에서 결제 기능을 제공할 때 사용하는 토스페이 간편결제 연동에 관한 내용이에요.

* 미니앱 내에서 결제 기능이 필요한 경우 토스페이만 사용할 수 있어요.
  * 토스페이 외에 다른 결제 수단은 사용할 수 없어요.
* 주문 요청 금액과 결제창 금액이 일치해야 해요.
* 결제·취소가 정상 처리되어야 해요.
  * 토스페이 화면에서 결제가 정상적으로 진행되었을 때, 미니앱에서도 정상적으로 결제 진행이 완료되어야 해요.
  * 사용자가 결제 도중 취소를 하는 경우 미니앱 주문 화면으로 랜딩 되어야 해요.
* 결제 실패 시 오류 메시지를 안내해야 해요.
* 결제 내역은 미니앱에서도 확인할 수 있어야 해요.

## 9. 인앱결제

디지털 상품을 판매하는 경우 인앱결제를 연동하고, 연동 후에는 아래 내용을 꼭 확인해 주세요.

* 미니앱 내에서 표기된 상품의 금액과 실제 결제가 진행되는 애플 또는 구글플레이스토어 결제창의 금액이 일치하는지 확인해 주세요.
* 결제 진행 시 오류 없이 결제가 진행되고, 결제를 완료하지 않고 이탈하면 정상적으로 취소 처리가 되는지 확인해 주세요.
* 현재 구독 상품은 제공할 수 없어요.
* 오류 등으로 인해 결제가 실패되었다면 어떤 오류로 결제가 실패되었는지 사용자에게 안내해 주세요.
* 결제한 내역을 사용자가 확인할 수 있게 내역이 제공되는지 확인해 주세요.
* 사용자가 기기를 변경한 후에도 인앱결제를 통해 결제한 데이터가 유지되는지 확인해 주세요.

## 10. 프로모션

프로모션을 사용하는 경우에는 [**프로모션 검토 가이드**](/promotion/console.html#_8-프로모션-검토-가이드라인)를 꼭 확인해 주세요.

또한 자체적인 이벤트나 프로모션인 경우에도 프로모션 가이드 및 아래 내용은 진행할 수 없어요.

* 현금성 또는 환금성 이벤트
* 아이템, 기프티콘, 상품권 등을 현금화하거나 포인트를 토스포인트로 전환하는 이벤트
* 사행성 또는 투기성 등 성격의 이벤트

## 11. 기능성 메시지 발송

기능성 메시지는 ‘서비스 이용에 꼭 필요한 필수 알람’을 뜻해요.

결제 완료, 배송 중, 배송 완료 등 사용자가 꼭 받아야 하는 알림만 발송할 수 있어요.

* 콘솔에서 설정한 템플릿 형태로 푸시/알람이 정상 발송되어야 해요.
* [**푸시/알림 가이드**](/push/console.html)와 [**UX 라이팅 가이드**](/design/ux-writing.html)를 꼭 확인해 주세요.

## 12. 인앱광고

앱인토스 콘솔에서 인앱 광고를 설정하여 연동한 경우, 아래 항목을 반드시 확인해 주세요.\
광고 로딩, 종료, 리워드 처리 등은 모두 검수 항목에 포함돼요.

* 콘솔에서 설정한 **광고가 정상적으로 노출되는지** 확인해 주세요.
* **광고는 반드시 사전 로드(Preload)** 되어야 해요.
  * 페이지 진입 시마다 광고를 사전 로드해 두면 노출 지연을 방지할 수 있어요.
* **리워드 광고의 경우,** 광고가 **정상적으로 완료된 이후에만** 보상이 지급되어야 해요.
  * 광고가 중도 종료되거나 실패한 경우에는 보상이 지급되지 않아야 해요.
* 광고를 표시할 때(`show` 호출)에는 반드시 **광고 SDK에서 전달하는 이벤트(event)** 를 받아 처리해야 해요.
  * 이벤트를 수신하지 않은 상태에서 내부 처리를 진행하면 오류가 발생하거나 **eCPM(노출 단가)에 영향을 줄 수 있어요.**
* 광고 종료 후에는 **미니앱의 음악이 자동으로 재개**되어야 해요.
* 광고가 **정상 종료되거나 중도 종료될 경우,** 사용자 화면이 **정상적으로 미니앱으로 복귀(랜딩)** 되어야 해요.
* 출시 전에는 **테스트용 광고 ID가 설정되어 있지 않은지** 반드시 확인해 주세요.

## 13. 앱 사용 권한

개발한 미니앱에서 사용되는 권한들에 대한 내용이에요.

* 콘솔에서 앱 번들을 업로드하면 미니앱에서 필요한 권한들을 확인할 수 있어요.
* 사용이 필요한 권한이 정상적으로 적용 및 작동되고 있는지 꼭 확인해주세요.
* 사용자가 특정 권한 동의를 하지 않더라도 해당 기능을 제외한 나머지 기능이 정상적으로 작동되어야 해요.

![](/resources/checklist/non-game-guide-4.png)

## 14. 데이터 및 메모리 사용량

미니앱을 이용하면서 발생 되는 데이터 사용량과 메모리 사용량에 대한 내용이에요.

* 데이터 사용량이 과도하면 사용자의 불편과 부정적인 CS로 이어질 수 있어요.
* 메모리 누수가 발생할 경우 휴대폰 발열로 이어지며 사용자로 하여금 부정적인 경험을 제공하게 돼요.
* 앱인토스 검수 과정에서도 데이터 사용량과 메모리 사용량을 체크하니, **과도한 데이터 사용과 메모리 누수가 발생하지 않도록 꼭 확인해 주세요.**

## 15. 보안

**보안 이슈가 발생하는 경우에는 앱 출시 검토에서 반려될 수 있어요.**\
**반려된 경우, 자세한 사유는 이메일과 콘솔에서 확인할 수 있어요.**

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/audio-video.md
---
# 비디오 및 오디오 최적화

## 오디오

앱인토스 미니앱에서는 UnityAudio가 기본적으로 자동 적용돼요.\
필요하다면 FMOD 플러그인도 함께 사용할 수 있어요.

***

## 호환 원리

### UnityAudio 원리

* 긴 오디오 재생은 InnerAudio를 사용합니다
* 짧은 오디오 재생은 WebAudio를 사용합니다
* Unity 플러그인은 오디오 파일 크기에 따라 자동으로 다른 재생 방식을 적응 사용합니다

### FMOD 원리

* 모든 것이 WebAudio를 사용하므로 배경음악 등 대용량 파일에 FMOD 재생을 사용하는 것은 권장하지 않습니다. 많은 메모리를 차지합니다

### QnA

* 권장하는 오디오 형식은 무엇인가요?
  * mp3 또는 aac 형식을 권장하며, 양쪽 플랫폼에서 좋은 호환성을 가집니다

***

## 비디오

앱인토스 미니앱에서는 VideoPlayer 가 기본적으로 적용돼요.

### QnA

* 비디오 파일의 권장 형식은 무엇인가요?
  * MP4 형식(H.264 코덱)을 권장하며, 앱인토스 플랫폼에서 최적의 호환성을 제공합니다
  * 해상도는 1080p 이하를 권장하며, 비트레이트는 3Mbps 이하로 유지하여 로딩 시간을 최소화하세요

* 비디오 재생 중 게임 성능 저하가 발생할 때
  * 비디오 재생은 GPU 리소스를 많이 사용하므로 다른 그래픽 집약적인 작업과 동시에 실행하지 않는 것이 좋습니다
  * 특히 파티클 시스템이나 복잡한 셰이더와 함께 사용할 때 주의하세요

* 비디오 캐싱 및 미리 로딩 권장사항
  * 자주 사용되는 비디오는 게임 시작 시 미리 로딩하여 재생 지연을 방지하세요
  * 앱인토스 파일 시스템 API를 사용하여 비디오 파일을 로컬에 캐싱할 수 있습니다
  * 캐시 크기 관리에 주의하여 기기의 저장 공간을 과도하게 사용하지 마세요

---

---
url: 'https://developers-apps-in-toss.toss.im/prepare/register-business.md'
description: >-
  앱인토스 사업자 등록 및 계약 진행하는 과정을 안내합니다. 개인 사업자, 법인 사업자 별 등록해야하는 서류를 상세히 안내하고, 사업자 정보
  검토가 완료되면 계약을 진행하는 방법을 안내해요. 앱인토스는 사업자가 없어도 앱을 출시할 수 있어 관련 내용도 상세히 안내해요.
---

# 사업자 등록하기

::: tip 확인해 주세요

* 수익화 기능(인앱광고 및 인앱결제, 토스페이, 프로모션, 비즈월렛)과 토스 로그인 기능을 사용하기 위해서는 꼭 사업자(개인 또는 법인) 등록이 필요해요.
  :::

## 1. 사업자 등록하기

앱 등록 후 토스 로그인, 수익화 기능을 사용하려면 사업자 인증이 필요해요.\
사업자 유형에 따라 필요한 서류를 제출하고 앱인토스 계약을 진행해 주세요.

* **사업자 등록증에 기재된 업종과 미니앱을 출시하는 업종이 일치해야 하며, 다를 경우 출시가 제한될 수 있어요.**
* **앱인토스 콘솔 → 워크스페이스 → 파트너 정보 → 사업자 정보 ‘등록하기’** 에서 신청할 수 있어요.

사업자 유형에 따라 필요한 서류를 제출하고 검토를 요청하면, 영업일 기준 1~2일이 소요돼요.

![](/assets/registering-business.BRiCH4uu.png)

### 1) 법인 사업자일 때

증빙 서류 다섯 가지(사업자 등록증, 사업자 등기부등본, 법인 인감증명서, 대리인 위임장, 대리인 신분증 사본)를 모두 제출해야 해요.\
단, 대표자 본인이 직접 등록할 경우에는 사업자 등록증과 사업자 등기부등본만 제출하면 돼요.

::: tip 꼭 확인해 주세요

* 사업자 등기부등본은 3개월 이내 발급본을 제출해주세요. 3개월 이내 발급본이 아니라면 사업자 인증이 되지 않아요.
* 공동 대표인 경우, 공동 대표자 모두의 위임장 및 법인 인감증명서가 필요해요.
* 공동 대표 중 1인이 신청하는 경우, 다른 대표들의 위임장과 법인 인감증명서가 필요해요.
  :::

![](/assets/corporate_business_1.CGr7iht6.png)

![](/assets/corporate_business_2.BEgCVSdk.png)

### **2) 개인 사업자일 때**

사업자 등록증, 개인 인감증명서, 대리인 위임장, 대리인 신분증 사본 네 가지 증빙 서류를 제출해 주세요.\
단, 대표자 본인이 직접 등록할 경우에는 사업자 등록증만 제출하면 돼요.

![](/assets/individual_1.DKpGZIoQ.png)

![](/assets/individual_2.5s-VNzTf.png)

## 2. 계약 진행하기

사업자 정보 검토가 완료 되면, 대표 관리자의 이메일로 본 계약 관련 메일이 전송돼요.

### 1) 대표 관리자 메일 확인

메일을 열람한 뒤 ‘**약관 동의하러 가기’** 버튼을 눌러 본계약을 진행해 주세요.

![](/assets/boss_change_5.D3OtlddM.png)

### 2) 본 계약 화면

본 계약은 각 동의문을 끝까지 확인해야 동의 체크가 가능해요.\
약관을 선택한 후, 동의문 내 **동의하기** 버튼을 눌러 주세요.

![](/assets/console_2.CiApe9BF.png)

::: tip 사업자가 없어도 앱을 출시할 수 있어요.

앱인토스는 개인 또는 법인 사업자가 없어도 앱을 런칭할 수 있어요.

이를 통해 많은 파트너사와 함께 하며 다양한 서비스를 사용자에게 제공하여 보다 나은 경험을 함께 만들어 가고자 해요.\
다만, 보다 원활한 계약 및 정산 등을 위해 각 기능별 약관 동의가 필요한 수익화 기능 및 토스 로그인 기능을 제외하고 런칭이 가능해요.

만약 사업자 없이 앱을 런칭한 이후 사업자 등록을 희망한다면, 앱인토스 콘솔의 사업자 등록을 통해 각 기능별 약관 동의를 진행하면 돼요.

* 사업자 인증 경로: 콘솔 > 워크스페이스 > 파트너 정보

사업자가 있는 경우와 없는 경우의 각 기능별 사용 가능 여부는 아래 표를 참고해 주세요.

| 구분                 | 사업자가 있는 경우 | 사업자가 없는 경우                           |
| -------------------- | ------------------ | -------------------------------------------- |
| 토스 로그인          | 사용 가능          | **사용 불가** |
| 세그먼트             | 사용 가능          | 사용 가능                                    |
| 푸시, 알림           | 사용 가능          | 사용 가능                                    |
| 토스 홈 광고         | 사용 가능          | 사용 가능                                    |
| 비즈월렛             | 사용 가능          | **사용 불가** |
| 프로모션             | 사용 가능          | **사용 불가** |
| 게임 프로필&리더보드 | 사용 가능          | 사용 가능                                    |
| 공유 리워드          | 사용 가능          | 사용 가능                                    |
| 인앱광고             | 사용 가능          | **사용 불가** |
| 토스페이             | 사용 가능          | **사용 불가** |
| 인앱결제             | 사용 가능          | **사용 불가** |

:::

---

---
url: 'https://developers-apps-in-toss.toss.im/growth/retention.md'
description: >-
  앱인토스 사용자 리텐션 확보 가이드입니다. 세그먼트, 푸시, 토스 홈 광고를 활용한 맞춤형 커뮤니케이션으로 리텐션을 높이는 방법을
  확인하세요.
---

# 사용자 리텐션 확보하기

사용자가 앱에 들어왔다면, 이제는 그들이 계속 머물고 다시 돌아오도록 만드는 것이 중요해요.\
토스 세그먼트, 푸시, 토스 홈 광고 기능을 통해서 사용자의 관심사와 행동에 맞춘 맞춤형 커뮤니케이션으로 리텐션을 높여보세요.

***

## 토스 기능으로 리텐션 확보하기

### ① 세그먼트

::: tip 세그먼트
세그먼트는 푸시, 알림과 토스 홈 광고에서 특정 유저에게 발송하기 위한 사용자 그룹을 만드는 기능이에요.\
거래정보, 유저정보, 유저활동, 유저프로파일의 정보를 기반으로 유저 그룹을 생성할 수 있어요.\
[세그먼트 가이드 바로가기](/segment/console.md)
:::

지속적인 사용자 유입을 만들기 위해서는 **마케팅 메시지의 타겟**이 중요해요.\
기획한 메시지에 관심을 가질 수 있는 타겟을 설정해야 높은 CTR부터 전환율까지 기대할 수 있어요.

예를 들어, 나의 서비스를 사용했던 사용자에게 마케팅을 하여 **신규 기능, 이벤트 등을 홍보하고 재방문을 유도**하고자 한다면, **\[유저활동]의 \[서비스 방문] 세그먼트에게 발송**하는 것이 효과적이에요.\
서비스 방문 세그먼트는 앱과 기간을 설정해 만들 수 있어요.

![](/assets/growth_retention_1.y_oMMY6v.png)

그리고 콘텐츠에 적합한 인구통계 정보가 있다면 성별, 나이 등의 **세그먼트를 조합하여 활용**해요.\
즉, 나의 앱을 최근 30일 내 접속한 20대 남성 세그먼트를 만들 수 있어요.

![](/assets/growth_retention_2.D-hUoXtT.png)

### ② 푸시, 알림

::: tip 푸시, 알림
푸시, 알림은 푸시와 알림 두 가지 채널을 통해서 메시지를 보내는 기능이에요.

* 푸시: 푸시는 앱을 열지 않은 상태에서 받는 OS 메시지예요. 앱의 이름과 로고가 함께 노출돼요.
* 알림: 알림은 토스 앱 오른쪽 상단 > 종 아이콘을 누르면 보이는 앱 내 메시지예요.

[푸시, 알림 가이드 바로가기](/push/intro.md)
:::

**타겟과 적합한 메시지를 구성**하여 푸시를 보내는 것이 핵심이에요.\
사용자 유입을 만들 때처럼 세그먼트 맥락을 잘 파악하여 푸시를 보낸다면 지속적인 사용자 유입을 만들 수 있어요.

1. 서비스 방문 세그먼트에게 발송하는 경우\
   서비스를 방문한 사용자에게는 새로운 기능이나 혜택을 소개하는 메시지가 효과적이에요.\
   방문 경험이 있는 만큼, ‘이번 달 혜택’, ‘다시 이용할 이유’를 구체적으로 보여주면 클릭률이 높아져요.

> **이번 달 받을 수 있는 혜택 공지**\
> 김토스님은 5만원까지 전액 캐시백 대상자예요.

2. 사용자의 서비스 참여를 유도하고 싶은 경우\
   참여를 이끌고 싶을 때는 다른 사람들이 이미 참여하고 있다는 내용을 강조하면 좋아요.\
   “벌써 N명이 참여했어요”, “많은 분들이 도전 중이에요”처럼 사용자의 호기심과 경쟁심을 자극할 수 있어요.

> **한글날 특집 퀴즈가 도착했어요**\
> 벌써 27만 3,266명이 정답에 도전했어요.

3. 사용자가 서비스를 계속 이용하도록 만들고 싶은 경우\
   지속 이용을 유도할 때는 행동을 유발하는 단어를 활용해요.\
   ‘충전’, ‘도전’처럼 즉시 재참여를 떠올리게 하는 표현이 클릭을 유도해요.

> **응모권이 충전됐어요**\
> 뽑기에 다시 도전할 수 있어요.

4. 새로운 서비스를 알리고 싶은 경우\
   새로운 기능이나 서비스를 출시했을 때는 변화를 바로 느낄 수 있는 문장으로 시작하세요.\
   “새로 나왔어요”, “지금부터 이용할 수 있어요”처럼 즉시 이용 가능함을 강조하는 표현이 효과적이에요.

> **추석인사 서비스가 새로 나왔어요**\
> 오늘부터 내 얼굴로 추석카드 만들 수 있어요.

5. 유용한 팁이나 정보를 전달하고 싶은 경우\
   생활과 밀접한 정보나 꿀팁을 제공할 때는 짧고 흥미로운 문장으로 호기심을 자극하는 게 좋아요.\
   “○○ 알아보세요”, “정답을 알려드릴게요”처럼 정보 탐색 욕구를 자극하는 문장이 클릭률을 높여줘요.

> **국민연금 평균 수급액은 얼마일까요?**\
> 김토스님 정답을 알려드릴게요.

### ③ 토스 홈 광고

::: tip 토스 홈 광고
토스 홈 광고는 토스 홈 최상단 배너에 광고를 노출할 수 있는 기능이에요.\
캠페인을 손쉽게 진행하고, 성과 데이터를 바로 확인하며 개선할 수 있어요.\
[토스 홈 광고 가이드 바로가기](/intelli/intro.md)
:::

토스 홈 광고 역시 푸시, 알림처럼 **세그먼트에 적합한 광고를 노출**하는 것이 중요해요.\
토스 홈 광고의 **CTR이 4% 미만**이면 **노출이 제한되거나 중단**되므로, 높은 노출과 클릭을 위해 캠페인을 최적화하는 것이 좋아요.

캠페인 최적화를 위해서는 **위닝 소재 먼저 발굴**해야 해요.\
상단 문구, 하단 문구, 아이콘, 소구점을 다양하게 실험하면서 CTR이 높은 소재를 찾아보세요.\
이때 세그먼트를 넓게 설정하고, 소재만 실험하는 방식을 추천해요.\
많은 위닝 소재의 **하단 문구**는 ‘확인하기’, ‘보러가기’처럼 **간결하고 직관적인 문구**로 작성되었어요.

> 운세 모음집 도착\
> 확인하기

::: tip 위닝 소재 판단 기준은 무엇인가요?
앱인토스 팀에서 진행한 테스트 기간 동안, 위닝 소재의 평균 CTR은 약 10~15% 내외였어요.\
절대적인 수치에만 의존하기보다는, 같은 그룹 내에서 상대적으로 높은 CTR을 기록한 소재를 위닝 소재로 판단해도 좋아요.
:::

위닝 소재를 찾았다면 세그먼트를 다양하게 실험하며, 해당 소재의 노출량을 높여요.

* 세그먼트 모수가 적고 세밀할수록 CTR은 높아질 수 있지만, 노출량이 천천히 올라가요.
* 세그먼트 모수가 충분하면서 위닝 소재에 반응이 좋은 세그먼트를 발굴하면 가장 좋아요.

최적의 소재와 세그먼트를 발견했다면, 해당 과정을 반복·고도화해요.\
토스 홈 광고는 **하나의 캠페인 내 여러 그룹을 생성**하여 **소재와 세그먼트를 대상으로 A/B 테스트**를 진행할 수 있기 때문에 위닝 소재와 적합한 세그먼트를 찾기 효율적이에요.

![](/assets/growth_retention_3.DpENt8V7.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/growth/traffic.md'
description: '앱인토스 사용자 유입 가이드입니다. 세그먼트, 푸시, 토스 홈 광고, 프로모션을 활용해 효과적으로 사용자를 유입하는 방법을 확인하세요.'
---

# 사용자 유입 만들기

앱인토스를 통해 앱을 출시했다면, 이제 더 많은 사람들에게 서비스를 알리고 사용자를 만들어보세요.\
토스에서 제공하는 기능을 통해 성공적으로 사용자 유입을 만들 수 있어요.

***

## 토스 기능으로 유입 늘리기

### ① 세그먼트

::: tip 세그먼트
세그먼트는 푸시, 알림과 토스 홈 광고에서 특정 유저에게 발송하기 위한 사용자 그룹을 만드는 기능이에요.\
거래정보, 유저정보, 유저활동, 유저 프로파일의 정보를 기반으로 유저 그룹을 생성할 수 있어요.\
[세그먼트 가이드 바로가기](/segment/console.md)
:::

세그먼트 기능을 통해 **유입 확률이 높은 사용자 그룹을 설정**하고 **푸시 및 광고 노출 대비 높은 전환률**을 만들 수 있어요.\
**앱인토스에서 제공하는 방대한 사용자 데이터**를 기반으로 타겟 고객과 일치하는 사용자 그룹을 생성해보세요.

![](/assets/growth_traffic_1.CVdcg2k0.png)

서울특별시에 거주하는 여성을 타겟으로 푸시/광고를 세팅하고 싶다면, \[유저 정보] 카테고리에서 \[성별]을 선택 후 ‘여성’을 설정하고 \[지역]을 선택 후 ‘서울 특별시’를 설정하면 원하는 타겟 고객을 세그먼트에서 설정할 수 있어요.

![](/assets/growth_traffic_2.DKsSOmqV.png)

### ② 푸시, 알림

::: tip 푸시, 알림
푸시, 알림은 푸시와 알림 두 가지 채널을 통해서 메시지를 보내는 기능이에요.

* 푸시: 푸시는 앱을 열지 않은 상태에서 받는 OS 메시지예요. 앱의 이름과 로고가 함께 노출돼요.
* 알림: 알림은 토스 앱 오른쪽 상단 > 종 아이콘을 누르면 보이는 앱 내 메시지예요.

[푸시, 알림 가이드 바로가기](/push/intro.md)
:::

푸시는 사용자에게 직접적으로 서비스와 관련된 메시지를 보낼 수 있는 기능인 만큼, 신규 사용자부터 기존 사용자까지 효과적으로 유입을 유도할 수 있어요.\
이때 위에서 설정한 세그먼트를 기반으로 푸시, 알림을 설정한다면 보다 효과적인 사용자 유입을 만들 수 있어요.

세그먼트를 이용해서 이렇게 푸시/알림을 세팅해보세요.

**1. 세그먼트 범위를 좁게 설정해요.**

* 세그먼트를 청년희망적금 신청 대상 중 **99년생으로 한정**

> **청년희망적금, 오늘은 `99년생` 신청일이에요**\
> 준비물은 주민등록초본, 토스에서 받을 수 있어요.

**2. 세그먼트 정보를 그대로 언급하여 푸시 멘트를 구성해요.**

* 세그먼트가 토스x 요기패스 가입자인 경우 해당 정보를 그대로 언급

> **요기요 3,000원 쿠폰 도착**\
> `요기패스 쓰는 김토스님`에게 드려요.

**3. 세그먼트 정보를 기반으로 사용자를 칭찬하면서 언급해보세요.**

* 세그먼트가 최근 건강식품 구매한 사용자인 경우

> **건강 챙기는 김토스님**

### ③ 토스 홈 광고

::: tip 토스 홈 광고
토스 홈 광고는 토스 홈 최상단 배너에 광고를 노출할 수 있는 기능이에요.\
캠페인을 손쉽게 진행하고, 성과 데이터를 바로 확인하며 개선할 수 있어요.\
[토스 홈 광고 가이드 바로가기](/intelli/intro.md)
:::

토스 사용자가 **진입 후 제일 먼저 확인하는 최상단 배너**에 광고를 집행해 광범위한 토스 사용자에게 내 서비스를 노출할 수 있어요.\
토스팀에서도 홈 화면 배너를 활용하여 내부 서비스를 효과적으로 알리고 사용자 유입을 만들고 있어요.

![](/assets/growth_traffic_3.BSzEbCya.png)

홈 광고 세팅 시 효과적인 배너 라이팅을 작성하고, 더 많은 사용자를 내 서비스로 유입시켜보세요.

1. 새로 나왔다는 정보 언급 시, 더 높은 노출과 전환률을 만들 수 있어요.

   > 새로 나온 요금제 혜택\
   > 5초 구경하고 포인트 받기

   > 새로 나온 OOO 게임\
   > 게임 시작하기

2. 이벤트가 있다는 사실만 언급해서 가벼운 궁금증을 만들고 보상을 언급하며 사용자의 행동을 이끌 수 있어요.

   > 5원 받는 토스페이 이벤트\
   > 확인하기

3. 내 서비스가 덜 유명하더라도 도전 욕구를 자극하면, 사용자에게 매력적으로 소구할 수 있어요.

   > OOO님의 실력을 보여주세요\
   > 한 판 해보기

   > OOO님의 실력을 보여주세요\
   > 첫 기록 세우기

4. 사용자가 취해야 할 행동을 자세히 알려줬을 때 사용자의 유입을 효과적으로 이끌 수 있어요.

   \[기존]

   > 어질러진 아이 물건을 정리해요\
   > 퍼즐 게임 한 판 해보기

   \[행동 자세히 쓰기]

   > 물건이 뒤죽박죽 섞여 있어요\
   > 짝맞춰 정리하기

5. 전문적인 용어가 등장할수록 진입장벽이 높아져서 CTR이 낮아져요. 따라서 최대한 쉽고 직관적인 언어를 사용해주세요.
   * 시뮬레이션 → OO 키우기, OO 운영하기
   * 방치형 → 켜놓기만 해도 레벨이 올라요, 손 안 대도, 일하는 중에도, 보상이 저절로 쌓여요

### ④ 프로모션 (토스 포인트)

::: tip 프로모션 (토스 포인트)
앱인토스의 프로모션은 사용자가 특정 행동을 달성 시 토스 포인트를 지급하는 이벤트예요.\
선충전한 예산을 기반으로 프로모션을 진행할 수 있으며 콘솔에서 혜택탭 노출 여부를 설정할 수 있어요.\
[프로모션 가이드 바로가기](/promotion/intro.md)
:::

프로모션은 토스 포인트라는 보상을 지급하는 이벤트임에 따라 신규 사용자를 유입하고 많은 사람들에게 내 서비스를 알리는 데 효과적인 기능이에요.\
또한, 프로모션 노출 설정 시 토스의 **혜택탭에 노출**되며 **광범위한 토스 사용자를 내 서비스로 유입**시킬 수 있어요.\
이때 혜택탭은 **미니앱 진입 경로 중 가장 많은 사용자가 유입되는 지면**임에 따라 많은 사용자들에게 서비스를 노출시킬 수 있어요.

혜택탭을 통해 서비스에 방문하는 신규 사용자에게 서비스의 핵심 기능을 사용하도록 만들어 보세요.

![](/assets/growth_traffic_4.D5Q5uGXr.png)

프로모션 설정 시 **유도하고자 하는 행동을 직관적이고 간단하게 표현**하면, 사용자가 무엇을 해야 하는지 **명확히 이해**하고 **더 쉽게 달성**하도록 할 수 있어요.

\[기존]

> 리뷰 둘러보기\
> **10원 받기**

\[행동 자세히 쓰기]

> 리뷰 3개 이상 확인하기\
> **10원 받기**

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/분석/Analytics.md
---

# 사용자 행동 기록하기

## `Analytics`

`Analytics` 는 사용자의 행동을 기록하고 분석하기 위한 객체예요. 이 객체를 사용해서 화면 진입, 버튼 클릭, 컴포넌트 노출 등의 이벤트를 자동으로 수집하고 기록할 수 있어요. 서비스 개선이나 사용자 흐름 분석에 필요한 데이터를 수집할 때 사용해요.

## 시그니처

```typescript
Analytics: {
    readonly init: typeof init;
    readonly Screen: typeof LoggingScreen;
    readonly Press: import("react").ForwardRefExoticComponent<import(".").LoggingPressProps & import("react").RefAttributes<unknown>>;
    readonly Impression: typeof LoggingImpression;
    readonly Area: typeof LoggingArea;
}
```

### 프로퍼티

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/start/preload.md'
---
# 사전 다운로드 가이드

앱인토스 Unity 게임에서 사전 다운로드 기능을 구현하여 게임 플레이 중 끊김 없는 경험을 제공하는 방법을 다뤄요.

***

## 1. 사전 다운로드 시스템 개요

### 사전 다운로드 전략

```
📥 사전 다운로드 아키텍처
├── 필수 콘텐츠 (게임 시작 전 다운로드)
│   ├── 핵심 게임 로직
│   ├── 기본 UI 리소스
│   ├── 첫 레벨 에셋
│   └── 필수 오디오
├── 우선순위 콘텐츠 (백그라운드 다운로드)
│   ├── 다음 레벨 에셋
│   ├── 캐릭터 스킨
│   ├── 추가 음악
│   └── 이펙트 에셋
├── 선택적 콘텐츠 (필요시 다운로드)
│   ├── 고해상도 텍스처
│   ├── 보너스 콘텐츠
│   ├── 계절 이벤트 에셋
│   └── 언어팩
└── 예측적 콘텐츠 (사용자 패턴 기반)
    ├── 자주 플레이하는 레벨
    ├── 선호 캐릭터 관련
    ├── 개인화 콘텐츠
    └── 추천 에셋
```

### 사전 다운로드 매니저

```c#
using UnityEngine;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Linq;

public class AppsInTossPreloadManager : MonoBehaviour
{
    public static AppsInTossPreloadManager Instance { get; private set; }
    
    [System.Serializable]
    public class PreloadItem
    {
        [Header("기본 정보")]
        public string itemId;
        public string itemName;
        public string description;
        public float sizeMB;
        public string version = "1.0.0";
        
        [Header("다운로드 설정")]
        public PreloadPriority priority;
        public PreloadTrigger downloadTrigger;
        public string[] dependencies;
        public string remoteUrl;
        public string localPath;
        
        [Header("조건 설정")]
        public bool requiresWiFi = false;
        public bool downloadOnlyWhenIdle = false;
        public int minimumBatteryLevel = 20;
        public long maxStorageUsageMB = 500;
        
        [Header("게임 로직")]
        public string[] requiredForScenes;
        public string[] requiredForFeatures;
        public bool isUserGenerated = false;
        public System.DateTime expiryDate;
    }
    
    public enum PreloadPriority
    {
        Critical = 0,    // 게임 진행에 필수
        High = 1,        // 사용자 경험 향상에 중요
        Medium = 2,      // 부가 기능
        Low = 3,         // 선택적 콘텐츠
        OnDemand = 4     // 요청시에만 다운로드
    }
    
    public enum PreloadTrigger
    {
        Immediate,       // 즉시 다운로드
        OnGameStart,     // 게임 시작시
        OnSceneLoad,     // 특정 씬 로드시
        OnFeatureAccess, // 기능 접근시
        OnUserRequest,   // 사용자 요청시
        OnWiFiAvailable, // WiFi 연결시
        OnIdle,          // 유휴 시간에
        OnBatteryOK      // 배터리 충분시
    }
    
    [Header("사전 다운로드 설정")]
    public PreloadItem[] preloadItems;
    
    [Header("네트워크 설정")]
    public int maxConcurrentDownloads = 2;
    public float downloadTimeoutSeconds = 30f;
    public bool enableBackgroundDownload = true;
    public bool enablePredictiveDownload = true;
    
    [Header("저장소 관리")]
    public long maxTotalCacheSizeMB = 1000;
    public bool enableAutomaticCleanup = true;
    public int keepRecentDays = 30;
    
    // 내부 상태
    private Dictionary<string, PreloadItem> itemMap = new Dictionary<string, PreloadItem>();
    private HashSet<string> downloadedItems = new HashSet<string>();
    private HashSet<string> downloadingItems = new HashSet<string>();
    private Queue<PreloadItem> downloadQueue = new Queue<PreloadItem>();
    private Dictionary<string, float> downloadProgress = new Dictionary<string, float>();
    private int activeDownloads = 0;
    private bool isInitialized = false;
    
    // 사용자 패턴 분석
    private Dictionary<string, int> usageFrequency = new Dictionary<string, int>();
    private Dictionary<string, System.DateTime> lastUsedTime = new Dictionary<string, System.DateTime>();
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializePreloadSystem();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializePreloadSystem()
    {
        // 아이템 맵 생성
        foreach (var item in preloadItems)
        {
            itemMap[item.itemId] = item;
        }
        
        // 로컬 캐시 상태 확인
        LoadCacheStatus();
        
        // 사용 패턴 데이터 로드
        LoadUsagePatterns();
        
        // 시스템 상태 모니터링 시작
        StartCoroutine(MonitorSystemConditions());
        
        // 초기 다운로드 큐 설정
        SetupInitialDownloadQueue();
        
        isInitialized = true;
        Debug.Log("AppsInToss 사전 다운로드 시스템 초기화 완료");
    }
    
    void LoadCacheStatus()
    {
        string cacheStatusPath = Path.Combine(Application.persistentDataPath, "preload_cache_status.json");
        
        if (File.Exists(cacheStatusPath))
        {
            try
            {
                string json = File.ReadAllText(cacheStatusPath);
                var cacheStatus = JsonUtility.FromJson<CacheStatus>(json);
                
                downloadedItems = new HashSet<string>(cacheStatus.downloadedItems);
                
                Debug.Log($"캐시 상태 로드 완료: {downloadedItems.Count}개 아이템");
            }
            catch (System.Exception e)
            {
                Debug.LogError($"캐시 상태 로드 실패: {e.Message}");
            }
        }
    }
    
    void SaveCacheStatus()
    {
        string cacheStatusPath = Path.Combine(Application.persistentDataPath, "preload_cache_status.json");
        
        var cacheStatus = new CacheStatus
        {
            downloadedItems = downloadedItems.ToArray(),
            lastUpdateTime = System.DateTime.UtcNow.ToString("o")
        };
        
        try
        {
            string json = JsonUtility.ToJson(cacheStatus, true);
            File.WriteAllText(cacheStatusPath, json);
        }
        catch (System.Exception e)
        {
            Debug.LogError($"캐시 상태 저장 실패: {e.Message}");
        }
    }
    
    void LoadUsagePatterns()
    {
        string patternsPath = Path.Combine(Application.persistentDataPath, "usage_patterns.json");
        
        if (File.Exists(patternsPath))
        {
            try
            {
                string json = File.ReadAllText(patternsPath);
                var patterns = JsonUtility.FromJson<UsagePatterns>(json);
                
                foreach (var item in patterns.items)
                {
                    usageFrequency[item.itemId] = item.frequency;
                    if (System.DateTime.TryParse(item.lastUsed, out System.DateTime lastUsed))
                    {
                        lastUsedTime[item.itemId] = lastUsed;
                    }
                }
                
                Debug.Log($"사용 패턴 로드 완료: {usageFrequency.Count}개 항목");
            }
            catch (System.Exception e)
            {
                Debug.LogError($"사용 패턴 로드 실패: {e.Message}");
            }
        }
    }
    
    void SaveUsagePatterns()
    {
        string patternsPath = Path.Combine(Application.persistentDataPath, "usage_patterns.json");
        
        var patterns = new UsagePatterns();
        patterns.items = new List<UsagePatternItem>();
        
        foreach (var kvp in usageFrequency)
        {
            var item = new UsagePatternItem
            {
                itemId = kvp.Key,
                frequency = kvp.Value,
                lastUsed = lastUsedTime.ContainsKey(kvp.Key) ? 
                          lastUsedTime[kvp.Key].ToString("o") : 
                          System.DateTime.UtcNow.ToString("o")
            };
            patterns.items.Add(item);
        }
        
        try
        {
            string json = JsonUtility.ToJson(patterns, true);
            File.WriteAllText(patternsPath, json);
        }
        catch (System.Exception e)
        {
            Debug.LogError($"사용 패턴 저장 실패: {e.Message}");
        }
    }
    
    IEnumerator MonitorSystemConditions()
    {
        while (true)
        {
            // 네트워크 상태 확인
            bool isWiFiAvailable = Application.internetReachability == NetworkReachability.ReachableViaLocalAreaNetwork;
            
            // 배터리 상태 확인 (모바일 플랫폼에서만)
            float batteryLevel = SystemInfo.batteryLevel * 100f;
            
            // 저장 공간 확인
            long availableStorage = GetAvailableStorageSpace();
            
            // 시스템 조건에 따른 다운로드 제어
            UpdateDownloadBehavior(isWiFiAvailable, batteryLevel, availableStorage);
            
            // 다운로드 큐 처리
            ProcessDownloadQueue();
            
            yield return new WaitForSeconds(5f);
        }
    }
    
    void UpdateDownloadBehavior(bool isWiFiAvailable, float batteryLevel, long availableStorage)
    {
        // WiFi 전용 아이템들 처리
        if (isWiFiAvailable)
        {
            var wifiOnlyItems = preloadItems.Where(item => 
                item.requiresWiFi && 
                !downloadedItems.Contains(item.itemId) && 
                !downloadingItems.Contains(item.itemId)
            ).ToArray();
            
            foreach (var item in wifiOnlyItems)
            {
                if (ShouldDownloadItem(item, batteryLevel, availableStorage))
                {
                    QueueItemForDownload(item);
                }
            }
        }
        
        // 배터리 조건 확인
        if (batteryLevel < 20f)
        {
            // 배터리가 부족하면 중요하지 않은 다운로드 일시 정지
            PauseNonCriticalDownloads();
        }
        
        // 저장 공간 부족시 정리
        if (availableStorage < 100 * 1024 * 1024) // 100MB 미만
        {
            StartCoroutine(CleanupOldCache());
        }
    }
    
    bool ShouldDownloadItem(PreloadItem item, float batteryLevel, long availableStorage)
    {
        // 배터리 레벨 체크
        if (batteryLevel < item.minimumBatteryLevel)
        {
            return false;
        }
        
        // 저장 공간 체크
        if (availableStorage < item.sizeMB * 1024 * 1024)
        {
            return false;
        }
        
        // 트리거 조건 체크
        if (item.downloadTrigger == PreloadTrigger.OnWiFiAvailable && 
            Application.internetReachability != NetworkReachability.ReachableViaLocalAreaNetwork)
        {
            return false;
        }
        
        // 유휴 시간 체크
        if (item.downloadOnlyWhenIdle && !IsPlayerIdle())
        {
            return false;
        }
        
        return true;
    }
    
    void SetupInitialDownloadQueue()
    {
        // 우선순위별로 정렬
        var sortedItems = preloadItems
            .Where(item => item.downloadTrigger == PreloadTrigger.Immediate || 
                          item.downloadTrigger == PreloadTrigger.OnGameStart)
            .OrderBy(item => item.priority)
            .ThenByDescending(item => GetItemPredictionScore(item));
        
        foreach (var item in sortedItems)
        {
            if (!downloadedItems.Contains(item.itemId))
            {
                QueueItemForDownload(item);
            }
        }
        
        Debug.Log($"초기 다운로드 큐 설정 완료: {downloadQueue.Count}개 아이템");
    }
    
    float GetItemPredictionScore(PreloadItem item)
    {
        float score = 0f;
        
        // 사용 빈도 점수
        if (usageFrequency.ContainsKey(item.itemId))
        {
            score += usageFrequency[item.itemId] * 10f;
        }
        
        // 최근 사용 점수
        if (lastUsedTime.ContainsKey(item.itemId))
        {
            var daysSinceLastUse = (System.DateTime.UtcNow - lastUsedTime[item.itemId]).TotalDays;
            score += Mathf.Max(0, 30f - (float)daysSinceLastUse);
        }
        
        // 크기 점수 (작을수록 높은 점수)
        score += Mathf.Max(0, 50f - item.sizeMB);
        
        return score;
    }
    
    void ProcessDownloadQueue()
    {
        while (downloadQueue.Count > 0 && activeDownloads < maxConcurrentDownloads)
        {
            var nextItem = downloadQueue.Dequeue();
            
            if (!downloadedItems.Contains(nextItem.itemId) && 
                !downloadingItems.Contains(nextItem.itemId))
            {
                StartCoroutine(DownloadItem(nextItem));
            }
        }
    }
    
    IEnumerator DownloadItem(PreloadItem item)
    {
        downloadingItems.Add(item.itemId);
        activeDownloads++;
        downloadProgress[item.itemId] = 0f;
        
        Debug.Log($"다운로드 시작: {item.itemName} ({item.sizeMB:F1}MB)");
        float startTime = Time.realtimeSinceStartup;
        
        // 의존성 체크 및 다운로드
        yield return StartCoroutine(EnsureDependencies(item));
        
        // 실제 파일 다운로드
        string downloadUrl = item.remoteUrl;
        string localPath = GetLocalPath(item);
        
        using (var www = new WWW(downloadUrl))
        {
            float timeoutTime = Time.realtimeSinceStartup + downloadTimeoutSeconds;
            
            while (!www.isDone && Time.realtimeSinceStartup < timeoutTime)
            {
                downloadProgress[item.itemId] = www.progress;
                
                // 진행률 이벤트 발송
                SendDownloadProgressEvent(item.itemId, www.progress);
                
                yield return null;
            }
            
            if (www.isDone && string.IsNullOrEmpty(www.error))
            {
                // 파일 저장
                Directory.CreateDirectory(Path.GetDirectoryName(localPath));
                File.WriteAllBytes(localPath, www.bytes);
                
                // 성공 처리
                OnDownloadSuccess(item, Time.realtimeSinceStartup - startTime);
            }
            else
            {
                // 실패 처리
                OnDownloadFailed(item, www.error);
            }
        }
        
        downloadingItems.Remove(item.itemId);
        activeDownloads--;
        downloadProgress.Remove(item.itemId);
    }
    
    IEnumerator EnsureDependencies(PreloadItem item)
    {
        foreach (var dependencyId in item.dependencies)
        {
            if (!downloadedItems.Contains(dependencyId))
            {
                if (itemMap.ContainsKey(dependencyId))
                {
                    var dependency = itemMap[dependencyId];
                    yield return StartCoroutine(DownloadItem(dependency));
                }
            }
        }
    }
    
    void OnDownloadSuccess(PreloadItem item, float downloadTime)
    {
        downloadedItems.Add(item.itemId);
        SaveCacheStatus();
        
        Debug.Log($"다운로드 완료: {item.itemName} ({downloadTime:F2}초)");
        
        // 성공 분석 데이터 전송
        SendDownloadAnalytics(item, true, downloadTime, null);
        
        // 완료 이벤트 발송
        AppsInToss.SendEvent("preload_item_downloaded", new Dictionary<string, object>
        {
            {"item_id", item.itemId},
            {"item_name", item.itemName},
            {"size_mb", item.sizeMB},
            {"download_time", downloadTime}
        });
    }
    
    void OnDownloadFailed(PreloadItem item, string error)
    {
        Debug.LogError($"다운로드 실패: {item.itemName} - {error}");
        
        // 실패 분석 데이터 전송
        SendDownloadAnalytics(item, false, 0f, error);
        
        // 재시도 로직 (낮은 우선순위 아이템만)
        if (item.priority >= PreloadPriority.Medium)
        {
            StartCoroutine(RetryDownloadAfterDelay(item, 10f));
        }
    }
    
    IEnumerator RetryDownloadAfterDelay(PreloadItem item, float delay)
    {
        yield return new WaitForSeconds(delay);
        
        if (!downloadedItems.Contains(item.itemId))
        {
            QueueItemForDownload(item);
            Debug.Log($"다운로드 재시도 예약: {item.itemName}");
        }
    }
    
    void SendDownloadProgressEvent(string itemId, float progress)
    {
        AppsInToss.SendEvent("preload_progress", new Dictionary<string, object>
        {
            {"item_id", itemId},
            {"progress", progress}
        });
    }
    
    void SendDownloadAnalytics(PreloadItem item, bool success, float downloadTime, string error)
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"item_id", item.itemId},
            {"item_name", item.itemName},
            {"size_mb", item.sizeMB},
            {"priority", item.priority.ToString()},
            {"success", success},
            {"download_time", downloadTime},
            {"error_message", error ?? ""},
            {"network_type", Application.internetReachability.ToString()},
            {"device_model", SystemInfo.deviceModel},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("preload_download", analyticsData);
    }
    
    string GetLocalPath(PreloadItem item)
    {
        if (!string.IsNullOrEmpty(item.localPath))
        {
            return Path.Combine(Application.persistentDataPath, item.localPath);
        }
        
        return Path.Combine(Application.persistentDataPath, "PreloadCache", item.itemId);
    }
    
    long GetAvailableStorageSpace()
    {
        // 플랫폼별 저장 공간 확인 로직
        // 여기서는 간단한 추정값 반환
        return 1024 * 1024 * 1024; // 1GB
    }
    
    bool IsPlayerIdle()
    {
        // 플레이어 유휴 상태 확인 로직
        return Time.realtimeSinceStartup - Time.time > 30f;
    }
    
    void PauseNonCriticalDownloads()
    {
        // 현재 진행중인 중요하지 않은 다운로드들을 일시 정지
        Debug.Log("배터리 부족으로 인한 비중요 다운로드 일시 정지");
    }
    
    IEnumerator CleanupOldCache()
    {
        Debug.Log("저장 공간 부족으로 인한 캐시 정리 시작");
        
        var cacheDir = Path.Combine(Application.persistentDataPath, "PreloadCache");
        if (Directory.Exists(cacheDir))
        {
            var files = Directory.GetFiles(cacheDir, "*", SearchOption.AllDirectories);
            var fileInfos = files.Select(f => new FileInfo(f)).ToArray();
            
            // 오래된 파일부터 정렬
            System.Array.Sort(fileInfos, (a, b) => a.LastAccessTime.CompareTo(b.LastAccessTime));
            
            long freedSpace = 0;
            long targetFreeSpace = 200 * 1024 * 1024; // 200MB
            
            foreach (var fileInfo in fileInfos)
            {
                if (freedSpace >= targetFreeSpace) break;
                
                try
                {
                    freedSpace += fileInfo.Length;
                    File.Delete(fileInfo.FullName);
                    
                    // 해당 아이템을 다운로드 목록에서 제거
                    string itemId = Path.GetFileNameWithoutExtension(fileInfo.Name);
                    downloadedItems.Remove(itemId);
                    
                    Debug.Log($"캐시 파일 삭제: {fileInfo.Name}");
                }
                catch (System.Exception e)
                {
                    Debug.LogError($"캐시 파일 삭제 실패: {e.Message}");
                }
                
                yield return null;
            }
            
            SaveCacheStatus();
            Debug.Log($"캐시 정리 완료: {freedSpace / (1024 * 1024)}MB 확보");
        }
    }
    
    // 공개 API
    public void QueueItemForDownload(PreloadItem item)
    {
        if (!downloadedItems.Contains(item.itemId) && 
            !downloadingItems.Contains(item.itemId))
        {
            downloadQueue.Enqueue(item);
            Debug.Log($"다운로드 큐에 추가: {item.itemName}");
        }
    }
    
    public void QueueItemForDownload(string itemId)
    {
        if (itemMap.ContainsKey(itemId))
        {
            QueueItemForDownload(itemMap[itemId]);
        }
    }
    
    public bool IsItemDownloaded(string itemId)
    {
        return downloadedItems.Contains(itemId);
    }
    
    public float GetDownloadProgress(string itemId)
    {
        return downloadProgress.ContainsKey(itemId) ? downloadProgress[itemId] : 0f;
    }
    
    public bool IsItemDownloading(string itemId)
    {
        return downloadingItems.Contains(itemId);
    }
    
    public void RecordItemUsage(string itemId)
    {
        if (usageFrequency.ContainsKey(itemId))
        {
            usageFrequency[itemId]++;
        }
        else
        {
            usageFrequency[itemId] = 1;
        }
        
        lastUsedTime[itemId] = System.DateTime.UtcNow;
        
        // 주기적으로 패턴 저장
        if (usageFrequency[itemId] % 10 == 0)
        {
            SaveUsagePatterns();
        }
    }
    
    public long GetTotalCacheSize()
    {
        var cacheDir = Path.Combine(Application.persistentDataPath, "PreloadCache");
        if (!Directory.Exists(cacheDir))
        {
            return 0;
        }
        
        long totalSize = 0;
        var files = Directory.GetFiles(cacheDir, "*", SearchOption.AllDirectories);
        
        foreach (var file in files)
        {
            totalSize += new FileInfo(file).Length;
        }
        
        return totalSize;
    }
    
    public PreloadItem[] GetQueuedItems()
    {
        return downloadQueue.ToArray();
    }
    
    public string[] GetDownloadedItemIds()
    {
        return downloadedItems.ToArray();
    }
    
    void OnApplicationPause(bool pauseStatus)
    {
        if (pauseStatus)
        {
            // 앱 일시정지시 패턴 데이터 저장
            SaveUsagePatterns();
        }
    }
    
    void OnDestroy()
    {
        SaveCacheStatus();
        SaveUsagePatterns();
    }
}

// 데이터 클래스들
[System.Serializable]
public class CacheStatus
{
    public string[] downloadedItems;
    public string lastUpdateTime;
}

[System.Serializable]
public class UsagePatterns
{
    public List<UsagePatternItem> items;
}

[System.Serializable]
public class UsagePatternItem
{
    public string itemId;
    public int frequency;
    public string lastUsed;
}
```

***

## 2. 사용자 인터페이스

### 다운로드 관리 UI

```c#
using UnityEngine;
using UnityEngine.UI;
using TMPro;
using System.Collections.Generic;
using System.Linq;

public class PreloadManagerUI : MonoBehaviour
{
    [Header("UI 컴포넌트")]
    public GameObject downloadItemPrefab;
    public Transform downloadItemContainer;
    public Button pauseAllButton;
    public Button resumeAllButton;
    public Button clearCacheButton;
    public TextMeshProUGUI totalSizeText;
    public TextMeshProUGUI availableSpaceText;
    public Slider totalProgressSlider;
    
    [Header("설정 UI")]
    public Toggle wifiOnlyToggle;
    public Toggle backgroundDownloadToggle;
    public Slider maxCacheSizeSlider;
    public TextMeshProUGUI maxCacheSizeLabel;
    
    private Dictionary<string, GameObject> downloadItemUIs = new Dictionary<string, GameObject>();
    private bool isPaused = false;
    
    void Start()
    {
        SetupUI();
        RegisterEventListeners();
        UpdateUI();
    }
    
    void SetupUI()
    {
        // 버튼 리스너 등록
        pauseAllButton.onClick.AddListener(PauseAllDownloads);
        resumeAllButton.onClick.AddListener(ResumeAllDownloads);
        clearCacheButton.onClick.AddListener(ClearCache);
        
        // 토글 리스너 등록
        wifiOnlyToggle.onValueChanged.AddListener(OnWiFiOnlyChanged);
        backgroundDownloadToggle.onValueChanged.AddListener(OnBackgroundDownloadChanged);
        
        // 슬라이더 리스너 등록
        maxCacheSizeSlider.onValueChanged.AddListener(OnMaxCacheSizeChanged);
        
        // 초기 설정 로드
        LoadUserPreferences();
    }
    
    void RegisterEventListeners()
    {
        AppsInToss.OnEvent += HandlePreloadEvent;
    }
    
    void HandlePreloadEvent(string eventName, Dictionary<string, object> data)
    {
        switch (eventName)
        {
            case "preload_item_downloaded":
                string itemId = data["item_id"] as string;
                UpdateDownloadItemUI(itemId, 1f, "완료");
                break;
                
            case "preload_progress":
                itemId = data["item_id"] as string;
                float progress = (float)data["progress"];
                UpdateDownloadItemUI(itemId, progress, $"{progress * 100f:F0}%");
                break;
        }
        
        UpdateUI();
    }
    
    void UpdateUI()
    {
        if (AppsInTossPreloadManager.Instance == null) return;
        
        // 전체 캐시 크기 표시
        long totalCacheSize = AppsInTossPreloadManager.Instance.GetTotalCacheSize();
        totalSizeText.text = $"사용 중: {FormatFileSize(totalCacheSize)}";
        
        // 사용 가능한 공간 표시 (추정값)
        availableSpaceText.text = "사용 가능: ~1.2GB";
        
        // 전체 진행률 계산
        UpdateTotalProgress();
        
        // 개별 다운로드 아이템 UI 업데이트
        UpdateDownloadItemsUI();
    }
    
    void UpdateTotalProgress()
    {
        var queuedItems = AppsInTossPreloadManager.Instance.GetQueuedItems();
        var downloadedItems = AppsInTossPreloadManager.Instance.GetDownloadedItemIds();
        
        if (queuedItems.Length == 0)
        {
            totalProgressSlider.value = 1f;
            return;
        }
        
        float totalItems = queuedItems.Length + downloadedItems.Length;
        float completedItems = downloadedItems.Length;
        
        // 현재 다운로드 중인 아이템들의 부분 진행률 추가
        foreach (var item in queuedItems)
        {
            if (AppsInTossPreloadManager.Instance.IsItemDownloading(item.itemId))
            {
                float itemProgress = AppsInTossPreloadManager.Instance.GetDownloadProgress(item.itemId);
                completedItems += itemProgress;
            }
        }
        
        totalProgressSlider.value = totalItems > 0 ? completedItems / totalItems : 1f;
    }
    
    void UpdateDownloadItemsUI()
    {
        var queuedItems = AppsInTossPreloadManager.Instance.GetQueuedItems();
        var downloadedItems = AppsInTossPreloadManager.Instance.GetDownloadedItemIds();
        
        // 큐에 있는 아이템들 UI 생성/업데이트
        foreach (var item in queuedItems)
        {
            if (!downloadItemUIs.ContainsKey(item.itemId))
            {
                CreateDownloadItemUI(item);
            }
            
            bool isDownloading = AppsInTossPreloadManager.Instance.IsItemDownloading(item.itemId);
            float progress = isDownloading ? 
                AppsInTossPreloadManager.Instance.GetDownloadProgress(item.itemId) : 0f;
            
            string status = isDownloading ? "다운로드 중" : "대기 중";
            UpdateDownloadItemUI(item.itemId, progress, status);
        }
        
        // 완료된 아이템들 처리
        foreach (var itemId in downloadedItems)
        {
            if (downloadItemUIs.ContainsKey(itemId))
            {
                UpdateDownloadItemUI(itemId, 1f, "완료");
            }
        }
    }
    
    void CreateDownloadItemUI(AppsInTossPreloadManager.PreloadItem item)
    {
        var itemUI = Instantiate(downloadItemPrefab, downloadItemContainer);
        downloadItemUIs[item.itemId] = itemUI;
        
        // UI 컴포넌트 설정
        var nameText = itemUI.transform.Find("NameText").GetComponent<TextMeshProUGUI>();
        var sizeText = itemUI.transform.Find("SizeText").GetComponent<TextMeshProUGUI>();
        var progressSlider = itemUI.transform.Find("ProgressSlider").GetComponent<Slider>();
        var statusText = itemUI.transform.Find("StatusText").GetComponent<TextMeshProUGUI>();
        var cancelButton = itemUI.transform.Find("CancelButton").GetComponent<Button>();
        
        nameText.text = item.itemName;
        sizeText.text = FormatFileSize((long)(item.sizeMB * 1024 * 1024));
        progressSlider.value = 0f;
        statusText.text = "대기 중";
        
        // 취소 버튼 이벤트
        cancelButton.onClick.AddListener(() => CancelDownload(item.itemId));
        
        // 우선순위에 따른 색상 설정
        var priorityIcon = itemUI.transform.Find("PriorityIcon").GetComponent<Image>();
        priorityIcon.color = GetPriorityColor(item.priority);
    }
    
    void UpdateDownloadItemUI(string itemId, float progress, string status)
    {
        if (!downloadItemUIs.ContainsKey(itemId)) return;
        
        var itemUI = downloadItemUIs[itemId];
        var progressSlider = itemUI.transform.Find("ProgressSlider").GetComponent<Slider>();
        var statusText = itemUI.transform.Find("StatusText").GetComponent<TextMeshProUGUI>();
        
        progressSlider.value = progress;
        statusText.text = status;
        
        // 완료된 아이템은 일정 시간 후 제거
        if (progress >= 1f)
        {
            StartCoroutine(RemoveCompletedItemUI(itemId, 3f));
        }
    }
    
    System.Collections.IEnumerator RemoveCompletedItemUI(string itemId, float delay)
    {
        yield return new WaitForSeconds(delay);
        
        if (downloadItemUIs.ContainsKey(itemId))
        {
            Destroy(downloadItemUIs[itemId]);
            downloadItemUIs.Remove(itemId);
        }
    }
    
    Color GetPriorityColor(AppsInTossPreloadManager.PreloadPriority priority)
    {
        switch (priority)
        {
            case AppsInTossPreloadManager.PreloadPriority.Critical:
                return Color.red;
            case AppsInTossPreloadManager.PreloadPriority.High:
                return Color.yellow;
            case AppsInTossPreloadManager.PreloadPriority.Medium:
                return Color.green;
            case AppsInTossPreloadManager.PreloadPriority.Low:
                return Color.gray;
            default:
                return Color.white;
        }
    }
    
    string FormatFileSize(long bytes)
    {
        string[] sizes = { "B", "KB", "MB", "GB" };
        double len = bytes;
        int order = 0;
        
        while (len >= 1024 && order < sizes.Length - 1)
        {
            order++;
            len = len / 1024;
        }
        
        return $"{len:0.##} {sizes[order]}";
    }
    
    void PauseAllDownloads()
    {
        isPaused = true;
        // 다운로드 일시정지 로직 구현
        Debug.Log("모든 다운로드 일시정지");
    }
    
    void ResumeAllDownloads()
    {
        isPaused = false;
        // 다운로드 재개 로직 구현
        Debug.Log("모든 다운로드 재개");
    }
    
    void ClearCache()
    {
        // 캐시 정리 확인 다이얼로그 표시
        ShowClearCacheDialog();
    }
    
    void ShowClearCacheDialog()
    {
        // 간단한 확인 다이얼로그
        bool confirmed = true; // 실제로는 다이얼로그 결과
        
        if (confirmed)
        {
            // 캐시 정리 실행
            Debug.Log("캐시 정리 시작");
        }
    }
    
    void CancelDownload(string itemId)
    {
        // 다운로드 취소 로직
        if (downloadItemUIs.ContainsKey(itemId))
        {
            Destroy(downloadItemUIs[itemId]);
            downloadItemUIs.Remove(itemId);
        }
        
        Debug.Log($"다운로드 취소: {itemId}");
    }
    
    void OnWiFiOnlyChanged(bool value)
    {
        // WiFi 전용 설정 변경
        SaveUserPreference("wifi_only", value);
    }
    
    void OnBackgroundDownloadChanged(bool value)
    {
        // 백그라운드 다운로드 설정 변경
        SaveUserPreference("background_download", value);
    }
    
    void OnMaxCacheSizeChanged(float value)
    {
        // 최대 캐시 크기 설정 변경
        long maxSizeMB = (long)(value * 1000);
        maxCacheSizeLabel.text = $"최대 캐시 크기: {maxSizeMB}MB";
        SaveUserPreference("max_cache_size_mb", maxSizeMB);
    }
    
    void LoadUserPreferences()
    {
        wifiOnlyToggle.isOn = GetUserPreference("wifi_only", false);
        backgroundDownloadToggle.isOn = GetUserPreference("background_download", true);
        
        long maxCacheSizeMB = GetUserPreference("max_cache_size_mb", 500L);
        maxCacheSizeSlider.value = maxCacheSizeMB / 1000f;
        maxCacheSizeLabel.text = $"최대 캐시 크기: {maxCacheSizeMB}MB";
    }
    
    void SaveUserPreference(string key, object value)
    {
        // 사용자 설정 저장
        PlayerPrefs.SetString($"preload_{key}", value.ToString());
        PlayerPrefs.Save();
    }
    
    T GetUserPreference<T>(string key, T defaultValue)
    {
        // 사용자 설정 로드
        string prefKey = $"preload_{key}";
        if (PlayerPrefs.HasKey(prefKey))
        {
            string value = PlayerPrefs.GetString(prefKey);
            try
            {
                return (T)System.Convert.ChangeType(value, typeof(T));
            }
            catch
            {
                return defaultValue;
            }
        }
        return defaultValue;
    }
    
    void Update()
    {
        // UI 주기적 업데이트
        if (Time.frameCount % 60 == 0) // 1초마다
        {
            UpdateUI();
        }
    }
    
    void OnDestroy()
    {
        AppsInToss.OnEvent -= HandlePreloadEvent;
    }
}
```

사전 다운로드를 통해 게임 플레이 중 끊김을 최소화하되, 사용자의 데이터 요금과 배터리, 저장 공간을 고려한 스마트한 다운로드 전략을 구현하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인앱
  결제/completeProductGrant.md
---

# 상품 지급하기

## `completeProductGrant`

`completeProductGrant` 함수는 **대기 중인 주문의 상품 지급을 완료 처리하는 함수**예요.\
사용자에게 상품을 지급하고 `completeProductGrant` 함수를 호출하여 지급 상태를 완료로 변경하세요.

앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.

## 시그니처

```typescript
function completeProductGrant(params: {
  params: {
    orderId: string;
  };
}): Promise<boolean | undefined>;
```

### 파라미터

### 반환값

## 예제

::: code-group

```js [js]
import { IAP } from '@apps-in-toss/web-framework';

async function handleGrantProduct(orderId) {
  try {
    await IAP.completeProductGrant({ params: { orderId } });
    console.log('상품 지급 완료 처리 성공');
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [ts]
 import { IAP } from '@apps-in-toss/framework';
 
 async function handleGrantProduct(orderId: string) {
   try {
     await IAP.completeProductGrant({ params: { orderId } });
   } catch (error) {
     console.error(error);
   }
 }
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인앱
  결제/getProductItemList.md
---

# 상품목록 가져오기

## `getProductItemList`

`getProductItemList` 는 인앱 결제로 구매할 수 있는 상품 목록을 담은 함수예요. 상품 목록을 화면에 표시할 때 사용해요.

## 시그니처

```typescript
function getProductItemList(): Promise<{ products: IapProductListItem[] } | undefined>;
```

### 반환값

### 프로퍼티

```typescript
interface IapProductListItem {
  sku: string;
  displayAmount: string;
  displayName: string;
  iconUrl: string;
  description: string;
}
```

## 예제

### 구매 가능한 인앱결제 상품목록 가져오기

::: code-group

```js [js]
import { IAP } from "@apps-in-toss/web-framework";

async function handleGetProductItemList() {
  const response = await IAP.getProductItemList();
  
  return response?.products ?? [];
}
```

```tsx [React]
import { IAP, IapProductListItem } from "@apps-in-toss/web-framework";
import { Button, List, ListRow } from "@toss/tds-mobile";
import { useEffect, useState, useCallback } from "react";

function IapProductList() {
  const [products, setProducts] = useState<IapProductListItem[]>([]);

  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
      },
      onEvent: (event) => {
        console.log(event);

        if(event.type === 'success') {
          cleanup();
        }
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  useEffect(() => {
    async function fetchProducts() {
      try {
        const response = await IAP.getProductItemList();
        setProducts(response?.products ?? []);
      } catch (error) {
        console.error("상품 목록을 가져오는 데 실패했어요:", error);
      }
    }

    fetchProducts();
  }, []);

  return (
    <List>
      {products.map((product) => (
        <ListRow
          key={product.sku}
          left={<ListRow.Image type="square" src={product.iconUrl} />}
          contents={
            <ListRow.Texts
              type="3RowTypeA"
              top={product.displayName}
              middle={product.description}
              bottom={product.displayAmount}
            />
          }
          right={
            <Button size="medium" onClick={() => handleBuy(product.sku)}>
              구매하기
            </Button>
          }
        />
      ))}
    </List>
  );
}

```

```tsx [React Native]
import { IAP, IapProductListItem } from "@apps-in-toss/framework";
import { Button, List, ListRow } from "@toss/tds-react-native";
import { useEffect, useState, useCallback } from "react";

function IapProductList() {
  const [products, setProducts] = useState<IapProductListItem[]>([]);

  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
      },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  useEffect(() => {
    async function fetchProducts() {
      try {
        const response = await IAP.getProductItemList();
        setProducts(response?.products ?? []);
      } catch (error) {
        console.error("상품 목록을 가져오는 데 실패했어요:", error);
      }
    }

    fetchProducts();
  }, []);

  return (
    <List>
      {products.map((product) => (
        <ListRow
          key={product.sku}
          left={<ListRow.Image type="square" source={{ uri: product.iconUrl }} />}
          right={
            <Button size="medium" onPress={() => handleBuy(product.sku)}>
              구매하기
            </Button>
          }
          contents={
            <ListRow.Texts
              type="3RowTypeA"
              top={product.displayName}
              middle={product.description}
              bottom={product.displayAmount}
            />
          }
        />
      ))}
    </List>
  );
}
```

:::

### 예제 응답

```json
{
  "products": [
    {
      "sku": "sku1",
      "displayName": "광고 제거",
      "displayAmount": "4,900원",
      "iconUrl": "https://cdn.example.com/icons/premium-monthly.png",
      "description": "광고 제거 및 프리미엄 기능 제공"
    },
    {
      "sku": "sku2",
      "displayName": "코인 100개",
      "displayAmount": "9,900원",
      "iconUrl": "https://cdn.example.com/icons/coin-100.png",
      "description": "앱 내에서 사용할 수 있는 코인 100개"
    }
  ]
}
```

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-in-app-purchase](https://github.com/toss/apps-in-toss-examples/tree/main/with-in-app-purchase) 코드를 내려받아 체험해 보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/intro/guide.md'
description: >-
  앱인토스 미니앱 출시를 위한 필수 정책 가이드입니다. 제한되는 서비스, 추가 확인이 필요한 카테고리, 자사 앱 설치 및 외부 링크 제한
  정책을 확인하세요.
---

# 서비스 오픈 정책

::: tip 확인해 주세요
앱인토스 미니앱 출시를 위한 필수 정책이에요.\
가이드를 지키지 않으면 **앱 정보와 앱 출시 단계에서 반려**될 수 있으며, 기존 **출시된 미니앱의 운영 제한**이 적용될 수 있어요.\
서비스 오픈 정책은 안정적인 운영과 사용자의 보호를 위해 수시로 개정될 수 있어요.
:::

## 1. 제한되는 서비스/콘텐츠

앱인토스 미니앱 서비스가 토스 플랫폼 정책, 관련 법령, 사용자 보호 기준에 부합하는지를 사전에 점검해 주세요.\
아래에 해당하는 서비스/콘텐츠는 출시가 불가해요.

### 1) 디지털 자산 및 가상자산 관련 서비스

디지털 자산의 소유, 이전, 저장, 거래, 중개, 발행(NFT 포함) 등의 기능을 제공하는 서비스는 법적 요건 충족 여부와 관계없이 토스 플랫폼에서는 자산 손실, 소비자 피해, 자금세탁 리스크에 따라 등록이 불가해요.

### 2) 자금세탁 가능성이 있는 서비스

미니앱 내에서 현금 또는 유사 자산의 직접적인 교환, 전환, 환불 기능이 포함된 경우, 거래 구조상 자금세탁 통로로 악용될 수 있기 때문에 등록이 불가해요.

### 3) 불법 또는 부정행위를 조장하는 서비스

법적으로 금지되거나 사회적 물의를 일으킬 수 있는 신분 조작, 해킹, 불법 문서 제공, 정보 수집 우회 등의 기능이 포함된 서비스는 명백히 등록이 불가해요.

### 4) 사행성 및 복권/베팅성 콘텐츠 포함 서비스

사행성 요소가 포함된 콘텐츠는 사용자 재산상 손실, 중독 유발, 연령 제한 문제 등으로 위법 소지가 있으며, 사용자 보호 및 서비스 신뢰도 확보를 위해 등록이 불가해요.

### 5) 금융 상품 중개 ∙ 판매 ∙ 광고 서비스

대출, 보험, 카드, 증권 등 금융 상품 관련 서비스는 법적 인허가 여부와 관계없이 소비자 보호, 금융정보의 정확성, 오인 가능성 등으로 인한 운영 리스크를 방지하기 위해 등록이 불가능하며, 향후 내부 정책 및 기준 정비에 따라 오픈 여부가 검토될 수 있어요.

### 6) 투자 자문, 리딩방, 유료 정보 제공 서비스

특정 종목 추천이나 투자 전략 안내 등으로 개인 투자자의 의사결정에 영향을 미치는 서비스는 운영 리스크 및 정책적 수용 미비로 인해 등록이 불가해요.

### 7) 이외 내부 정책상 승인 불가 서비스

법률 위반 여부와 관계없이 토스의 브랜드 신뢰성, UX 정책, 리스크 관리 방침에 따라 등록이 제한될 수 있어요.

* 심사 결과는 내부 정책 및 리스크 검토 절차에 따라 변경될 수 있으며, 사전 등록을 보장하지 않아요.
* 서비스 특수성, 비즈니스 모델에 따라 사전 상담 또는 추가 설명 요청이 있을 수 있어요.
* 기존 회사 및 서비스를 단순 홍보하기 위해서 앱인토스 미니앱을 출시할 수 없어요.
* 위 내용 외에도 사용자 보호 및 신뢰성 확보를 위한 추가 기준이 적용될 수 있어요.

***

## 2. 자격이 필요한 카테고리

아래 카테고리는 **서비스 운영에 필요한 인허가/등록/신고** 등 자격 조건이 충족 되어야 할 수 있어요.\
다만, 아래 내용으로는 서비스 출시가 불가해요.

* 의료: 비대면 진료를 통해 수익을 얻는 서비스는 출시할 수 없어요.
* 쇼핑몰: 고객센터, 가품 방지 및 환불 정책을 갖추지 않은 서비스는 출시할 수 없어요.
* 교육: 국가 전문 자격증/국가 기술 자격증이 없는 상태에서 수익이 발생하는 서비스는 출시할 수 없어요.

***

## 3. 미니앱 어뷰징 방지 정책

앱인토스는 사용자의 더 높은 수준의 경험과 서비스 품질을 유지하기 위해 동일 기능의 미니앱을 반복적으로 출시하는 것을 제한하고 있으며, 위반 시 콘텐츠 미노출 및 서비스 운영이 제한될 수 있으니 아래 내용을 꼭 확인해 주세요.

::: tip 꼭 확인해 주세요
기존 미니앱과 완전하게 다른 목적의 기능만 새로운 미니앱으로 등록할 수 있어요.\
검수 단계에서 기존 미니앱과 구조의 유사도가 높다고 판단되면 반려 및 수정을 요청할 수 있어요.
:::

### 1) 동일 및 유사한 기능 기반의 앱을 여러 개 출시할 수 없어요.

핵심 기능이 같다면 테마나 대상, 주제만 다르게 구성하더라도 별도의 미니앱으로 인정되지 않아요.

* **예시 :** 동일 파트너사에서 ‘AI 여자 얼굴 만들기’, ‘AI 남자 얼굴 만들기’ 등과 같이 주제만 다르고 결과물만 달라지는 개별 미니앱으로 출시하는 경우

### 2) 동일 브랜드를 사용한 여러 개의 미니앱 출시는 불가해요.

검색 범위를 늘리기 위함 등 같은 파트너사에서 동일 브랜드명이나 로고, 색상을 반복하여 사용하는 것은 허용되지 않아요.

* **예시 :** ‘AI사진관’, ‘AI사진관 Lite’, ‘AI사진관 증명사진’ 등 동일 브랜드를 반복 또는 변형하여 사용한 미니앱

### 3) 위반 시 조치

정책 위반 시 다음 조치가 적용될 수 있어요.

* 콘텐츠 수정 요청
* 서비스 미노출 처리
* 반복 위반 시 미니앱 등록 및 운영 제한

***

## 4. 자사 앱 설치/외부 링크

앱인토스는 **자사 앱 설치 유도**와 **외부 링크 이동**을 제한하고 있어요. 위반 시 콘텐츠 비노출 또는 서비스 운영 제한이 적용될 수 있어요.

### 1) 자사 앱 설치를 유도할 수 없어요.

‘자사 앱 설치 유도’란, 미니앱 이용 중 별도 **앱 설치를 권유/강요**하는 모든 행위를 말해요.

> 앱인토스의 핵심 가치: 앱 설치 없이 토스 앱 안에서 간편하게 이용 외부 앱 설치 유도는 사용자 경험을 해치고 플랫폼 일관성을 저해하므로 허용되지 않아요.

**① 자사앱 설치 유도 예시**

* “앱을 설치하시면 더 많은 기능을 이용할 수 있어요.”
* “전용 쿠폰을 받으시려면 자사 앱을 설치하세요.”
* “앱 다운로드 후 첫 구매 시 할인해 드려요.”

**② 제한되는 행위**

* 앱 설치를 직접적으로 유도하는 문구
* 앱 설치 유도 배너/이미지 삽입
* 앱 마켓 링크 삽입
* 앱 설치 시 혜택 제공 안내
* 그 외 설치 유도로 판단될 수 있는 모든 콘텐츠/기능

### **2) 외부 링크는 허용된 경우에 한해 제한적으로 사용**

‘외부 링크 이동’은 사용자를 토스 미니앱 환경 밖의 웹/앱으로 보내는 행위예요.\
서비스 본질과 직접 관련 없는 결제창/다운로드 페이지/홍보 랜딩 등은 인정되지 않아요.

**① 예시(제한 대상)**

* “자세한 내용은 홈페이지에서 확인하세요.”
* “이동 후 결제를 완료해주세요.”
* “외부 웹사이트에서 가입을 진행해주세요.”

→ 외부 이동은 신뢰·편의성 저하, 개인정보·보안 리스크, 추적 불가 등 문제로 이어질 수 있어요.

**② 제한되는 행위**

* 미니앱 내에서 ‘앱 내 기능’을 완결적으로 제공하지 않는 구조
* 외부 결제창으로 이동
* 앱 다운로드/설치를 위한 외부 페이지 연결
* 공유하기 링크가 자사 웹사이트로 랜딩되는 경우
* 주요 기능/흐름이 외부 링크에 의존하는 구조

**③ 허용될 수 있는 경우**

* 법률상 고지/필수 안내 목적의 외부 링크
* 공공기관·제휴기관 공식 페이지 연결
* 단순 정보 확인을 위한 타사 웹사이트 이동
* 미니앱 기능 내에서 완결되지 않는 일부 특수 상황
  * 각 제품을 소개·추천 후 최저가 구매 플랫폼으로 이동
  * 혜택 제공을 위해 쿠폰 발급 플랫폼으로 이동

**기존 앱의 모든 기능을 옮겨와야 하나요?**\
모든 기능을 그대로 이식할 필요는 없어요.\
다만, 콘솔에 설정한 **‘앱 내 기능’은 미니앱 내에서 완결적으로 경험**할 수 있어야 해요.

* “~ 견적내기”라면, 미니앱에서 견적 산출까지 가능해야 해요.
* “~ 견적내고 결제하기”라면, 견적~결제까지 미니앱에서 진행되어야 해요.
* 먼저 “~ 견적내기”로 출시 후 “~ 결제하기” 기능을 후속 업데이트해도 괜찮아요.

### 3) 위반 시 조치

* 콘텐츠 수정 요청 및 고지
* 미니앱 서비스 준비 중으로 변경 (미노출)
* 반복 위반 시 미니앱 등록·운영 제한

---

---
url: 'https://developers-apps-in-toss.toss.im/intro/onboarding-process.md'
description: '앱인토스 미니앱 서비스 오픈 프로세스를 단계별로 안내합니다. 콘솔 등록부터 디자인, 개발, 검수, 출시까지 전 과정을 확인하세요.'
---

# 서비스 오픈 프로세스

앱인토스는 **누구나 빠르고 간편하게 미니앱을 출시할 수 있도록 설계된 플랫폼**이에요.\
처음 시작하는 분들도 순서대로만 따라오면 **토스 플랫폼에서 안정적이고 일관된 서비스 운영**이 가능해요.

## 1. 시작하기

## 2. 디자인하기

### 디자인 툴 사용하기

앱인토스는 **앱빌더**와 **피그마(Figma)** 두 가지 디자인 툴을 제공해요.\
토스 UI 스타일을 그대로 활용해 **빠르고 일관된 디자인**을 완성할 수 있어요.

#### **앱빌더란?**

* 파트너사를 위해 제공하는 전용 UI 디자인 툴이에요.
* 별도 설치 없이 웹에서 바로 사용할 수 있어요.
* TDS 라이브러리와 주요 컴포넌트가 포함되어 있어 빠르게 완성할 수 있어요.

## 3. 개발하기

앱인토스는 SDK와 API를 제공해 **복잡한 과정을 최소화하고 빠르게 개발**할 수 있어요.\
원하는 방식으로 개발을 시작해보세요.

게임 개발도 쉽고 빠르게 할 수 있어요.

테스트를 진행하고 출시해보세요.

앱인토스 API 사용을 위해서는 필수로 mTLS(mutual TLS, 양방향 인증) 인증서를 설정해야 해요.\
이 인증서는 파트너사 서버와 앱인토스 서버 사이의 통신을 암호화하고, 서로 신원을 확인하는데 사용 돼요.

## 4. 검수하기

### 앱인토스 검수 절차

앱인토스는 **4단계 검수 절차**를 거쳐요. 평균 소요 시간은 **2~3일**이에요.

**1. 운영 검수** : 앱 정보, 노출 정보, 서류 확인\
**2. 기능 검수** : 앱이 토스앱 안에서 오류 없이 정상 작동하는지 확인\
**3. 디자인 검수** : 토스 UI 가이드 준수 여부 검토\
**4. 보안 검수** : 개인정보·보안 관련 문제 없는지 확인

::: tip 게임 미니앱은 반드시 심의를 완료해야 런칭할 수 있어요
아래 2가지 방법 중 편하신 방법을 선택하여 등급 심의를 받아 주세요.

1. [게임물관리위원회](https://www.grac.or.kr/)를 통한 심의 후 등급분류증명서 첨부
2. 아래 자체등급분류사업자를 통한 앱 출시 시 등급 심의 후 스토어에 출시된 링크 첨부
   * 앱스토어
   * 플레이스토어
   * 원스토어
   * Microsoft Store
     :::

## 5. 미니앱 출시

검수가 완료되면 결과가 이메일로 안내돼요.\
승인 후에는 콘솔에서 ‘출시하기’ 버튼을 눌러 바로 미니앱을 오픈할 수 있어요. 🚀

---

---
url: 'https://developers-apps-in-toss.toss.im/intro/caution.md'
description: >-
  앱인토스 서비스 유형별 주요 정책과 유의사항을 확인하세요. 웹보드 게임과 데이팅/만남 서비스, 민감 콘텐츠에 대한 법적 준수 요건, 운영
  요구사항, 안전 관리 정책을 안내합니다.
---

# 서비스별 주의사항

앱인토스에서 제공되는 서비스 유형별 주요 정책과 유의사항을 안내드려요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/perf-optimization.md
---
# 성능 최적화 가이드

Unity WebGL로 만든 앱인토스 미니앱의 성능은 사용자 경험에 직접적인 영향을 줘요.\
이 가이드는 미니앱의 속도와 안정성을 높이기 위한 성능 최적화 전략과 실용적인 가이드를 정리했어요.

## 1. 성능 최적화 개요

### 최적화 목표

```
🎯 성능 목표
├── 시작 시간: < 3초
├── 프레임레이트: 30+ FPS (모바일)
├── 메모리 사용량: < 200MB
├── 로딩 시간: < 5초 (추가 씬)
└── 배터리 효율: 네이티브 대비 90%
```

### 최적화 우선순위

```
🔥 높은 우선순위 (즉시 개선 필요)
├── 시작 성능 - 사용자 첫인상 결정
├── 메모리 관리 - 크래시 방지
└── 모바일 성능 - 주요 타겟 플랫폼

⚡ 중간 우선순위 (점진적 개선)
├── 렌더링 성능 - 시각적 품질 개선
├── 네트워킹 - 안정성 향상
└── 리소스 최적화 - 용량 및 로딩 개선

 낮은 우선순위 (여유 있을 때)
├── 고급 기능 최적화
├── Edge case 처리
└── 미세 조정
```

***

## 2. 시작 성능 최적화

### 핵심 전략

* [Unity WebGL 게임 시작 속도 향상](/unity/optimization/start/startup-speed)
* [시작 흐름과 시퀀스](/unity/optimization/start/startup-sequence)
* [첫 씬 시작 최적화](/unity/optimization/start/first-scene-optimization)

### 로딩 최적화

```c#
// 점진적 로딩 구현
public class ProgressiveLoader : MonoBehaviour
{
    public async Task LoadGameProgressively()
    {
        // 1단계: 핵심 UI 로드
        await LoadEssentialUI();
        ShowGame(); // 사용자에게 빠르게 보여주기
        
        // 2단계: 게임 로직 로드 (백그라운드)
        _ = LoadGameLogicAsync();
        
        // 3단계: 추가 리소스 로드 (지연)
        _ = LoadAdditionalAssetsAsync();
    }
}
```

### 리소스 동적 로딩

* [AssetBundle로 리소스 묶기](/unity/optimization/start/assetbundle)
* [Addressables로 리소스 관리하기](/unity/optimization/start/addressables)

***

## 3. 메모리 최적화

### 메모리 관리 전략

* [Unity WebGL 메모리 최적화](/unity/optimization/runtime/memory)
* [ProfilingMemory 메모리 분석](/unity/optimization/runtime/memory-profiling)

### 텍스처 최적화

```c#
// 텍스처 메모리 절약
public class TextureOptimizer : MonoBehaviour
{
    void OptimizeTextures()
    {
        // 플랫폼별 압축 설정
        var importer = AssetImporter.GetAtPath(texturePath) as TextureImporter;
        
        // 모바일 최적화
        var mobileSettings = new TextureImporterPlatformSettings
        {
            name = "WebGL",
            maxTextureSize = 1024, // 모바일에서는 작게
            format = TextureImporterFormat.DXT5, // 압축 포맷
            compressionQuality = 50 // 품질 vs 용량 균형
        };
        
        importer.SetPlatformTextureSettings(mobileSettings);
    }
}
```

### 메모리 누수 방지

```c#
public class MemoryManager : MonoBehaviour
{
    void OnDestroy()
    {
        // 이벤트 해제
        EventBus.Unsubscribe(this);
        
        // 텍스처 해제
        if (texture != null)
        {
            DestroyImmediate(texture);
            texture = null;
        }
        
        // 리소스 정리
        Resources.UnloadUnusedAssets();
        System.GC.Collect();
    }
}
```

## 4. 렌더링 성능 최적화

### 렌더링 최적화 문서

[Unity WebGL 렌더링 성능 최적화](/unity/optimization/runtime/rendering)
[EmscriptenGLX 렌더링 모드](/unity/optimization/runtime/emscripten-glx)

### Draw Call 최적화

```c#
// 배칭 최적화
public class BatchingOptimizer : MonoBehaviour
{
    void OptimizeDrawCalls()
    {
        // Static Batching 활용
        StaticBatchingUtility.Combine(staticObjects);
        
        // Dynamic Batching 설정
        // Player Settings에서 활성화
        
        // GPU Instancing 활용
        Graphics.DrawMeshInstanced(mesh, 0, material, matrices);
    }
}
```

### LOD 시스템

```c#
public class LODManager : MonoBehaviour
{
    public LOD[] lods;
    
    void SetupLOD()
    {
        var lodGroup = gameObject.AddComponent<LODGroup>();
        
        // 거리별 LOD 설정
        lods[0] = new LOD(0.1f, highQualityRenderers); // 가까이
        lods[1] = new LOD(0.02f, mediumQualityRenderers); // 중간
        lods[2] = new LOD(0.005f, lowQualityRenderers); // 멀리
        
        lodGroup.SetLODs(lods);
    }
}
```

## 5. 프로파일링 및 분석

### 성능 분석 도구

* [Android CPU Profiler 성능 조정](/unity/optimization/runtime/android-profiling)
* [Unity Profiler 성능 조정](/unity/optimization/runtime/unity-profiler)
* [성능 심화 분석 도구](/unity/optimization/runtime/unity-profiler)

### 실시간 성능 모니터링

```c#
public class PerformanceMonitor : MonoBehaviour
{
    public Text fpsText;
    public Text memoryText;
    
    private float frameCount = 0;
    private float dt = 0.0f;
    private float fps = 0.0f;
    private float updateRate = 4.0f; // 4번 업데이트/초
    
    void Update()
    {
        frameCount++;
        dt += Time.deltaTime;
        
        if (dt > 1.0f / updateRate)
        {
            fps = frameCount / dt;
            frameCount = 0;
            dt -= 1.0f / updateRate;
            
            // UI 업데이트
            fpsText.text = $"FPS: {fps:0}";
            memoryText.text = $"Memory: {System.GC.GetTotalMemory(false) / 1024 / 1024:0}MB";
            
            // 경고 임계값 체크
            if (fps < 20) Debug.LogWarning("Low FPS detected!");
        }
    }
}
```

***

## 6. 플랫폼별 최적화

### 모바일 최적화

* [iOS 고성능 및 고성능+ 모드](/unity/optimization/runtime/ios)

### 웹 브라우저 최적화

```javascript
// JavaScript 최적화
class WebOptimizer {
    static optimizeForBrowser() {
        // 브라우저별 최적화
        if (this.isChrome()) {
            this.optimizeForChrome();
        } else if (this.isSafari()) {
            this.optimizeForSafari();
        }
        
        // 메모리 가비지 컬렉션 최적화
        if (window.performance && window.performance.memory) {
            this.monitorMemoryUsage();
        }
    }
    
    static optimizeForChrome() {
        // Chrome WebGL 최적화
        Module.canvas.addEventListener('webglcontextlost', this.handleContextLost);
    }
}
```

***

## 7. 리소스 최적화

### 에셋 최적화

* [에셋 최적화 도구 및 제안](/unity/optimization/runtime/asset)
* [압축 텍스처 최적화](/unity/optimization/runtime/compressed-texture)
* [오디오 및 비디오](/unity/optimization/runtime/audio-video)

### 파일 크기 최적화

```c#
// 빌드 후처리 최적화
public class BuildPostProcessor : IPostprocessBuildWithReport
{
    public int callbackOrder => 1;
    
    public void OnPostprocessBuild(BuildReport report)
    {
        string buildPath = report.summary.outputPath;
        
        // 불필요한 파일 제거
        RemoveUnnecessaryFiles(buildPath);
        
        // 압축 최적화
        OptimizeCompression(buildPath);
        
        // 파일 크기 리포트
        GenerateSizeReport(buildPath);
    }
}
```

***

## 8. 코드 최적화

### 스크립트 최적화

```c#
public class CodeOptimization : MonoBehaviour
{
    // 캐싱으로 성능 향상
    private Transform cachedTransform;
    private Camera cachedCamera;
    
    void Awake()
    {
        // 자주 사용하는 컴포넌트 캐싱
        cachedTransform = transform;
        cachedCamera = Camera.main;
    }
    
    void Update()
    {
        // 프레임마다 실행되는 코드 최적화
        
        // ❌ 나쁜 예
        // transform.position = Vector3.Lerp(transform.position, target, Time.deltaTime);
        
        // ✅ 좋은 예  
        cachedTransform.position = Vector3.Lerp(cachedTransform.position, target, Time.deltaTime);
    }
}
```

### WASM 최적화

* [코드 분할 도구 사용](/unity/optimization/start/wasm-split)

***

## 9. 네트워킹 성능

### 네트워크 최적화

```c#
public class NetworkOptimizer : MonoBehaviour
{
    // 연결 풀링
    private Queue<UnityWebRequest> requestPool = new Queue<UnityWebRequest>();
    
    public async Task<string> OptimizedHttpRequest(string url)
    {
        UnityWebRequest request;
        
        // 재사용 가능한 요청 객체 사용
        if (requestPool.Count > 0)
        {
            request = requestPool.Dequeue();
            request.url = url;
        }
        else
        {
            request = UnityWebRequest.Get(url);
        }
        
        try
        {
            await request.SendWebRequest();
            return request.downloadHandler.text;
        }
        finally
        {
            // 풀에 반환
            if (requestPool.Count < 10) // 풀 크기 제한
            {
                requestPool.Enqueue(request);
            }
            else
            {
                request.Dispose();
            }
        }
    }
}
```

***

## 10. 최적화 체크리스트

### 개발 단계별 체크리스트

#### 초기 개발 (프로토타입)

* unity 권장 버전 사용
* 기본 성능 측정 기준점 설정
* 주요 리소스 크기 제한 설정

#### 중간 개발 (알파/베타)

* Profiler로 병목 지점 파악
* 메모리 사용량 모니터링
* 모바일 테스트 시작
* 기본 최적화 적용

#### 출시 준비 (RC)

* 모든 최적화 기법 적용
* 다양한 기기에서 성능 테스트
* 성능 벤치마크 달성 확인
* 사용자 테스트 피드백 반영

### 성능 기준표

| 항목 | 최소 요구사항 | 권장 | 우수 |
|:--|:--:|:--:|:--:|
| 시작 시간 | < 5초 | < 3초 | < 2초 |
| 평균 FPS | 20+ | 30+ | 50+ |
| 메모리 사용량 | < 300MB | < 200MB | < 150MB |
| 첫 프레임 | < 10초 | < 5초 | < 3초 |
| 배터리 사용 | 네이티브 대비 120% | 110% | 100% |

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/perf-measure.md'
---
# 성능 최적화 평가 기준

AppsInToss Unity 미니앱의 성능을 정확하게 측정하고 평가할 수 있는 기준과 도구를 소개해요.\
정확한 측정이 이루어져야, 그다음 단계인 최적화 전략도 제대로 세울 수 있어요.

***

## 1. 성능 측정 기준

### 핵심 성능 지표 (KPI)

```
🎯 중요도별 성능 지표
├── Critical (치명적 - 즉시 해결 필요)
│   ├── 시작 시간: > 5초
│   ├── 평균 FPS: < 20
│   ├── 메모리 사용량: > 300MB
│   └── 크래시율: > 1%
│
├── High (높음 - 우선 해결)
│   ├── 시작 시간: 3-5초
│   ├── 평균 FPS: 20-30
│   ├── 메모리 사용량: 200-300MB
│   └── 로딩 시간: > 10초
│
└── Medium (보통 - 점진적 개선)
    ├── 시작 시간: 2-3초
    ├── 평균 FPS: 30-50
    ├── 메모리 사용량: 150-200MB
    └── 배터리 효율: 네이티브 대비 120%
```

### 플랫폼별 성능 기준

#### iOS 기준

| 기기 등급 | 시작 시간 | 평균 FPS | 메모리 | 배터리 |
|:--|:--:|:--:|:--:|:--:|
| High-end (iPhone 13+) | < 2초 | 60+ | < 150MB | 95% |
| Mid-range (iPhone 11–12) | < 3초 | 50+ | < 200MB | 90% |
| Low-end (iPhone X 이하) | < 5초 | 30+ | < 250MB | 85% |

#### Android 기준

| 기기 등급 | 시작 시간 | 평균 FPS | 메모리 | 배터리 |
|:--|:--:|:--:|:--:|:--:|
| High-end (Flagship) | < 2초 | 50+ | < 150MB | 90% |
| Mid-range (중급형) | < 4초 | 40+ | < 200MB | 85% |
| Low-end (저가형) | < 6초 | 25+ | < 250MB | 80% |

***

## 2. 성능 측정 도구

### Unity Built-in 측정 도구

```c#
using UnityEngine;
using UnityEngine.Profiling;
using System.Collections.Generic;
using System.Text;

public class AppsInTossPerformanceMeasure : MonoBehaviour
{
    [Header("측정 설정")]
    public bool enableMeasurement = true;
    public float measureInterval = 1.0f;
    public int maxSampleCount = 300; // 5분간 데이터
    
    [Header("성능 임계값")]
    public float fpsWarningThreshold = 30f;
    public float memoryWarningThreshold = 200f; // MB
    public float startupTimeLimit = 5f; // 초
    
    private Dictionary<string, PerformanceMetric> metrics = new Dictionary<string, PerformanceMetric>();
    private float startTime;
    private bool startupMeasured = false;
    
    [System.Serializable]
    public class PerformanceMetric
    {
        public string name;
        public Queue<float> samples = new Queue<float>();
        public float currentValue;
        public float averageValue;
        public float minValue = float.MaxValue;
        public float maxValue = float.MinValue;
        
        public void AddSample(float value)
        {
            samples.Enqueue(value);
            if (samples.Count > 300) samples.Dequeue(); // 최대 샘플 수 유지
            
            currentValue = value;
            minValue = Mathf.Min(minValue, value);
            maxValue = Mathf.Max(maxValue, value);
            
            // 평균 계산
            float sum = 0;
            foreach (float sample in samples)
                sum += sample;
            averageValue = sum / samples.Count;
        }
    }
    
    void Awake()
    {
        startTime = Time.realtimeSinceStartup;
        InitializeMetrics();
    }
    
    void Start()
    {
        if (enableMeasurement)
        {
            InvokeRepeating(nameof(MeasurePerformance), 0f, measureInterval);
        }
    }
    
    void InitializeMetrics()
    {
        metrics["FPS"] = new PerformanceMetric { name = "FPS" };
        metrics["Memory"] = new PerformanceMetric { name = "Memory (MB)" };
        metrics["DrawCalls"] = new PerformanceMetric { name = "Draw Calls" };
        metrics["Triangles"] = new PerformanceMetric { name = "Triangles" };
        metrics["CPUFrameTime"] = new PerformanceMetric { name = "CPU Frame Time (ms)" };
        metrics["GPUFrameTime"] = new PerformanceMetric { name = "GPU Frame Time (ms)" };
    }
    
    void MeasurePerformance()
    {
        // FPS 측정
        float fps = 1.0f / Time.unscaledDeltaTime;
        metrics["FPS"].AddSample(fps);
        
        // 메모리 측정 (MB)
        float memoryMB = Profiler.GetTotalAllocatedMemory(false) / (1024f * 1024f);
        metrics["Memory"].AddSample(memoryMB);
        
        // 렌더링 통계
        metrics["DrawCalls"].AddSample(UnityEngine.Rendering.FrameDebugger.enabled ? 
            UnityEngine.Rendering.FrameDebugger.GetFrameEventCount() : 0);
        
        // CPU/GPU 프레임 시간
        float cpuTime = Time.deltaTime * 1000f; // ms로 변환
        metrics["CPUFrameTime"].AddSample(cpuTime);
        
        // 시작 시간 측정 (한 번만)
        if (!startupMeasured && Time.realtimeSinceStartup > 1f)
        {
            float startupTime = Time.realtimeSinceStartup - startTime;
            LogStartupTime(startupTime);
            startupMeasured = true;
        }
        
        // 경고 임계값 체크
        CheckPerformanceWarnings();
    }
    
    void CheckPerformanceWarnings()
    {
        // FPS 경고
        if (metrics["FPS"].currentValue < fpsWarningThreshold)
        {
            Debug.LogWarning($"Low FPS detected: {metrics["FPS"].currentValue:F1}");
            SendWarningToAppsInToss("low_fps", metrics["FPS"].currentValue);
        }
        
        // 메모리 경고
        if (metrics["Memory"].currentValue > memoryWarningThreshold)
        {
            Debug.LogWarning($"High memory usage: {metrics["Memory"].currentValue:F1}MB");
            SendWarningToAppsInToss("high_memory", metrics["Memory"].currentValue);
        }
    }
    
    void LogStartupTime(float startupTime)
    {
        Debug.Log($"[Performance] Startup time: {startupTime:F2}s");
        
        if (startupTime > startupTimeLimit)
        {
            Debug.LogWarning($"Startup time exceeds limit: {startupTime:F2}s > {startupTimeLimit}s");
        }
        
        // AppsInToss 분석 시스템에 전송
        SendMetricToAppsInToss("startup_time", startupTime);
    }
    
    void SendWarningToAppsInToss(string warningType, float value)
    {
        var data = new Dictionary<string, object>
        {
            {"warning_type", warningType},
            {"value", value},
            {"timestamp", System.DateTime.UtcNow.ToString("o")},
            {"device_model", SystemInfo.deviceModel},
            {"memory_size", SystemInfo.systemMemorySize},
            {"processor_type", SystemInfo.processorType}
        };
        
        // AppsInToss Native 호출
        Application.ExternalCall("SendPerformanceWarning", JsonUtility.ToJson(data));
    }
    
    void SendMetricToAppsInToss(string metricName, float value)
    {
        var data = new Dictionary<string, object>
        {
            {"metric_name", metricName},
            {"value", value},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        Application.ExternalCall("SendPerformanceMetric", JsonUtility.ToJson(data));
    }
    
    // 성능 리포트 생성
    public string GeneratePerformanceReport()
    {
        var report = new StringBuilder();
        report.AppendLine("=== AppsInToss 성능 측정 리포트 ===");
        report.AppendLine($"측정 시간: {System.DateTime.Now:yyyy-MM-dd HH:mm:ss}");
        report.AppendLine($"기기 정보: {SystemInfo.deviceModel}");
        report.AppendLine($"메모리: {SystemInfo.systemMemorySize}MB");
        report.AppendLine($"프로세서: {SystemInfo.processorType}");
        report.AppendLine();
        
        foreach (var metric in metrics.Values)
        {
            report.AppendLine($"[{metric.name}]");
            report.AppendLine($"  현재값: {metric.currentValue:F2}");
            report.AppendLine($"  평균값: {metric.averageValue:F2}");
            report.AppendLine($"  최소값: {metric.minValue:F2}");
            report.AppendLine($"  최대값: {metric.maxValue:F2}");
            report.AppendLine($"  샘플 수: {metric.samples.Count}");
            report.AppendLine();
        }
        
        return report.ToString();
    }
    
    // GUI 성능 표시
    void OnGUI()
    {
        if (!enableMeasurement) return;
        
        GUILayout.BeginArea(new Rect(10, 10, 300, 150));
        GUILayout.Box("AppsInToss 성능 모니터");
        
        GUILayout.Label($"FPS: {metrics["FPS"].currentValue:F1} (평균: {metrics["FPS"].averageValue:F1})");
        GUILayout.Label($"메모리: {metrics["Memory"].currentValue:F1}MB");
        GUILayout.Label($"Draw Calls: {metrics["DrawCalls"].currentValue:F0}");
        
        // 성능 상태 표시
        if (metrics["FPS"].currentValue < fpsWarningThreshold)
        {
            GUI.color = Color.red;
            GUILayout.Label("⚠ FPS 경고");
        }
        
        if (metrics["Memory"].currentValue > memoryWarningThreshold)
        {
            GUI.color = Color.red;
            GUILayout.Label("⚠ 메모리 경고");
        }
        
        GUI.color = Color.white;
        GUILayout.EndArea();
    }
}
```

***

## 3. 자동화된 성능 테스트

### 성능 테스트 스크립트

```c#
using UnityEngine;
using System.Collections;
using System.Collections.Generic;

public class AutomatedPerformanceTest : MonoBehaviour
{
    [System.Serializable]
    public class TestScenario
    {
        public string name;
        public string sceneName;
        public float testDuration = 60f; // 초
        public int targetFPS = 30;
        public float maxMemoryMB = 200f;
    }
    
    public TestScenario[] testScenarios;
    
    private PerformanceTestResult currentResult;
    
    [System.Serializable]
    public class PerformanceTestResult
    {
        public string scenarioName;
        public float averageFPS;
        public float minFPS;
        public float maxMemoryMB;
        public float testDuration;
        public bool passed;
        public List<string> issues = new List<string>();
    }
    
    public void RunAllTests()
    {
        StartCoroutine(RunTestSequence());
    }
    
    IEnumerator RunTestSequence()
    {
        var allResults = new List<PerformanceTestResult>();
        
        foreach (var scenario in testScenarios)
        {
            Debug.Log($"Starting test: {scenario.name}");
            
            yield return StartCoroutine(RunSingleTest(scenario));
            
            allResults.Add(currentResult);
            
            // 테스트 간 쿨다운
            yield return new WaitForSeconds(2f);
        }
        
        GenerateTestReport(allResults);
    }
    
    IEnumerator RunSingleTest(TestScenario scenario)
    {
        currentResult = new PerformanceTestResult
        {
            scenarioName = scenario.name,
            testDuration = scenario.testDuration
        };
        
        // 씬 로드
        var loadOp = UnityEngine.SceneManagement.SceneManager.LoadSceneAsync(scenario.sceneName);
        yield return loadOp;
        
        // 안정화 대기
        yield return new WaitForSeconds(2f);
        
        // 성능 측정 시작
        float startTime = Time.time;
        float fpsSum = 0f;
        int fpsCount = 0;
        float minFPS = float.MaxValue;
        float maxMemory = 0f;
        
        while (Time.time - startTime < scenario.testDuration)
        {
            float fps = 1.0f / Time.unscaledDeltaTime;
            fpsSum += fps;
            fpsCount++;
            minFPS = Mathf.Min(minFPS, fps);
            
            float memoryMB = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(false) / (1024f * 1024f);
            maxMemory = Mathf.Max(maxMemory, memoryMB);
            
            yield return new WaitForSeconds(0.1f); // 10Hz 측정
        }
        
        // 결과 계산
        currentResult.averageFPS = fpsSum / fpsCount;
        currentResult.minFPS = minFPS;
        currentResult.maxMemoryMB = maxMemory;
        
        // 성능 기준 체크
        EvaluateTestResult(scenario);
    }
    
    void EvaluateTestResult(TestScenario scenario)
    {
        currentResult.passed = true;
        currentResult.issues.Clear();
        
        if (currentResult.averageFPS < scenario.targetFPS)
        {
            currentResult.passed = false;
            currentResult.issues.Add($"평균 FPS 부족: {currentResult.averageFPS:F1} < {scenario.targetFPS}");
        }
        
        if (currentResult.minFPS < scenario.targetFPS * 0.7f) // 30% 드롭 허용
        {
            currentResult.passed = false;
            currentResult.issues.Add($"최소 FPS 부족: {currentResult.minFPS:F1}");
        }
        
        if (currentResult.maxMemoryMB > scenario.maxMemoryMB)
        {
            currentResult.passed = false;
            currentResult.issues.Add($"메모리 사용량 초과: {currentResult.maxMemoryMB:F1}MB > {scenario.maxMemoryMB}MB");
        }
    }
    
    void GenerateTestReport(List<PerformanceTestResult> results)
    {
        var report = new System.Text.StringBuilder();
        report.AppendLine("=== 자동화 성능 테스트 결과 ===");
        report.AppendLine($"테스트 일시: {System.DateTime.Now:yyyy-MM-dd HH:mm:ss}");
        report.AppendLine($"기기: {SystemInfo.deviceModel}");
        report.AppendLine();
        
        int passedCount = 0;
        
        foreach (var result in results)
        {
            report.AppendLine($"[{result.scenarioName}] - {(result.passed ? "PASS" : "FAIL")}");
            report.AppendLine($"  평균 FPS: {result.averageFPS:F1}");
            report.AppendLine($"  최소 FPS: {result.minFPS:F1}");
            report.AppendLine($"  최대 메모리: {result.maxMemoryMB:F1}MB");
            
            if (!result.passed)
            {
                foreach (var issue in result.issues)
                {
                    report.AppendLine($"  ❌ {issue}");
                }
            }
            else
            {
                passedCount++;
            }
            
            report.AppendLine();
        }
        
        report.AppendLine($"전체 결과: {passedCount}/{results.Count} 통과");
        
        Debug.Log(report.ToString());
        
        // AppsInToss 리포팅 시스템에 전송
        SendTestReportToAppsInToss(report.ToString(), results);
    }
    
    void SendTestReportToAppsInToss(string report, List<PerformanceTestResult> results)
    {
        var data = new Dictionary<string, object>
        {
            {"report", report},
            {"results", results},
            {"device_info", new Dictionary<string, object>
            {
                {"model", SystemInfo.deviceModel},
                {"memory", SystemInfo.systemMemorySize},
                {"processor", SystemInfo.processorType},
                {"graphics", SystemInfo.graphicsDeviceName}
            }}
        };
        
        Application.ExternalCall("SendPerformanceTestReport", JsonUtility.ToJson(data));
    }
}
```

***

## 4. 실시간 성능 대시보드

### 웹 기반 성능 모니터링

```tsx
// TypeScript - AppsInToss 성능 대시보드
interface PerformanceData {
    timestamp: number;
    fps: number;
    memory: number;
    drawCalls: number;
    cpuTime: number;
    gpuTime: number;
}

class AppsInTossPerformanceDashboard {
    private performanceData: PerformanceData[] = [];
    private maxDataPoints = 300; // 5분간 데이터 (1초 간격)
    private charts: { [key: string]: any } = {};
    
    constructor() {
        this.initializeDashboard();
        this.startDataCollection();
    }
    
    initializeDashboard() {
        // Chart.js 또는 다른 차트 라이브러리 초기화
        this.createFPSChart();
        this.createMemoryChart();
        this.createDrawCallChart();
    }
    
    createFPSChart() {
        const ctx = document.getElementById('fpsChart') as HTMLCanvasElement;
        this.charts.fps = new Chart(ctx, {
            type: 'line',
            data: {
                labels: [],
                datasets: [{
                    label: 'FPS',
                    data: [],
                    borderColor: '#4CAF50',
                    backgroundColor: 'rgba(76, 175, 80, 0.1)',
                    tension: 0.4
                }]
            },
            options: {
                responsive: true,
                scales: {
                    y: {
                        beginAtZero: true,
                        max: 60,
                        ticks: {
                            callback: function(value) {
                                return value + ' FPS';
                            }
                        }
                    }
                },
                plugins: {
                    legend: {
                        position: 'top'
                    },
                    title: {
                        display: true,
                        text: 'FPS 모니터링'
                    }
                }
            }
        });
    }
    
    createMemoryChart() {
        const ctx = document.getElementById('memoryChart') as HTMLCanvasElement;
        this.charts.memory = new Chart(ctx, {
            type: 'area',
            data: {
                labels: [],
                datasets: [{
                    label: 'Memory (MB)',
                    data: [],
                    borderColor: '#FF9800',
                    backgroundColor: 'rgba(255, 152, 0, 0.2)',
                    fill: true
                }]
            },
            options: {
                responsive: true,
                scales: {
                    y: {
                        beginAtZero: true,
                        ticks: {
                            callback: function(value) {
                                return value + ' MB';
                            }
                        }
                    }
                }
            }
        });
    }
    
    startDataCollection() {
        setInterval(() => {
            this.collectPerformanceData();
        }, 1000); // 1초마다 데이터 수집
    }
    
    collectPerformanceData() {
        // Unity에서 성능 데이터 요청
        if ((window as any).unityInstance) {
            (window as any).unityInstance.SendMessage('AppsInTossPerformanceMeasure', 'SendCurrentMetrics', '');
        }
    }
    
    updateDashboard(data: PerformanceData) {
        // 데이터 저장
        this.performanceData.push(data);
        
        // 최대 데이터 포인트 수 유지
        if (this.performanceData.length > this.maxDataPoints) {
            this.performanceData.shift();
        }
        
        // 차트 업데이트
        this.updateCharts();
        
        // 경고 체크
        this.checkPerformanceAlerts(data);
    }
    
    updateCharts() {
        const labels = this.performanceData.map(d => new Date(d.timestamp).toLocaleTimeString());
        
        // FPS 차트 업데이트
        this.charts.fps.data.labels = labels;
        this.charts.fps.data.datasets[0].data = this.performanceData.map(d => d.fps);
        this.charts.fps.update('none');
        
        // 메모리 차트 업데이트
        this.charts.memory.data.labels = labels;
        this.charts.memory.data.datasets[0].data = this.performanceData.map(d => d.memory);
        this.charts.memory.update('none');
    }
    
    checkPerformanceAlerts(data: PerformanceData) {
        const alerts = [];
        
        if (data.fps < 20) {
            alerts.push({
                type: 'critical',
                message: `심각한 FPS 저하: ${data.fps.toFixed(1)} FPS`
            });
        } else if (data.fps < 30) {
            alerts.push({
                type: 'warning',
                message: `FPS 경고: ${data.fps.toFixed(1)} FPS`
            });
        }
        
        if (data.memory > 200) {
            alerts.push({
                type: 'critical',
                message: `높은 메모리 사용량: ${data.memory.toFixed(1)} MB`
            });
        } else if (data.memory > 150) {
            alerts.push({
                type: 'warning',
                message: `메모리 경고: ${data.memory.toFixed(1)} MB`
            });
        }
        
        if (alerts.length > 0) {
            this.showAlerts(alerts);
        }
    }
    
    showAlerts(alerts: any[]) {
        const alertContainer = document.getElementById('performanceAlerts');
        if (alertContainer) {
            alertContainer.innerHTML = '';
            alerts.forEach(alert => {
                const alertElement = document.createElement('div');
                alertElement.className = `alert alert-${alert.type}`;
                alertElement.textContent = alert.message;
                alertContainer.appendChild(alertElement);
            });
        }
    }
    
    generateReport() {
        if (this.performanceData.length === 0) return;
        
        const latest = this.performanceData[this.performanceData.length - 1];
        const avgFPS = this.performanceData.reduce((sum, d) => sum + d.fps, 0) / this.performanceData.length;
        const maxMemory = Math.max(...this.performanceData.map(d => d.memory));
        
        return {
            currentFPS: latest.fps,
            averageFPS: avgFPS,
            currentMemory: latest.memory,
            maxMemory: maxMemory,
            sampleCount: this.performanceData.length,
            duration: (latest.timestamp - this.performanceData[0].timestamp) / 1000 // 초
        };
    }
}

// Unity에서 호출하는 글로벌 함수
(window as any).UpdatePerformanceData = (dataJson: string) => {
    const data = JSON.parse(dataJson) as PerformanceData;
    dashboard.updateDashboard(data);
};

// 대시보드 인스턴스 생성
const dashboard = new AppsInTossPerformanceDashboard();
```

***

## 5. 성능 평가 체크리스트

### 출시 전 성능 검증 체크리스트

* 시작 시간 5초 이내 (모든 대상 기기)
* 평균 FPS 30 이상 유지 (1분 이상 테스트)
* 메모리 사용량 200MB 이하 (장시간 플레이)
* 크래시율 1% 이하 (100명 이상 베타 테스트)
* 배터리 효율성 네이티브 앱 대비 85% 이상
* 네트워크 끊김 상황에서 정상 동작
* 백그라운드 진입/복귀 시 정상 동작
* 다양한 화면 비율에서 정상 동작
* 메모리 부족 상황 대응 (우아한 저하)
* 자동화된 성능 테스트 통과

### 정기 모니터링 체크리스트

* 주간 성능 리포트 검토
* 사용자 피드백 중 성능 관련 이슈 분석
* 성능 저하 트렌드 모니터링
* A/B 테스트를 통한 최적화 효과 검증
* 새로운 기기/OS 버전 호환성 테스트

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/runtime/profile.md'
---
# 성능 프로파일링

앱인토스 미니앱에서 Unity WebGL 게임의 성능을 프로파일링하고 최적화하는 방법을 안내해요.

***

## 1. 프로파일링 도구 개요

### Unity Profiler

* Unity 에디터 내장 프로파일러
* CPU, 메모리, 렌더링 성능 분석
* WebGL 빌드에서 제한적 지원

### 브라우저 개발자 도구

* Chrome DevTools Performance 탭
* JavaScript 성능 분석
* 메모리 사용량 모니터링

### AppsInToss Analytics

* 실시간 성능 모니터링
* 사용자 환경별 성능 데이터
* 크래시 리포트 통합

***

## 2. 성능 측정 지표

### 핵심 성능 지표 (KPI)

```
📊 필수 측정 항목
├── FPS (Frames Per Second): 30fps 이상 권장
├── 로딩 시간: 초기 로딩 5초 이내
├── 메모리 사용량: 200MB 이하 권장
├── 네트워크 지연: 100ms 이하
└── 배터리 소모: 표준 게임 대비 120% 이하
```

### 사용자 경험 지표 (UX)

```
👤 UX 측정 항목  
├── 앱 시작 시간: 3초 이내
├── 씬 전환 시간: 2초 이내
├── 입력 지연: 16ms 이하 (60fps 기준)
├── UI 반응성: 터치 후 즉시 반응
└── 안정성: 크래시율 1% 미만
```

***

## 3. Unity Profiler 활용

### WebGL 프로파일링 설정

```c#
// Development Build 필수
PlayerSettings.SetScriptingDefineSymbolsForGroup(
    BuildTargetGroup.WebGL, 
    "ENABLE_PROFILER"
);
```

### 원격 프로파일링 연결

1. Unity 에디터에서 Window → Analysis → Profiler 열기
2. Target 드롭다운에서 Enter IP 선택
3. 브라우저 IP 주소 입력
4. Connected 상태 확인

### 주요 분석 영역

#### CPU Usage

```
🔍 CPU 프로파일링 체크포인트
├── Scripts: C# 스크립트 실행 시간
├── Rendering: 렌더링 파이프라인 비용
├── Physics: 물리 연산 오버헤드
├── UI: UI 렌더링 및 이벤트 처리
└── Others: 기타 시스템 오버헤드
```

#### Memory

```
💾 메모리 사용량 분석
├── Unity Objects: GameObject, Component 메모리
├── Graphics: 텍스처, 메시 메모리 
├── Audio: 오디오 클립 메모리
├── Scripts: C# 힙 메모리
└── WebAssembly: WASM 메모리 할당
```

#### Rendering

```
🎨 렌더링 성능 분석
├── Draw Calls: 드로우콜 수 (200개 이하 권장)
├── Triangles: 삼각형 수 (10만개 이하 권장)  
├── Vertices: 정점 수 (5만개 이하 권장)
├── SetPass Calls: 머티리얼 변경 수
└── Batches: 배칭 효율성
```

***

## 4. 브라우저 도구 활용

### Chrome DevTools 성능 분석

#### Performance 탭 사용법

1. F12로 개발자 도구 열기
2. Performance 탭 선택
3. Record 버튼으로 프로파일링 시작
4. 게임 플레이 후 중지
5. 분석 결과 검토

#### 분석 요소

```javascript
// JavaScript 성능 측정
console.time('GameLoop');
// 게임 로직 실행
console.timeEnd('GameLoop');

// 메모리 사용량 확인
console.log('Memory Usage:', performance.memory);
```

#### Memory 탭 활용

```
🧠 메모리 분석
├── Heap Snapshot: 특정 시점 메모리 상태
├── Allocation Timeline: 메모리 할당 패턴
├── Allocation Sampling: 메모리 누수 감지  
└── Performance Monitor: 실시간 메모리 추적
```

***

## 5. AppsInToss Analytics 연동

### SDK 설정

```c#
using AppsInToss.Analytics;

// 성능 모니터링 시작
PerformanceMonitor.StartTracking();

// 커스텀 메트릭 추가
PerformanceMonitor.TrackMetric("LoadTime", loadTime);
PerformanceMonitor.TrackMetric("FPS", averageFPS);
```

### 실시간 모니터링 대시보드

* 성능 지표 실시간 추적
* 사용자별 성능 분석
* 기기별 성능 차이 파악
* 지역별 네트워크 성능

***

## 6. 성능 최적화 가이드

### CPU 최적화

```c#
// Object Pooling 구현
public class ObjectPool<T> : MonoBehaviour where T : MonoBehaviour
{
    public T prefab;
    private Queue<T> objects = new Queue<T>();
    
    public T Get()
    {
        if (objects.Count > 0)
            return objects.Dequeue();
        return Instantiate(prefab);
    }
    
    public void Return(T obj)
    {
        obj.gameObject.SetActive(false);
        objects.Enqueue(obj);
    }
}
```

### 메모리 최적화

```c#
// 리소스 해제 관리
public class ResourceManager : MonoBehaviour
{
    void OnSceneLoaded(Scene scene, LoadSceneMode mode)
    {
        // 사용하지 않는 에셋 해제
        Resources.UnloadUnusedAssets();
        System.GC.Collect();
    }
}
```

### 렌더링 최적화

```c#
// LOD 시스템 활용
public class LODController : MonoBehaviour
{
    public Renderer[] renderers;
    public float[] lodDistances = {10f, 50f, 100f};
    
    void Update()
    {
        float distance = Vector3.Distance(Camera.main.transform.position, transform.position);
        
        for (int i = 0; i < renderers.Length; i++)
        {
            renderers[i].enabled = distance <= lodDistances[i];
        }
    }
}
```

***

## 7. 성능 문제 해결

### 일반적인 성능 병목

```
⚠️ 흔한 성능 문제
├── 과도한 DrawCall: 배칭 최적화 필요
├── 메모리 누수: 오브젝트 해제 확인  
├── 무거운 Update(): 로직 최적화 필요
├── 큰 텍스처: 압축 및 해상도 조정
└── 복잡한 셰이더: 모바일용 셰이더 사용
```

### 해결 전략

1. 병목 지점 식별: 프로파일러로 정확한 원인 파악
2. 우선순위 설정: 성능 영향이 큰 부분부터 최적화
3. 측정과 검증: 최적화 후 성능 개선 확인
4. 지속적 모니터링: 정기적인 성능 체크

***

## 8. 성능 테스트 체크리스트

### 개발 단계

* Unity Profiler로 CPU/메모리 사용량 확인
* 드로우콜 수 200개 이하 유지
* 텍스처 메모리 사용량 50MB 이하
* 60FPS 또는 30FPS 일정하게 유지

### 배포 전

* 다양한 기기에서 성능 테스트
* 네트워크 환경별 로딩 시간 측정
* 장시간 플레이 시 메모리 누수 확인
* 배터리 소모량 테스트

### 배포 후

* AppsInToss Analytics로 실시간 모니터링
* 사용자 피드백 기반 성능 개선
* A/B 테스트로 최적화 효과 검증
* 정기적인 성능 리포트 검토

성능 최적화는 지속적인 과정이에요. 정기적인 프로파일링과 모니터링을 통해 최적의 성능을 유지하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인증/tosscertSessionKey.md
---
# 세션키 생성

본인 인증 연동시 필요한 세션키를 발급하는 방법을 설명해요.\
보안을 위해 세션키(sessionKey)는 매 요청마다 새로 생성하세요.

:::code-group

```java
public static String generateSessionKey(String sessionId, String secretKey, String iv, String base64PublicKey) throws Exception {
    String sessionAesKey = "AES_GCM$" + secretKey + "$" + iv;
    String encryptedSessionAesKey = encryptSessionAesKey(base64PublicKey, sessionAesKey);
    return "v1$" + sessionId + "$" + encryptedSessionAesKey;
}

```

```javascript
generateSessionKey: function (sessionId, secretKey, iv, base64PublicKey) {
    let sessionAesKey = 'AES_GCM$' + secretKey + '$' + iv
    let encryptedSessionAesKey = this.encryptSessionAesKey(base64PublicKey, sessionAesKey)
    return 'v1$' + sessionId + '$' + encryptedSessionAesKey
},
```

```csharp
public static string GenerateSessionKey(string sessionId, string secretKey, string iv, string base64PublicKey)
{
    string sessionAesKey = "AES_GCM$" + secretKey + "$" + iv;
    string encryptedSessionAesKey = EncryptSessionAesKey(base64PublicKey, sessionAesKey);
    return "v1$" + sessionId + "$" + encryptedSessionAesKey;
}

```

```php
function generateSessionKey(string $sessionId, string $secretKey, string $iv, string $base64PublicKey): string
{
    $sessionAesKey = "AES_GCM$" . $secretKey . "$" . $iv;
    $encryptedSessionAesKey = encryptSessionAesKey($base64PublicKey, $sessionAesKey);
    return "v1$" . $sessionId . "$" . $encryptedSessionAesKey;
}
```

```python
def generate_session_key(session_id, secret_key, iv, base64_public_key):
    session_aes_key = 'AES_GCM$' + secret_key + '$' + iv
    encrypted_session_aes_key = encrypt_session_aes_key(base64_public_key, session_aes_key)
    return 'v1$' + session_id + '$' + encrypted_session_aes_key

```

```ruby
def generate_session_key(session_id, secret_key, iv, base64_public_key)
  session_aes_key = 'AES_GCM$' + secret_key + '$' + iv
  encrypted_session_aes_key = encrypt_session_aes_key(base64_public_key, session_aes_key)
  'v1$' + session_id + '$' + encrypted_session_aes_key
end
```

:::

보다 자세한 예시는 [여기](https://github.com/toss/toss-cert-examples)에서 확인해보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/intersection-observer.md
---

# 스크롤 뷰에서 요소 감지하기

## `IOScrollView`, `ImpressionArea`

[`IOScrollView`](/bedrock/reference/framework/화면%20제어/IOScrollView.md)와 [`ImpressionArea`](/bedrock/reference/framework/화면%20제어/ImpressionArea.md)를 사용해서 스크롤 뷰 내에서 요소가 화면에 보이는지 확인할 수 있어요. 특정 요소가 화면에 일정 비율 이상 나타나면 `onImpressionStart` 콜백이 호출돼요.

[`ImpressionArea`](/bedrock/reference/framework/화면%20제어/ImpressionArea.md)의 `areaThreshold` 값을 설정하면, 설정한 비율 이상으로 요소가 보이면 `onImpressionStart` 콜백이 호출돼요.

::: tip `IOScrollView` 내부에서만 사용할 수 있어요
[`ImpressionArea`](/bedrock/reference/framework/화면%20제어/ImpressionArea.md)는 반드시 [`IOScrollView`](/bedrock/reference/framework/화면%20제어/IOScrollView.md) 내부에 있어야 해요.

그렇지 않으면, `IOContext.Provider 밖에서 사용되었습니다.`라는 에러가 발생해요.
:::

## 스크롤 뷰에서 요소가 20% 이상 나타날 때 처리하기

다음 코드는 높이 `100px`을 가진 요소가 [`IOScrollView`](/bedrock/reference/framework/화면%20제어/IOScrollView.md)에서 `20%`이상 나타났을 때`onImpressionStart`가 호출되는 예제에요.

빨간색 선은 `100px`의 `20%` 지점을 시각적으로 표시한 예시예요.

```tsx{14,18,22-27,37-38}
import { createRoute, ImpressionArea, IOScrollView } from '@granite-js/react-native';
import { ReactNode } from 'react';
import { Alert, Text, View } from 'react-native';

export const Route = createRoute('/image', {
  component: Image,
});

/* 스크롤을 위한 Dummy 콘텐츠 */
const dummies = new Array(10).fill(undefined);

/** 20% 지점 */
const AREA_THRESHOLD = 0.2; // [!code focus]

function Image() {
  return (
    <IOScrollView> // [!code focus]
      {dummies.map((_, index) => {
        return <DummyContent key={index} text={10 - index} />;
      })}
      <ImpressionArea // [!code focus]
        areaThreshold={AREA_THRESHOLD} // [!code focus]
        onImpressionStart={() => { // [!code focus]
          Alert.alert('Impression Start'); // [!code focus]
        }} // [!code focus]
      > // [!code focus]
        <View
          style={{
            width: '100%',
            height: 100,
            backgroundColor: 'blue',
          }}
        >
          <DebugLine areaThreshold={AREA_THRESHOLD} />
        </View>
      </ImpressionArea> // [!code focus]
    </IOScrollView> // [!code focus]
  );
}

/** 비율을 시각적으로 표시하는 디버그 컴포넌트 */
function DebugLine({ areaThreshold }: { areaThreshold: number }) {
  return (
    <View
      style={{
        position: 'absolute',
        top: `${areaThreshold * 100}%`,
        width: '100%',
        height: 1,
        backgroundColor: 'red',
      }}
    />
  );
}

/** Dummy 영역 */
function DummyContent({ text }: { text: ReactNode }) {
  return (
    <View
      style={{
        width: '100%',
        height: 100,
        borderWidth: 1,
      }}
    >
      <Text>{text}</Text>
    </View>
  );
}
```

## 레퍼런스

* [`IOScrollView` 컴포넌트](/bedrock/reference/framework/화면%20제어/IOScrollView.md)
* [`ImpressionArea` 컴포넌트](/bedrock/reference/framework/화면%20제어/ImpressionArea.md)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/IOScrollView.md
---

# 스크롤 영역 노출 감지하기

## `IOScrollView`

`IOScrollView`는 `Intersection Observer` 기능이 추가된 [ScrollView](https://reactnative.dev/docs/scrollview) 컴포넌트예요. 스크롤 중 특정 요소가 화면에 보이거나 사라지는 상태를 감지할 수 있어요.
이 기능을 활용해 `InView` 컴포넌트를 자식 요소로 사용하면, 화면에 노출되는지 여부를 쉽게 확인할 수 있어요.

## 시그니처

```typescript
IOScrollView: ForwardRefExoticComponent<IOScrollViewProps & RefAttributes<IOScrollViewController>>
```

## 예제

`IOScrollView`를 사용해 리스트의 각 항목이 화면에 나타나는지 여부를 확인할 수 있어요.
리스트의 각 항목이 화면에 나타나면 `InView` 컴포넌트가 `visible` 상태로 변경되어요.

```tsx
import { ReactNode, useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { InView, IOScrollView } from '@granite-js/react-native';

const mockData = Array.from({ length: 30 }, (_, i) => ({ key: String(i) }));

function IOScrollViewPage() {
 return (
   <IOScrollView>
     {mockData.map((data) => (
       <InViewItem key={data.key}>{data.key}</InViewItem>
     ))}
   </IOScrollView>
 );
}

function InViewItem({ children }: { children: ReactNode }) {
 const [visible, setVisible] = useState(false);

 return (
   <InView onChange={setVisible}>
     <View style={styles.item}>
       <Text>{children}</Text>
       <Text>{visible ? 'visible' : ''}</Text>
     </View>
   </InView>
 );
}

const styles = StyleSheet.create({
 item: {
   padding: 16,
   borderBottomWidth: 1,
   borderBottomColor: '#ddd',
 },
});
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/환경
  확인/getSchemeUri.md
---

# 스킴 값 가져오기

## `getSchemeUri`

`getSchemeUri` 는 처음에 화면에 진입한 스킴 값을 반환해요. 페이지 이동으로 인한 URI 변경은 반영되지 않아요.

## 시그니처

```typescript
function getSchemeUri(): string;
```

### 반환 값

## 예제

### 처음 진입한 스킴 값 가져오기

```tsx
import { getSchemeUri } from '@apps-in-toss/framework';
import { Text } from 'react-native';

function MyPage() {
 const schemeUri = getSchemeUri();

 return <Text>처음에 화면에 진입한 스킴 값: {schemeUri}</Text>
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/launch-opera.md
---
# 시작 스토리 디자인 가이드

AppsInToss Unity 게임에서 매력적이고 몰입도 높은 게임 시작 경험을 설계하는 방법을 다뤄요.

***

## 1. 런치 오페라 개념

### 런치 오페라란?

```
🎭 런치 오페라 구성요소
├── 브랜드 스토리텔링
│   ├── 토스 × 게임 브랜딩
│   ├── 게임 세계관 소개
│   └── 캐릭터/스토리 티저
├── 사용자 온보딩
│   ├── 직관적인 조작법 안내
│   ├── 핵심 게임 메커니즘 소개
│   └── 진행 목표 제시
├── 감정적 연결
│   ├── 음악과 사운드 디자인
│   ├── 시각적 임팩트
│   └── 개인화된 경험
└── 즉시 참여 유도
    ├── 빠른 액션 시퀀스
    ├── 성취감 제공
    └── 다음 단계로의 자연스러운 전환
```

### 런치 오페라 매니저

```c#
using UnityEngine;
using UnityEngine.UI;
using System.Collections;
using System.Collections.Generic;
using TMPro;

public class LaunchOperaManager : MonoBehaviour
{
    public static LaunchOperaManager Instance { get; private set; }
    
    [System.Serializable]
    public class OperaSequence
    {
        [Header("시퀀스 설정")]
        public string sequenceName;
        public float duration = 3f;
        public bool skippable = true;
        public bool autoAdvance = true;
        
        [Header("시각적 요소")]
        public GameObject[] visualElements;
        public AnimationClip[] animations;
        public Sprite backgroundImage;
        public Color backgroundColor = Color.black;
        
        [Header("오디오")]
        public AudioClip backgroundMusic;
        public AudioClip[] soundEffects;
        public float musicVolume = 0.7f;
        
        [Header("텍스트")]
        public string title;
        public string[] dialogues;
        public float textSpeed = 50f; // 글자/초
        public bool showCharacterByCharacter = true;
        
        [Header("인터랙션")]
        public bool requiresUserInput = false;
        public string inputPrompt = "터치하여 계속";
        public KeyCode[] skipKeys = { KeyCode.Space, KeyCode.Return };
    }
    
    [Header("런치 오페라 설정")]
    public OperaSequence[] operaSequences;
    public bool enableSkipAll = true;
    public string skipAllText = "모두 건너뛰기";
    
    [Header("UI 컴포넌트")]
    public Canvas operaCanvas;
    public Image backgroundImage;
    public TextMeshProUGUI titleText;
    public TextMeshProUGUI dialogueText;
    public Button continueButton;
    public Button skipButton;
    public Button skipAllButton;
    public Slider progressSlider;
    
    [Header("애니메이션 컴포넌트")]
    public Animator sceneAnimator;
    public ParticleSystem[] atmosphereParticles;
    
    [Header("오디오 컴포넌트")]
    public AudioSource musicSource;
    public AudioSource sfxSource;
    
    // 내부 상태
    private int currentSequenceIndex = 0;
    private bool isPlaying = false;
    private bool isSequenceComplete = false;
    private bool userWantsToSkip = false;
    private Coroutine currentSequenceCoroutine;
    private Coroutine textAnimationCoroutine;
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            InitializeLaunchOpera();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeLaunchOpera()
    {
        // UI 초기 설정
        SetupInitialUI();
        
        // 이벤트 리스너 등록
        RegisterEventListeners();
        
        // 오디오 초기화
        InitializeAudio();
        
        Debug.Log("런치 오페라 시스템 초기화 완료");
    }
    
    void SetupInitialUI()
    {
        // 초기 UI 상태
        operaCanvas.gameObject.SetActive(true);
        titleText.text = "";
        dialogueText.text = "";
        
        // 버튼 설정
        continueButton.onClick.AddListener(OnContinueClicked);
        skipButton.onClick.AddListener(OnSkipClicked);
        skipAllButton.onClick.AddListener(OnSkipAllClicked);
        
        // 스킵 버튼 표시/숨김
        skipAllButton.gameObject.SetActive(enableSkipAll);
        
        // 진행률 바 초기화
        progressSlider.value = 0f;
        progressSlider.maxValue = operaSequences.Length;
    }
    
    void RegisterEventListeners()
    {
        AppsInToss.OnEvent += HandleAppsInTossEvent;
    }
    
    void InitializeAudio()
    {
        // 오디오 소스 초기 설정
        if (musicSource == null)
            musicSource = gameObject.AddComponent<AudioSource>();
        if (sfxSource == null)
            sfxSource = gameObject.AddComponent<AudioSource>();
        
        musicSource.loop = true;
        sfxSource.loop = false;
    }
    
    void HandleAppsInTossEvent(string eventName, Dictionary<string, object> data)
    {
        switch (eventName)
        {
            case "opera_start":
                StartLaunchOpera();
                break;
            case "opera_sequence_complete":
                OnSequenceComplete();
                break;
            case "opera_user_skip":
                userWantsToSkip = true;
                break;
        }
    }
    
    public void StartLaunchOpera()
    {
        if (isPlaying) return;
        
        isPlaying = true;
        currentSequenceIndex = 0;
        
        Debug.Log("런치 오페라 시작");
        
        // 첫 번째 시퀀스 시작
        StartCurrentSequence();
        
        // 분석 데이터 전송
        SendOperaAnalytics("opera_started", currentSequenceIndex);
    }
    
    void StartCurrentSequence()
    {
        if (currentSequenceIndex >= operaSequences.Length)
        {
            CompleteLaunchOpera();
            return;
        }
        
        var sequence = operaSequences[currentSequenceIndex];
        isSequenceComplete = false;
        userWantsToSkip = false;
        
        Debug.Log($"시퀀스 시작: {sequence.sequenceName}");
        
        // 현재 시퀀스 실행
        if (currentSequenceCoroutine != null)
        {
            StopCoroutine(currentSequenceCoroutine);
        }
        
        currentSequenceCoroutine = StartCoroutine(PlaySequence(sequence));
        
        // 진행률 업데이트
        UpdateProgress();
    }
    
    IEnumerator PlaySequence(OperaSequence sequence)
    {
        // 시퀀스 시작 준비
        yield return StartCoroutine(PrepareSequence(sequence));
        
        // 백그라운드 뮤직 시작
        if (sequence.backgroundMusic != null)
        {
            PlayBackgroundMusic(sequence.backgroundMusic, sequence.musicVolume);
        }
        
        // 시각적 요소 애니메이션
        StartCoroutine(AnimateVisualElements(sequence));
        
        // 대화/텍스트 표시
        yield return StartCoroutine(ShowSequenceText(sequence));
        
        // 사용자 입력 대기 또는 자동 진행
        if (sequence.requiresUserInput)
        {
            yield return StartCoroutine(WaitForUserInput(sequence));
        }
        else if (!sequence.autoAdvance)
        {
            yield return new WaitForSeconds(sequence.duration);
        }
        
        // 시퀀스 완료
        yield return StartCoroutine(CompleteSequence(sequence));
        
        isSequenceComplete = true;
        
        // 다음 시퀀스로 진행
        if (!userWantsToSkip)
        {
            yield return new WaitForSeconds(0.5f);
            NextSequence();
        }
    }
    
    IEnumerator PrepareSequence(OperaSequence sequence)
    {
        // 배경 설정
        if (sequence.backgroundImage != null)
        {
            backgroundImage.sprite = sequence.backgroundImage;
            backgroundImage.color = Color.white;
        }
        else
        {
            backgroundImage.color = sequence.backgroundColor;
        }
        
        // 시각적 요소 초기화
        foreach (var element in sequence.visualElements)
        {
            if (element != null)
            {
                element.SetActive(true);
            }
        }
        
        // 페이드 인 효과
        yield return StartCoroutine(FadeInSequence());
        
        // 분위기 파티클 시작
        StartAtmosphereParticles();
    }
    
    IEnumerator FadeInSequence()
    {
        CanvasGroup canvasGroup = operaCanvas.GetComponent<CanvasGroup>();
        if (canvasGroup == null)
        {
            canvasGroup = operaCanvas.gameObject.AddComponent<CanvasGroup>();
        }
        
        float fadeTime = 0.5f;
        float elapsedTime = 0f;
        
        canvasGroup.alpha = 0f;
        
        while (elapsedTime < fadeTime)
        {
            elapsedTime += Time.deltaTime;
            canvasGroup.alpha = elapsedTime / fadeTime;
            yield return null;
        }
        
        canvasGroup.alpha = 1f;
    }
    
    void StartAtmosphereParticles()
    {
        foreach (var particles in atmosphereParticles)
        {
            if (particles != null && !particles.isPlaying)
            {
                particles.Play();
            }
        }
    }
    
    IEnumerator AnimateVisualElements(OperaSequence sequence)
    {
        // 씬 애니메이터 트리거
        if (sceneAnimator != null && !string.IsNullOrEmpty(sequence.sequenceName))
        {
            sceneAnimator.SetTrigger(sequence.sequenceName);
        }
        
        // 개별 요소 애니메이션
        for (int i = 0; i < sequence.animations.Length && i < sequence.visualElements.Length; i++)
        {
            if (sequence.animations[i] != null && sequence.visualElements[i] != null)
            {
                var elementAnimator = sequence.visualElements[i].GetComponent<Animator>();
                if (elementAnimator != null)
                {
                    elementAnimator.Play(sequence.animations[i].name);
                }
            }
        }
        
        yield return null;
    }
    
    IEnumerator ShowSequenceText(OperaSequence sequence)
    {
        // 제목 표시
        if (!string.IsNullOrEmpty(sequence.title))
        {
            titleText.text = sequence.title;
            yield return StartCoroutine(AnimateTextAppearance(titleText));
        }
        
        // 대화 텍스트 순차 표시
        foreach (var dialogue in sequence.dialogues)
        {
            if (userWantsToSkip) break;
            
            if (sequence.showCharacterByCharacter)
            {
                yield return StartCoroutine(ShowTextCharacterByCharacter(dialogue, sequence.textSpeed));
            }
            else
            {
                dialogueText.text = dialogue;
                yield return StartCoroutine(AnimateTextAppearance(dialogueText));
            }
            
            // 대화 간 대기 시간
            if (sequence.dialogues.Length > 1)
            {
                yield return new WaitForSeconds(1f);
            }
        }
    }
    
    IEnumerator ShowTextCharacterByCharacter(string text, float charactersPerSecond)
    {
        dialogueText.text = "";
        float timePerCharacter = 1f / charactersPerSecond;
        
        for (int i = 0; i <= text.Length; i++)
        {
            if (userWantsToSkip) 
            {
                dialogueText.text = text;
                break;
            }
            
            dialogueText.text = text.Substring(0, i);
            
            // 문장부호에서 약간 더 대기
            if (i < text.Length && (text[i] == '.' || text[i] == '!' || text[i] == '?'))
            {
                yield return new WaitForSeconds(timePerCharacter * 3f);
            }
            else
            {
                yield return new WaitForSeconds(timePerCharacter);
            }
        }
    }
    
    IEnumerator AnimateTextAppearance(TextMeshProUGUI textComponent)
    {
        textComponent.color = new Color(textComponent.color.r, textComponent.color.g, textComponent.color.b, 0f);
        
        float fadeTime = 0.5f;
        float elapsedTime = 0f;
        
        while (elapsedTime < fadeTime)
        {
            if (userWantsToSkip) break;
            
            elapsedTime += Time.deltaTime;
            float alpha = elapsedTime / fadeTime;
            textComponent.color = new Color(textComponent.color.r, textComponent.color.g, textComponent.color.b, alpha);
            
            yield return null;
        }
        
        textComponent.color = new Color(textComponent.color.r, textComponent.color.g, textComponent.color.b, 1f);
    }
    
    IEnumerator WaitForUserInput(OperaSequence sequence)
    {
        // 입력 안내 표시
        continueButton.gameObject.SetActive(true);
        continueButton.GetComponentInChildren<TextMeshProUGUI>().text = sequence.inputPrompt;
        
        bool inputReceived = false;
        
        while (!inputReceived && !userWantsToSkip)
        {
            // 터치/클릭 입력 체크
            if (Input.touchCount > 0 && Input.GetTouch(0).phase == TouchPhase.Began)
            {
                inputReceived = true;
            }
            
            if (Input.GetMouseButtonDown(0))
            {
                inputReceived = true;
            }
            
            // 키보드 입력 체크
            foreach (var key in sequence.skipKeys)
            {
                if (Input.GetKeyDown(key))
                {
                    inputReceived = true;
                    break;
                }
            }
            
            yield return null;
        }
        
        continueButton.gameObject.SetActive(false);
    }
    
    IEnumerator CompleteSequence(OperaSequence sequence)
    {
        // 시퀀스 완료 애니메이션
        yield return StartCoroutine(FadeOutSequence());
        
        // 시각적 요소 정리
        foreach (var element in sequence.visualElements)
        {
            if (element != null)
            {
                element.SetActive(false);
            }
        }
        
        // 분석 데이터 전송
        SendOperaAnalytics("sequence_completed", currentSequenceIndex);
    }
    
    IEnumerator FadeOutSequence()
    {
        CanvasGroup canvasGroup = operaCanvas.GetComponent<CanvasGroup>();
        
        float fadeTime = 0.3f;
        float elapsedTime = 0f;
        
        while (elapsedTime < fadeTime)
        {
            elapsedTime += Time.deltaTime;
            canvasGroup.alpha = 1f - (elapsedTime / fadeTime);
            yield return null;
        }
        
        canvasGroup.alpha = 0f;
        
        // 텍스트 정리
        titleText.text = "";
        dialogueText.text = "";
    }
    
    void PlayBackgroundMusic(AudioClip music, float volume)
    {
        if (musicSource != null && music != null)
        {
            musicSource.clip = music;
            musicSource.volume = volume;
            musicSource.Play();
        }
    }
    
    void PlaySoundEffect(AudioClip sfx)
    {
        if (sfxSource != null && sfx != null)
        {
            sfxSource.PlayOneShot(sfx);
        }
    }
    
    void NextSequence()
    {
        currentSequenceIndex++;
        StartCurrentSequence();
    }
    
    void CompleteLaunchOpera()
    {
        isPlaying = false;
        
        Debug.Log("런치 오페라 완료");
        
        // 완료 애니메이션
        StartCoroutine(PlayCompletionSequence());
    }
    
    IEnumerator PlayCompletionSequence()
    {
        // 모든 UI 페이드 아웃
        CanvasGroup canvasGroup = operaCanvas.GetComponent<CanvasGroup>();
        
        float fadeTime = 1f;
        float elapsedTime = 0f;
        
        while (elapsedTime < fadeTime)
        {
            elapsedTime += Time.deltaTime;
            canvasGroup.alpha = 1f - (elapsedTime / fadeTime);
            yield return null;
        }
        
        operaCanvas.gameObject.SetActive(false);
        
        // 파티클 정리
        foreach (var particles in atmosphereParticles)
        {
            if (particles != null)
            {
                particles.Stop();
            }
        }
        
        // 완료 분석 데이터 전송
        SendOperaAnalytics("opera_completed", operaSequences.Length);
        
        // 게임 시작 신호 전송
        AppsInToss.SendEvent("opera_finished", new Dictionary<string, object>
        {
            {"total_sequences", operaSequences.Length},
            {"completion_time", Time.time}
        });
        
        // 메인 게임 씬으로 전환
        StartMainGame();
    }
    
    void StartMainGame()
    {
        UnityEngine.SceneManagement.SceneManager.LoadScene("GameScene");
    }
    
    void UpdateProgress()
    {
        if (progressSlider != null)
        {
            progressSlider.value = currentSequenceIndex;
        }
    }
    
    void OnContinueClicked()
    {
        // 현재 텍스트 애니메이션이 진행 중이면 즉시 완료
        if (textAnimationCoroutine != null)
        {
            StopCoroutine(textAnimationCoroutine);
            userWantsToSkip = true;
        }
        else if (isSequenceComplete)
        {
            NextSequence();
        }
    }
    
    void OnSkipClicked()
    {
        if (operaSequences[currentSequenceIndex].skippable)
        {
            userWantsToSkip = true;
            
            SendOperaAnalytics("sequence_skipped", currentSequenceIndex);
        }
    }
    
    void OnSkipAllClicked()
    {
        if (enableSkipAll)
        {
            // 모든 시퀀스 건너뛰기
            SendOperaAnalytics("opera_skipped", currentSequenceIndex);
            
            CompleteLaunchOpera();
        }
    }
    
    void SendOperaAnalytics(string eventType, int sequenceIndex)
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"event_type", eventType},
            {"sequence_index", sequenceIndex},
            {"sequence_name", sequenceIndex < operaSequences.Length ? operaSequences[sequenceIndex].sequenceName : "complete"},
            {"play_time", Time.time},
            {"device_model", SystemInfo.deviceModel},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("launch_opera", analyticsData);
    }
    
    // 입력 처리
    void Update()
    {
        // ESC 키로 전체 스킵
        if (Input.GetKeyDown(KeyCode.Escape) && enableSkipAll)
        {
            OnSkipAllClicked();
        }
    }
    
    // 공개 API
    public bool IsPlaying()
    {
        return isPlaying;
    }
    
    public int GetCurrentSequenceIndex()
    {
        return currentSequenceIndex;
    }
    
    public float GetProgress()
    {
        if (operaSequences.Length == 0) return 1f;
        return (float)currentSequenceIndex / operaSequences.Length;
    }
    
    public void PauseOpera()
    {
        if (currentSequenceCoroutine != null)
        {
            StopCoroutine(currentSequenceCoroutine);
        }
        
        if (musicSource != null)
        {
            musicSource.Pause();
        }
    }
    
    public void ResumeOpera()
    {
        if (musicSource != null)
        {
            musicSource.UnPause();
        }
        
        if (!isSequenceComplete)
        {
            StartCurrentSequence();
        }
    }
    
    void OnDestroy()
    {
        AppsInToss.OnEvent -= HandleAppsInTossEvent;
    }
}
```

***

## 2. 스토리 템플릿

### 게임 온보딩 템플릿

```c#
public class GameOnboardingTemplate : MonoBehaviour
{
    [Header("온보딩 단계")]
    public OnboardingStep[] onboardingSteps;
    
    [System.Serializable]
    public class OnboardingStep
    {
        public string stepName;
        public Sprite illustrationImage;
        public string title;
        public string description;
        public bool hasInteraction;
        public UnityEngine.Events.UnityEvent onStepComplete;
    }
    
    public void SetupOnboardingOpera(LaunchOperaManager operaManager)
    {
        var sequences = new List<LaunchOperaManager.OperaSequence>();
        
        foreach (var step in onboardingSteps)
        {
            var sequence = new LaunchOperaManager.OperaSequence
            {
                sequenceName = step.stepName,
                backgroundImage = step.illustrationImage,
                title = step.title,
                dialogues = new string[] { step.description },
                requiresUserInput = step.hasInteraction,
                duration = 3f
            };
            
            sequences.Add(sequence);
        }
        
        operaManager.operaSequences = sequences.ToArray();
    }
}
```

### 브랜드 스토리 템플릿

```c#
public class BrandStoryTemplate : MonoBehaviour
{
    [Header("브랜드 스토리")]
    public BrandStoryElement[] brandElements;
    
    [System.Serializable]
    public class BrandStoryElement
    {
        public string brandMessage;
        public Sprite brandVisual;
        public Color brandColor;
        public AudioClip brandMusic;
        public float displayDuration = 4f;
    }
    
    public void CreateBrandOpera(LaunchOperaManager operaManager)
    {
        var sequences = new List<LaunchOperaManager.OperaSequence>();
        
        // 토스 브랜딩 시퀀스
        var tossSequence = new LaunchOperaManager.OperaSequence
        {
            sequenceName = "TossBranding",
            title = "토스와 함께하는 게임",
            dialogues = new string[] { "토스에서 즐기는 새로운 게임 경험" },
            backgroundColor = new Color(49/255f, 130/255f, 247/255f), // 토스 블루
            duration = 2f,
            autoAdvance = true
        };
        sequences.Add(tossSequence);
        
        // 게임별 브랜드 요소들
        foreach (var element in brandElements)
        {
            var sequence = new LaunchOperaManager.OperaSequence
            {
                sequenceName = "Brand_" + element.brandMessage.Replace(" ", "_"),
                backgroundImage = element.brandVisual,
                backgroundColor = element.brandColor,
                dialogues = new string[] { element.brandMessage },
                backgroundMusic = element.brandMusic,
                duration = element.displayDuration,
                autoAdvance = true
            };
            
            sequences.Add(sequence);
        }
        
        operaManager.operaSequences = sequences.ToArray();
    }
}
```

***

## 3. 인터랙티브 요소

### 터치 인터랙션 시스템

```c#
public class OperaInteractionSystem : MonoBehaviour
{
    [Header("인터랙션 설정")]
    public InteractionType[] interactions;
    
    [System.Serializable]
    public class InteractionType
    {
        public string name;
        public Vector2 screenPosition; // 0-1 범위
        public float radius = 0.1f;
        public Sprite hintIcon;
        public string hintText;
        public UnityEngine.Events.UnityEvent onInteraction;
        public ParticleSystem interactionEffect;
    }
    
    private Camera uiCamera;
    private Canvas interactionCanvas;
    
    void Start()
    {
        uiCamera = Camera.main;
        interactionCanvas = GetComponent<Canvas>();
    }
    
    public void ShowInteractionHint(InteractionType interaction)
    {
        StartCoroutine(AnimateInteractionHint(interaction));
    }
    
    IEnumerator AnimateInteractionHint(InteractionType interaction)
    {
        // 힌트 UI 생성
        var hintObject = CreateInteractionHint(interaction);
        
        // 펄스 애니메이션
        while (hintObject != null)
        {
            yield return StartCoroutine(PulseHint(hintObject.transform));
        }
    }
    
    GameObject CreateInteractionHint(InteractionType interaction)
    {
        var hintObject = new GameObject("InteractionHint");
        hintObject.transform.SetParent(interactionCanvas.transform);
        
        var rectTransform = hintObject.AddComponent<RectTransform>();
        var image = hintObject.AddComponent<Image>();
        
        // 화면 위치 설정
        Vector2 screenPos = new Vector2(
            interaction.screenPosition.x * Screen.width,
            interaction.screenPosition.y * Screen.height
        );
        
        rectTransform.anchoredPosition = screenPos;
        rectTransform.sizeDelta = Vector2.one * 100f;
        
        // 힌트 이미지 설정
        image.sprite = interaction.hintIcon;
        image.color = Color.white;
        
        return hintObject;
    }
    
    IEnumerator PulseHint(Transform hintTransform)
    {
        Vector3 originalScale = Vector3.one;
        Vector3 targetScale = Vector3.one * 1.2f;
        
        float duration = 0.8f;
        float elapsedTime = 0f;
        
        // 확대
        while (elapsedTime < duration / 2f)
        {
            elapsedTime += Time.deltaTime;
            float progress = elapsedTime / (duration / 2f);
            hintTransform.localScale = Vector3.Lerp(originalScale, targetScale, progress);
            yield return null;
        }
        
        elapsedTime = 0f;
        
        // 축소
        while (elapsedTime < duration / 2f)
        {
            elapsedTime += Time.deltaTime;
            float progress = elapsedTime / (duration / 2f);
            hintTransform.localScale = Vector3.Lerp(targetScale, originalScale, progress);
            yield return null;
        }
        
        hintTransform.localScale = originalScale;
    }
    
    void Update()
    {
        HandleTouchInput();
    }
    
    void HandleTouchInput()
    {
        if (Input.touchCount > 0)
        {
            Touch touch = Input.GetTouch(0);
            if (touch.phase == TouchPhase.Began)
            {
                CheckInteractionHit(touch.position);
            }
        }
        
        // 마우스 클릭도 지원 (에디터 테스트용)
        if (Input.GetMouseButtonDown(0))
        {
            CheckInteractionHit(Input.mousePosition);
        }
    }
    
    void CheckInteractionHit(Vector2 inputPosition)
    {
        foreach (var interaction in interactions)
        {
            Vector2 screenPos = new Vector2(
                interaction.screenPosition.x * Screen.width,
                interaction.screenPosition.y * Screen.height
            );
            
            float distance = Vector2.Distance(inputPosition, screenPos);
            float hitRadius = interaction.radius * Screen.width;
            
            if (distance <= hitRadius)
            {
                TriggerInteraction(interaction);
                break;
            }
        }
    }
    
    void TriggerInteraction(InteractionType interaction)
    {
        // 이벤트 실행
        interaction.onInteraction.Invoke();
        
        // 파티클 효과
        if (interaction.interactionEffect != null)
        {
            interaction.interactionEffect.Play();
        }
        
        // 성공 피드백
        StartCoroutine(ShowInteractionSuccess(interaction));
        
        Debug.Log($"인터랙션 트리거: {interaction.name}");
    }
    
    IEnumerator ShowInteractionSuccess(InteractionType interaction)
    {
        // 성공 애니메이션이나 피드백 표시
        yield return new WaitForSeconds(0.5f);
    }
}
```

***

## 4. 성능 최적화

### 오페라 성능 모니터

```c#
public class OperaPerformanceMonitor : MonoBehaviour
{
    private Dictionary<string, float> sequencePerformance = new Dictionary<string, float>();
    private float operaStartTime;
    
    void Start()
    {
        AppsInToss.OnEvent += TrackOperaPerformance;
    }
    
    void TrackOperaPerformance(string eventName, Dictionary<string, object> data)
    {
        if (eventName == "opera_started")
        {
            operaStartTime = Time.realtimeSinceStartup;
        }
        else if (eventName == "sequence_completed")
        {
            int sequenceIndex = (int)data["sequence_index"];
            float duration = Time.realtimeSinceStartup - operaStartTime;
            
            string sequenceName = $"sequence_{sequenceIndex}";
            sequencePerformance[sequenceName] = duration;
            
            // 메모리 사용량 체크
            CheckMemoryUsage(sequenceName);
        }
        else if (eventName == "opera_completed")
        {
            GeneratePerformanceReport();
        }
    }
    
    void CheckMemoryUsage(string sequenceName)
    {
        long memoryUsage = System.GC.GetTotalMemory(false);
        
        var memoryData = new Dictionary<string, object>
        {
            {"sequence_name", sequenceName},
            {"memory_usage_mb", memoryUsage / (1024f * 1024f)},
            {"timestamp", Time.realtimeSinceStartup}
        };
        
        AppsInToss.SendAnalytics("opera_memory_usage", memoryData);
    }
    
    void GeneratePerformanceReport()
    {
        float totalDuration = Time.realtimeSinceStartup - operaStartTime;
        
        var report = new Dictionary<string, object>
        {
            {"total_duration", totalDuration},
            {"sequence_performance", sequencePerformance},
            {"device_model", SystemInfo.deviceModel},
            {"graphics_memory", SystemInfo.graphicsMemorySize},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("opera_performance_report", report);
        
        Debug.Log($"런치 오페라 성능 보고서: 총 {totalDuration:F2}초 소요");
    }
    
    void OnDestroy()
    {
        AppsInToss.OnEvent -= TrackOperaPerformance;
    }
}
```

런치 오페라는 첫인상이 결정되는 중요한 순간이에요.\
사용자의 감정적 몰입을 이끌어내면서도 건너뛸 수 있는 선택권을 제공하여 다양한 사용자 취향을 배려하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/startup-sequence.md
---
# 시작 시간 최적화

앱인토스 Unity 게임의 시작 시간을 최적화하여 사용자 경험을 크게 향상시키는 방법을 제공해요.\
토스 앱 사용자들은 빠른 응답성을 기대하므로 5초 이내 시작을 목표로 해요.

***

## 1. 시작 시간 개요

### 목표 시간 기준

```
🎯 앱인토스 시작 시간 목표
├── Critical (즉시 개선 필요): > 5초
├── Good (권장): 2-3초  
└── Excellent (최적): < 2초
```

### 시작 과정 분석

```tsx
// 앱인토스 Unity 시작 과정
interface StartupPhases {
  tossAppLaunch: number;        // 토스 앱 내 게임 시작: ~0.5초
  appsInTossInit: number;       // 앱인토스 프레임워크 초기화: ~0.3초
  unityEngineInit: number;      // Unity 엔진 초기화: ~1.0초
  gameAssetLoading: number;     // 게임 에셋 로딩: ~1-3초
  firstSceneReady: number;      // 첫 씬 준비 완료: ~0.5초
}

// 각 단계별 최적화 포인트 식별
```

***

## 2. Unity 엔진 최적화

### PlayerSettings 최적화

```c#
// Unity 프로젝트 설정 최적화
public class AppsInTossStartupOptimizer : MonoBehaviour
{
    [Header("시작 최적화 설정")]
    public bool enableFastStartup = true;
    public bool preloadCriticalAssets = true;
    public int maxConcurrentLoads = 3;
    
    [Header("앱인토스 연동")]
    public bool enableTossLogin = true;
    public bool preloadTossServices = false;
    
    void Awake()
    {
        if (enableFastStartup)
        {
            OptimizeStartupSettings();
        }
    }
    
    void OptimizeStartupSettings()
    {
        // 프레임률 제한 설정 (초기 로딩 시)
        Application.targetFrameRate = 30; // 배터리 절약
        
        // Unity 서비스 지연 초기화
        StartCoroutine(DelayedUnityServicesInit());
        
        // 메모리 관리 최적화
        System.GC.Collect();
        Resources.UnloadUnusedAssets();
        
        if (enableTossLogin)
        {
            InitializeTossServices();
        }
    }
    
    IEnumerator DelayedUnityServicesInit()
    {
        // 첫 프레임 렌더링 후 Unity 서비스 초기화
        yield return new WaitForEndOfFrame();
        
        // Analytics, Cloud Build 등 지연 초기화
        InitializeUnityServices();
    }
    
    void InitializeTossServices()
    {
        // 토스 로그인 서비스 사전 초기화
        StartCoroutine(PreloadTossAuthentication());
    }
    
    IEnumerator PreloadTossAuthentication()
    {
        // 토스페이 SDK 사전 로딩
        yield return new WaitForSeconds(0.1f);
        
        // AppsInToss 인증 토큰 검증
        AppsInToss.GetCurrentUserToken((token) => {
            if (!string.IsNullOrEmpty(token))
            {
                Debug.Log("토스 인증 토큰 사전 로딩 완료");
                // 사용자 프로필 캐시 로딩
                StartCoroutine(CacheUserProfile(token));
            }
        });
    }
    
    IEnumerator CacheUserProfile(string token)
    {
        // 사용자 프로필 정보 미리 캐시
        // 게임 플레이 중 빠른 접근을 위함
        yield return null; // 구현 필요
    }
}
```

### 스크립트 실행 순서 최적화

```c#
// 스크립트 실행 순서 정의
[DefaultExecutionOrder(-100)] // 가장 먼저 실행
public class StartupManager : MonoBehaviour
{
    public static StartupManager Instance { get; private set; }
    
    [Header("시작 단계 설정")]
    public StartupPhase[] phases;
    
    [System.Serializable]
    public class StartupPhase
    {
        public string name;
        public UnityEngine.Events.UnityEvent onPhaseStart;
        public UnityEngine.Events.UnityEvent onPhaseComplete;
        public float maxDuration = 5f; // 타임아웃
    }
    
    private int currentPhaseIndex = 0;
    private float phaseStartTime;
    
    void Awake()
    {
        // 싱글톤 패턴
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            StartStartupSequence();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void StartStartupSequence()
    {
        Debug.Log("앱인토스 게임 시작 시퀀스 시작");
        ExecuteNextPhase();
    }
    
    void ExecuteNextPhase()
    {
        if (currentPhaseIndex >= phases.Length)
        {
            OnStartupComplete();
            return;
        }
        
        var phase = phases[currentPhaseIndex];
        Debug.Log($"시작 단계 실행: {phase.name}");
        
        phaseStartTime = Time.realtimeSinceStartup;
        phase.onPhaseStart?.Invoke();
        
        // 타임아웃 설정
        StartCoroutine(PhaseTimeout(phase));
    }
    
    IEnumerator PhaseTimeout(StartupPhase phase)
    {
        yield return new WaitForSeconds(phase.maxDuration);
        
        // 단계가 완료되지 않았다면 강제 진행
        if (currentPhaseIndex < phases.Length)
        {
            Debug.LogWarning($"시작 단계 타임아웃: {phase.name}");
            CompleteCurrentPhase();
        }
    }
    
    public void CompleteCurrentPhase()
    {
        if (currentPhaseIndex >= phases.Length) return;
        
        var phase = phases[currentPhaseIndex];
        float duration = Time.realtimeSinceStartup - phaseStartTime;
        
        Debug.Log($"시작 단계 완료: {phase.name} ({duration:F2}초)");
        
        phase.onPhaseComplete?.Invoke();
        
        // 앱인토스 분석 시스템에 전송
        SendPhaseMetric(phase.name, duration);
        
        currentPhaseIndex++;
        ExecuteNextPhase();
    }
    
    void OnStartupComplete()
    {
        float totalTime = Time.realtimeSinceStartup;
        Debug.Log($"게임 시작 완료! 총 시간: {totalTime:F2}초");
        
        // 앱인토스에 시작 완료 알림
        AppsInToss.ReportGameReady(totalTime);
        
        // 성능 목표 체크
        if (totalTime > 5f)
        {
            Debug.LogWarning($"시작 시간이 목표를 초과했습니다: {totalTime:F2}s > 5s");
            AppsInToss.ReportPerformanceIssue("startup_slow", totalTime);
        }
    }
    
    void SendPhaseMetric(string phaseName, float duration)
    {
        var metric = new Dictionary<string, object>
        {
            {"phase", phaseName},
            {"duration", duration},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("startup_phase", metric);
    }
}
```

***

## 3. 에셋 로딩 최적화

### 핵심 에셋 사전 로딩

```c#
public class CriticalAssetLoader : MonoBehaviour
{
    [Header("필수 에셋 목록")]
    public UnityEngine.Object[] criticalAssets;
    public string[] criticalAddressables;
    
    [Header("앱인토스 특화 에셋")]
    public Texture2D tossPayIcon;
    public AudioClip tossNotificationSound;
    public Font tossFont; // 앱인토스 권장 폰트
    
    private int loadedAssetCount = 0;
    private int totalAssetCount = 0;
    
    public System.Action<float> OnLoadProgress;
    public System.Action OnLoadComplete;
    
    public IEnumerator LoadCriticalAssets()
    {
        totalAssetCount = criticalAssets.Length + criticalAddressables.Length + 3; // 앱인토스 에셋
        loadedAssetCount = 0;
        
        // 1. Unity Resources 에셋 로딩
        foreach (var asset in criticalAssets)
        {
            if (asset != null)
            {
                // 이미 로딩된 에셋은 스킵
                yield return null; // 프레임 분산
                loadedAssetCount++;
                ReportProgress();
            }
        }
        
        // 2. Addressables 에셋 로딩
        foreach (var address in criticalAddressables)
        {
            yield return StartCoroutine(LoadAddressableAsset(address));
        }
        
        // 3. 앱인토스 특화 에셋 로딩
        yield return StartCoroutine(LoadAppsInTossAssets());
        
        OnLoadComplete?.Invoke();
    }
    
    IEnumerator LoadAddressableAsset(string address)
    {
        var handle = Addressables.LoadAssetAsync<UnityEngine.Object>(address);
        
        while (!handle.IsDone)
        {
            yield return null;
        }
        
        if (handle.Status == UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationStatus.Succeeded)
        {
            Debug.Log($"Addressable 에셋 로딩 완료: {address}");
        }
        else
        {
            Debug.LogError($"Addressable 에셋 로딩 실패: {address}");
        }
        
        loadedAssetCount++;
        ReportProgress();
    }
    
    IEnumerator LoadAppsInTossAssets()
    {
        // 토스페이 아이콘 로딩
        if (tossPayIcon == null)
        {
            var iconLoad = Resources.LoadAsync<Texture2D>("AppsInToss/TossPayIcon");
            yield return iconLoad;
            tossPayIcon = iconLoad.asset as Texture2D;
        }
        loadedAssetCount++;
        ReportProgress();
        
        // 토스 알림음 로딩
        if (tossNotificationSound == null)
        {
            var soundLoad = Resources.LoadAsync<AudioClip>("AppsInToss/NotificationSound");
            yield return soundLoad;
            tossNotificationSound = soundLoad.asset as AudioClip;
        }
        loadedAssetCount++;
        ReportProgress();
        
        // 앱인토스 권장 폰트 로딩
        if (tossFont == null)
        {
            var fontLoad = Resources.LoadAsync<Font>("AppsInToss/NotoSansKR");
            yield return fontLoad;
            tossFont = fontLoad.asset as Font;
        }
        loadedAssetCount++;
        ReportProgress();
    }
    
    void ReportProgress()
    {
        float progress = (float)loadedAssetCount / totalAssetCount;
        OnLoadProgress?.Invoke(progress);
        
        // 앱인토스 로딩 진행률 UI 업데이트
        AppsInToss.UpdateLoadingProgress(progress);
    }
}
```

### 점진적 로딩 시스템

```c#
public class ProgressiveLoader : MonoBehaviour
{
    [System.Serializable]
    public class LoadingTier
    {
        public string name;
        public UnityEngine.Object[] assets;
        public int priority; // 낮을수록 우선순위 높음
        public bool loadInBackground = true;
    }
    
    [Header("로딩 단계 설정")]
    public LoadingTier[] loadingTiers;
    
    [Header("앱인토스 연동 설정")]
    public bool showTossLoadingScreen = true;
    public bool enableBackgroundLoading = true;
    
    void Start()
    {
        StartCoroutine(ProgressiveLoadingSequence());
    }
    
    IEnumerator ProgressiveLoadingSequence()
    {
        // 우선순위별로 정렬
        var sortedTiers = loadingTiers.OrderBy(t => t.priority).ToArray();
        
        foreach (var tier in sortedTiers)
        {
            if (tier.priority == 0) // 최우선 에셋은 동기 로딩
            {
                yield return StartCoroutine(LoadTierSync(tier));
            }
            else if (enableBackgroundLoading) // 나머지는 백그라운드 로딩
            {
                StartCoroutine(LoadTierAsync(tier));
            }
        }
    }
    
    IEnumerator LoadTierSync(LoadingTier tier)
    {
        Debug.Log($"동기 로딩 시작: {tier.name}");
        
        foreach (var asset in tier.assets)
        {
            if (asset != null)
            {
                // 에셋 사전 로딩
                yield return null; // 프레임 분산
            }
        }
        
        Debug.Log($"동기 로딩 완료: {tier.name}");
    }
    
    IEnumerator LoadTierAsync(LoadingTier tier)
    {
        Debug.Log($"백그라운드 로딩 시작: {tier.name}");
        
        // 백그라운드 로딩 (게임 플레이에 영향 없음)
        foreach (var asset in tier.assets)
        {
            if (asset != null)
            {
                yield return new WaitForSeconds(0.1f); // 부하 분산
            }
        }
        
        Debug.Log($"백그라운드 로딩 완료: {tier.name}");
    }
}
```

***

## 4. 네트워크 최적화

### 앱인토스 API 사전 초기화

```tsx
// TypeScript - 앱인토스 서비스 사전 초기화
interface AppsInTossPreloadConfig {
    enableUserAuth: boolean;
    enableTossPay: boolean;
    enableAnalytics: boolean;
    cacheUserData: boolean;
}

class AppsInTossPreloader {
    private config: AppsInTossPreloadConfig;
    private preloadPromises: Promise<any>[] = [];
    
    constructor(config: AppsInTossPreloadConfig) {
        this.config = config;
    }
    
    async preloadServices(): Promise<void> {
        console.log('앱인토스 서비스 사전 로딩 시작');
        
        if (this.config.enableUserAuth) {
            this.preloadPromises.push(this.preloadAuthentication());
        }
        
        if (this.config.enableTossPay) {
            this.preloadPromises.push(this.preloadTossPayServices());
        }
        
        if (this.config.enableAnalytics) {
            this.preloadPromises.push(this.preloadAnalyticsServices());
        }
        
        if (this.config.cacheUserData) {
            this.preloadPromises.push(this.preloadUserData());
        }
        
        // 병렬로 모든 서비스 사전 로딩
        await Promise.all(this.preloadPromises);
        console.log('앱인토스 서비스 사전 로딩 완료');
    }
    
    private async preloadAuthentication(): Promise<void> {
        try {
            // 토스 인증 토큰 검증
            const token = await AppsInToss.getCurrentUserToken();
            if (token) {
                console.log('사용자 인증 정보 캐시 완료');
                localStorage.setItem('ait_user_token_cache', token);
            }
        } catch (error) {
            console.warn('인증 정보 사전 로딩 실패:', error);
        }
    }
    
    private async preloadTossPayServices(): Promise<void> {
        try {
            // 토스페이 결제 수단 목록 캐시
            const paymentMethods = await AppsInToss.getAvailablePaymentMethods();
            localStorage.setItem('ait_payment_methods_cache', JSON.stringify(paymentMethods));
            console.log('토스페이 서비스 캐시 완료');
        } catch (error) {
            console.warn('토스페이 서비스 사전 로딩 실패:', error);
        }
    }
    
    private async preloadAnalyticsServices(): Promise<void> {
        try {
            // 분석 서비스 초기화
            await AppsInToss.initializeAnalytics();
            console.log('분석 서비스 초기화 완료');
        } catch (error) {
            console.warn('분석 서비스 초기화 실패:', error);
        }
    }
    
    private async preloadUserData(): Promise<void> {
        try {
            // 사용자 프로필 및 게임 데이터 캐시
            const userProfile = await AppsInToss.getUserProfile();
            const gameData = await AppsInToss.getCloudSaveData();
            
            localStorage.setItem('ait_user_profile_cache', JSON.stringify(userProfile));
            localStorage.setItem('ait_game_data_cache', JSON.stringify(gameData));
            
            console.log('사용자 데이터 캐시 완료');
        } catch (error) {
            console.warn('사용자 데이터 캐시 실패:', error);
        }
    }
}

// Unity WebGL에서 호출할 전역 함수
(window as any).initializeAppsInTossServices = async (configJson: string) => {
    const config = JSON.parse(configJson) as AppsInTossPreloadConfig;
    const preloader = new AppsInTossPreloader(config);
    
    try {
        await preloader.preloadServices();
        // Unity에 완료 알림
        (window as any).unityInstance.SendMessage('StartupManager', 'OnAppsInTossServicesReady', '');
    } catch (error) {
        console.error('앱인토스 서비스 초기화 실패:', error);
        (window as any).unityInstance.SendMessage('StartupManager', 'OnAppsInTossServicesError', error.message);
    }
};
```

***

## 5. 메모리 관리 최적화

### 시작 시 메모리 정리

```c#
public class StartupMemoryManager : MonoBehaviour
{
    [Header("메모리 최적화 설정")]
    public bool enableStartupGC = true;
    public bool unloadUnusedAssets = true;
    public bool optimizeTextureMemory = true;
    
    [Header("앱인토스 메모리 제한")]
    public long maxMemoryUsageMB = 200; // 앱인토스 권장 제한
    
    void Awake()
    {
        if (enableStartupGC)
        {
            StartCoroutine(OptimizeStartupMemory());
        }
    }
    
    IEnumerator OptimizeStartupMemory()
    {
        Debug.Log("시작 시 메모리 최적화 시작");
        
        // 1. 가비지 컬렉션 실행
        if (enableStartupGC)
        {
            System.GC.Collect();
            System.GC.WaitForPendingFinalizers();
            yield return new WaitForSeconds(0.1f);
        }
        
        // 2. 사용하지 않는 에셋 언로드
        if (unloadUnusedAssets)
        {
            var unloadOp = Resources.UnloadUnusedAssets();
            yield return unloadOp;
        }
        
        // 3. 텍스처 메모리 최적화
        if (optimizeTextureMemory)
        {
            OptimizeTextureSettings();
        }
        
        // 4. 메모리 사용량 체크
        CheckMemoryUsage();
        
        Debug.Log("시작 시 메모리 최적화 완료");
    }
    
    void OptimizeTextureSettings()
    {
        // 모바일 환경에 맞는 텍스처 설정 적용
        QualitySettings.masterTextureLimit = 1; // 절반 해상도
        QualitySettings.anisotropicFiltering = AnisotropicFiltering.Disable;
        
        Debug.Log("텍스처 메모리 최적화 적용");
    }
    
    void CheckMemoryUsage()
    {
        long currentMemoryMB = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(false) / (1024 * 1024);
        
        Debug.Log($"현재 메모리 사용량: {currentMemoryMB}MB");
        
        if (currentMemoryMB > maxMemoryUsageMB)
        {
            Debug.LogWarning($"메모리 사용량이 권장 제한을 초과: {currentMemoryMB}MB > {maxMemoryUsageMB}MB");
            
            // 앱인토스에 메모리 경고 리포트
            AppsInToss.ReportPerformanceIssue("high_memory_startup", currentMemoryMB);
            
            // 추가 메모리 정리 시도
            StartCoroutine(AdditionalMemoryCleanup());
        }
    }
    
    IEnumerator AdditionalMemoryCleanup()
    {
        // 더 적극적인 메모리 정리
        Resources.UnloadUnusedAssets();
        System.GC.Collect();
        
        yield return new WaitForSeconds(0.5f);
        
        // 정리 후 재측정
        long newMemoryMB = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(false) / (1024 * 1024);
        Debug.Log($"메모리 정리 후 사용량: {newMemoryMB}MB");
    }
}
```

***

## 6. 시작 화면 최적화

### 앱인토스 로딩 화면 커스터마이징

```c#
public class AppsInTossLoadingScreen : MonoBehaviour
{
    [Header("로딩 화면 설정")]
    public CanvasGroup loadingCanvas;
    public Image progressBar;
    public TextMeshProUGUI loadingText;
    public Image tossLogo;
    
    [Header("앱인토스 브랜딩")]
    public Color tossBlue = new Color(0.196f, 0.510f, 0.965f); // #3182F6
    public Sprite tossIcon;
    public string[] loadingMessages = {
        "토스와 함께하는 게임을 준비하고 있어요",
        "곧 시작됩니다!",
        "로딩 중..."
    };
    
    private int currentMessageIndex = 0;
    
    void Start()
    {
        InitializeLoadingScreen();
        StartCoroutine(AnimateLoadingScreen());
    }
    
    void InitializeLoadingScreen()
    {
        // 앱인토스 브랜드 컬러 적용
        progressBar.color = tossBlue;
        
        if (tossIcon != null)
        {
            tossLogo.sprite = tossIcon;
        }
        
        // 초기 메시지 설정
        if (loadingText != null)
        {
            loadingText.text = loadingMessages[0];
            loadingText.color = tossBlue;
        }
    }
    
    IEnumerator AnimateLoadingScreen()
    {
        // 로딩 메시지 순환 표시
        while (loadingCanvas.alpha > 0)
        {
            yield return new WaitForSeconds(2f);
            
            currentMessageIndex = (currentMessageIndex + 1) % loadingMessages.Length;
            loadingText.text = loadingMessages[currentMessageIndex];
            
            // 부드러운 텍스트 전환 효과
            yield return StartCoroutine(FadeText());
        }
    }
    
    IEnumerator FadeText()
    {
        // 페이드 아웃
        float alpha = 1f;
        while (alpha > 0)
        {
            alpha -= Time.deltaTime * 2f;
            loadingText.alpha = alpha;
            yield return null;
        }
        
        // 페이드 인
        while (alpha < 1)
        {
            alpha += Time.deltaTime * 2f;
            loadingText.alpha = alpha;
            yield return null;
        }
    }
    
    public void UpdateProgress(float progress)
    {
        if (progressBar != null)
        {
            progressBar.fillAmount = Mathf.Clamp01(progress);
        }
        
        // 진행률에 따른 메시지 업데이트
        if (progress > 0.8f && currentMessageIndex < loadingMessages.Length - 1)
        {
            loadingText.text = loadingMessages[loadingMessages.Length - 1];
        }
    }
    
    public void HideLoadingScreen()
    {
        StartCoroutine(FadeOutLoadingScreen());
    }
    
    IEnumerator FadeOutLoadingScreen()
    {
        float alpha = 1f;
        while (alpha > 0)
        {
            alpha -= Time.deltaTime * 3f; // 빠른 페이드아웃
            loadingCanvas.alpha = alpha;
            yield return null;
        }
        
        loadingCanvas.gameObject.SetActive(false);
        
        // 앱인토스에 로딩 완료 알림
        AppsInToss.OnLoadingComplete();
    }
}
```

***

## 7. 성능 모니터링

### 시작 성능 추적 시스템

```c#
public class StartupPerformanceTracker : MonoBehaviour
{
    [System.Serializable]
    public class StartupMetrics
    {
        public float totalStartupTime;
        public float engineInitTime;
        public float assetLoadingTime;
        public float appsInTossInitTime;
        public float firstFrameTime;
        public long peakMemoryUsage;
        public string deviceModel;
        public string osVersion;
    }
    
    private StartupMetrics metrics = new StartupMetrics();
    private float startTime;
    
    void Awake()
    {
        startTime = Time.realtimeSinceStartup;
        StartPerformanceTracking();
    }
    
    void StartPerformanceTracking()
    {
        // 기기 정보 수집
        metrics.deviceModel = SystemInfo.deviceModel;
        metrics.osVersion = SystemInfo.operatingSystem;
        
        StartCoroutine(TrackStartupPerformance());
    }
    
    IEnumerator TrackStartupPerformance()
    {
        // 첫 프레임 시간 측정
        yield return new WaitForEndOfFrame();
        metrics.firstFrameTime = Time.realtimeSinceStartup - startTime;
        
        // 메모리 사용량 추적
        StartCoroutine(TrackMemoryUsage());
        
        // 시작 완료 대기
        yield return new WaitUntil(() => StartupManager.Instance != null && StartupManager.Instance.IsStartupComplete);
        
        // 최종 메트릭 수집
        CollectFinalMetrics();
        
        // 앱인토스 분석 시스템에 전송
        SendStartupMetrics();
    }
    
    IEnumerator TrackMemoryUsage()
    {
        while (!IsStartupComplete())
        {
            long currentMemory = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(false);
            metrics.peakMemoryUsage = System.Math.Max(metrics.peakMemoryUsage, currentMemory);
            
            yield return new WaitForSeconds(0.1f);
        }
    }
    
    void CollectFinalMetrics()
    {
        metrics.totalStartupTime = Time.realtimeSinceStartup - startTime;
        
        Debug.Log($"시작 성능 메트릭:");
        Debug.Log($"  총 시작 시간: {metrics.totalStartupTime:F2}초");
        Debug.Log($"  첫 프레임: {metrics.firstFrameTime:F2}초");
        Debug.Log($"  최대 메모리: {metrics.peakMemoryUsage / (1024*1024)}MB");
        Debug.Log($"  기기: {metrics.deviceModel}");
    }
    
    void SendStartupMetrics()
    {
        var metricsData = new Dictionary<string, object>
        {
            {"total_startup_time", metrics.totalStartupTime},
            {"first_frame_time", metrics.firstFrameTime},
            {"peak_memory_mb", metrics.peakMemoryUsage / (1024f * 1024f)},
            {"device_model", metrics.deviceModel},
            {"os_version", metrics.osVersion},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("startup_performance", metricsData);
        
        // 성능 기준 체크
        if (metrics.totalStartupTime > 5f)
        {
            AppsInToss.ReportPerformanceIssue("startup_slow", metrics.totalStartupTime);
        }
        
        if (metrics.peakMemoryUsage > 200 * 1024 * 1024) // 200MB
        {
            AppsInToss.ReportPerformanceIssue("high_startup_memory", metrics.peakMemoryUsage / (1024f * 1024f));
        }
    }
    
    bool IsStartupComplete()
    {
        return StartupManager.Instance != null && StartupManager.Instance.IsStartupComplete;
    }
}
```

***

## 8. 체크리스트 및 권장사항

### 시작 최적화 체크리스트

* Unity PlayerSettings 최적화 적용
* 스크립트 실행 순서 정의
* 핵심 에셋 사전 로딩 시스템 구현
* 점진적 로딩 시스템 적용
* 앱인토스 API 사전 초기화
* 시작 시 메모리 최적화
* 커스텀 로딩 화면 구현
* 성능 모니터링 시스템 설치
* 목표 시간 5초 이내 달성 확인
* 다양한 기기에서 테스트 완료

### 앱인토스 특화 권장사항

1. **토스페이 연동 대비**: 결제 API 사전 초기화
2. **사용자 인증 최적화**: 토스 로그인 토큰 캐싱
3. **메모리 제한 준수**: 200MB 이하 유지
4. **분석 데이터 활용**: 실제 사용자 시작 시간 모니터링

---

---
url: 'https://developers-apps-in-toss.toss.im/api/overview.md'
description: 앱인토스 API 개요입니다. 사용 가능한 API 목록과 인증 방법을 확인하세요.
---

# 시작하기

앱인토스를 연동하기 위해 필요한 API를 소개드려요.\
앱인토스 개발을 처음 시작하신다면, 좀 더 친절한 안내를 먼저 확인해보세요! ['시작하기' 문서로 바로가기](/prepare/console-workspace)

::: tip 🚨 주의해주세요

iframe은 사용할 수 없어요.\
iframe을 사용할 경우 앱인토스 기능이 정상 동작하지 않고, 내부 보안 심사에서도 반려됩니다.\
단, YouTube 영상 콘텐츠를 삽입하는 용도는 예외적으로 iframe 사용이 가능해요.

:::

## 서버 mTLS 인증서 발급받기

앱인토스 API 사용을 위해서는 필수로 mTLS(mutual TLS, 양방향 인증) 인증서를 설정해야 해요.
이 인증서는 파트너사 서버와 앱인토스 서버 사이의 통신을 암호화하고, 서로 신원을 확인하는 데 사용돼요.\
mTLS 인증서가 준비되지 않으셨다면 [서버 mTLS 인증서 발급받기](/development/integration-process#mtls-인증서-발급-방법)를 확인해주세요.

## 통신 방화벽 확인하기

In/Out Bound 방화벽 관리를 하신다면 아래 IP를 방화벽에 등록해주세요.

**가맹점이 허용해야하는 inbound IP 목록(앱인토스 -> 가맹점)**

|IP|port|
|---|---|
|117.52.3.11|443|
|211.115.96.11|443|
|106.249.5.11|443|
|117.52.3.80~87|443|
|211.115.96.80~87|443|
|106.249.5.80~87|443|

**가맹점이 허용해야하는 outbound IP 목록(가맹점 -> 앱인토스)**
|기능|도메인|IP|port|
|---|---|---|---|
|간편 로그인, 메시지 발송, 토스 포인트 지급|apps-in-toss-api.toss.im|117.52.3.192, 211.115.96.192, 106.249.5.192|443|
|간편 결제|pay-apps-in-toss-api.toss.im|117.52.3.195, 211.115.96.195, 106.249.5.195|443|

## API 공통규격 확인하기

### 도메인 정보

https://apps-in-toss-api.toss.im\
https://pay-apps-in-toss-api.toss.im

### API 공통 응답

**성공**

```json
// 성공일 경우 resultType이 SUCCESS로 설정되며 해당 API의 응답이 success 하위에 적재됩니다.
{
   "resultType":"SUCCESS",
   "success":{
      "sample":"data"
   }
}
```

**실패**

```json
// 실패일 경우 resultType 이 FAIL로 설정되며 해당 실패 사유가 error 하위에 적재됩니다.
{
   "resultType":"FAIL",
   "error":{
      "errorCode":"INVALID_PARAMETER",
      "reason":"요청에 실패했습니다."
   }
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/growth/intro.md'
description: '앱인토스 앱 성장 가이드입니다. 사용자 유입, 리텐션, 바이럴 확산 등 성장의 모든 단계를 설계하는 방법을 확인하세요.'
---

# 시작하기

앱인토스 앱을 성장시키는 방법을 목적과 단계별로 안내하는 가이드예요.\
앱을 출시하고 지표를 성장시키기 위해 활용할 수 있는 기능과 토스의 성공 방정식을 공유해요.

***

앱인토스는 토스팀이 만든 마케팅 툴을 직접 사용하여 만든 서비스를 쉽게 알릴 수 있어요.\
상황과 목적에 맞게 다양한 마케팅 기능을 조합하면 유입부터 리텐션, 확산까지 성장의 모든 단계를 설계할 수 있어요.

![](/assets/growth_intro_1.pKgFGM7h.png)

## 앱 성장 만들기

### 1. 사용자 유입 만들기

앱 성장은 새로운 사용자가 들어오는 순간부터 시작돼요.\
세그먼트 / 푸시, 알림 / 프로모션 / 토스 홈 광고를 활용하면 서비스 이용에 적합한 사람에게 정확한 메시지를 보내고, 첫 경험에서 강한 동기를 줄 수 있어요.\
유입의 문턱을 낮추고 접속 계기를 만드는 것이 핵심이에요.\
[가이드 바로가기](traffic.md)

### 2. 사용자 리텐션 확보하기

한번 들어온 사용자가 계속 머물러야 성장이 이어져요.\
세그먼트 / 푸시, 알림 기능을 사용하면 사용자의 관심사와 행동에 맞춘 메시지를 보낼 수 있어요.\
이탈을 줄이고 꾸준히 관계를 이어 나가는 단계예요.\
[가이드 바로가기](retention.md)

### 3. 공유 기능으로 바이럴 만들기

기존 사용자가 새로운 사용자를 데려오면 성장은 더 빨라져요.\
공유 리워드, 게임 프로필 & 리더보드, 공통 내비게이션 공유하기 기능을 통해 사용자가 성취와 혜택을 자발적으로 나누게 만들 수 있어요.\
이렇게 네트워크 효과가 생기면 앱은 자연스럽게 성장해요.\
[가이드 바로가기](share.md)

### 4. 대시보드로 성장 인사이트 찾기

성장을 이어가려면 현재 상황을 정확히 보는 것이 중요해요.\
대시보드를 통해 유입, 리텐션, 확산 지표를 한눈에 보면 어떤 부분을 강화해야 할지 알 수 있어요.\
데이터는 다음 액션을 정하는 근거가 돼요.\
[가이드 바로가기](insight.md)

::: tip 꾸준한 업데이트가 만드는 성장
지속적인 성장을 위해서는 마케팅뿐만 아니라, 앱을 꾸준히 업데이트하며 관리하는 것이 중요해요.\
콘솔에서는 앱 번들(버전)을 손쉽게 업로드할 수 있어, 새로운 기능이나 혜택을 빠르게 추가하고 개선할 수 있어요.\
주기적으로 앱을 업데이트하면 사용자에게 항상 새로운 경험을 제공하고, 이탈을 줄이며 꾸준한 참여를 유지할 수 있어요.\
:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/위치
  정보/startUpdateLocation.md
---

# 실시간 위치 추적하기

## `startUpdateLocation`

디바이스의 위치 정보를 지속적으로 감지하고, 위치가 변경되면 콜백을 실행하는 함수예요. 콜백 함수를 등록하면 위치가 변경될 때마다 자동으로 호출돼요.
실시간 위치 추적이 필요한 기능을 구현할 때 사용할 수 있어요. 예를 들어 지도 앱에서 사용자의 현재 위치를 실시간으로 업데이트할 때, 운동 앱에서 사용자의 이동 거리를 기록할 때 등이에요.
위치 업데이트 주기와 정확도를 조정해 배터리 소모를 최소화하면서도 필요한 정보를 얻을 수 있어요.

## 시그니처

```typescript
function startUpdateLocation(options: {
  onError: (error: unknown) => void;
  onEvent: (location: Location) => void;
  options: StartUpdateLocationOptions;
}): () => void;
```

### 파라미터

### 프로퍼티

## StartUpdateLocationPermissionError

위치 업데이트 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof StartUpdateLocationPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
StartUpdateLocationPermissionError: typeof GetCurrentLocationPermissionError
```

## 예제

### 위치 정보 변경 감지하기

위치 정보가 변경되는것을 감지하는 예제예요. "위치 정보 변경 감지하기"를 눌러서 감지할 수 있어요.

"권한 확인하기"버튼을 눌러서 현재 위치 정보 변경 감지 권한을 확인해요.
사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`StartUpdateLocationPermissionError`](./StartUpdateLocationPermissionError)를 반환해요.
"권한 요청하기"버튼을 눌러서 위치 정보 변경 감지 권한을 요청할 수 있어요.

::: code-group

```js [js]
import { Accuracy, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/web-framework';

let cleanup;

async function handleStartUpdateLocation() {
  cleanup?.();
  
  cleanup = startUpdateLocation({
    options: {
      accuracy: Accuracy.Balanced,
      timeInterval: 3000,
      distanceInterval: 10,
    },
    onEvent: (location) => {
      console.log(`위도: ${location.coords.latitude}, 경도: ${location.coords.longitude}`);
    },
    onError: (error) => {
      if (error instanceof StartUpdateLocationPermissionError) {
        console.log('위치 정보 변경 감지 권한 없음');
      }
      console.error('위치 정보를 가져오는데 실패했어요:', error);
    },
  });
}

window.addEventListener('pagehide', () => {
  cleanup?.();
});

async function handleGetPermissionForStartUpdateLocation() {
  const permission = await startUpdateLocation.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForStartUpdateLocation() {
  const permission = await startUpdateLocation.openPermissionDialog();
  return permission;
}
```

```tsx [React]
import { Accuracy, Location, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/web-framework';
import { useCallback, useState } from 'react';


// 위치 정보 변경 감지하기
function LocationWatcher() {
  const [location, setLocation] = useState<Location | null>(null);

  const handlePress = useCallback(() => {
    startUpdateLocation({
      options: {
        accuracy: Accuracy.Balanced,
        timeInterval: 3000,
        distanceInterval: 10,
      },
      onEvent: (location) => {
        setLocation(location);
      },
      onError: (error) => {
        if (error instanceof StartUpdateLocationPermissionError) {
          // 위치 정보 변경 감지 권한 없음
        }
        console.error('위치 정보를 가져오는데 실패했어요:', error);
      },
    });
  }, []);

  return (
    <div>
      {location != null && (
        <>
          <span>위도: {location.coords.latitude}</span>
          <span>경도: {location.coords.longitude}</span>
          <span>위치 정확도: {location.coords.accuracy}m</span>
          <span>높이: {location.coords.altitude}m</span>
          <span>고도 정확도: {location.coords.altitudeAccuracy}m</span>
          <span>방향: {location.coords.heading}°</span>
        </>
      )}

      <input type="button" value="위치 정보 변경 감지하기" onClick={handlePress} />

      <input type="button"
        value="권한 확인하기"
        onClick={async () => {
          const permission = await startUpdateLocation.getPermission();
          alert(permission);
        }}
      />
      <input type="button"
        value="권한 요청하기"
        onClick={async () => {
          const permission = await startUpdateLocation.openPermissionDialog();
          alert(permission);
        }}
      />
    </div>
  );
}
```

```tsx [React Native]
import { Accuracy, Location, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/framework';
import { useCallback, useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

// 위치 정보 변경 감지하기
function LocationWatcher() {
  const [location, setLocation] = useState<Location | null>(null);

  const handlePress = useCallback(() => {
    startUpdateLocation({
      options: {
        accuracy: Accuracy.Balanced,
        timeInterval: 3000,
        distanceInterval: 10,
      },
      onEvent: (location) => {
        setLocation(location);
      },
      onError: (error) => {
        if (error instanceof StartUpdateLocationPermissionError) {
          // 위치 정보 변경 감지 권한 없음
        }
        console.error('위치 정보를 가져오는데 실패했어요:', error);
      },
    });
  }, []);

  return (
    <View>
      {location != null && (
        <>
          <Text>위도: {location.coords.latitude}</Text>
          <Text>경도: {location.coords.longitude}</Text>
          <Text>위치 정확도: {location.coords.accuracy}m</Text>
          <Text>높이: {location.coords.altitude}m</Text>
          <Text>고도 정확도: {location.coords.altitudeAccuracy}m</Text>
          <Text>방향: {location.coords.heading}°</Text>
        </>
      )}

      <Button title="위치 정보 변경 감지하기" onPress={handlePress} />

      <Button
        title="권한 확인하기"
        onPress={async () => {
          const permission = await startUpdateLocation.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="권한 요청하기"
        onPress={async () => {
          const permission = await startUpdateLocation.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-location-callback](https://github.com/toss/apps-in-toss-examples/tree/main/with-location-callback) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/환경
  확인/getPlatformOS.md
---

# 실행중인 플랫폼 확인하기

## `getPlatformOS`

`getPlatformOS` 는 현재 실행 중인 플랫폼을 확인하는 함수예요.
이 함수는 `react-native`의 [`Platform.OS`](https://reactnative.dev/docs/0.72/platform#os) 값을 기반으로 동작하며, `ios` 또는 `android` 중 하나의 문자열을 반환해요.

## 시그니처

```typescript
function getPlatformOS(): 'ios' | 'android';
```

### 반환 값

## 예제

### 현재 실행중인 OS 플랫폼 확인하기

```tsx
import { getPlatformOS } from '@apps-in-toss/framework';
import { Text } 'react-native';

function Page() {
  const platform = getPlatformOS();

  return <Text>현재 플랫폼: {platform}</Text>;
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/deep-profile-tool.md
---
# 심화 분석 도구

심화 프로파일링 도구는 앱인토스 미니앱에서 Unity 게임의 성능을 더 세밀하게 분석하고 최적화할 수 있는 전용 도구예요.\
일반 Unity Profiler보다 한 단계 확장돼, WebGL 환경과 토스 앱의 특수한 제약까지 고려한 맞춤형 분석 기능을 제공합니다.

***

## 앱인토스 플랫폼 특화 분석

### 1. WebGL 특화 성능 메트릭

```c#
// Unity C# - 앱인토스 WebGL 프로파일러
using UnityEngine;
using System.Collections.Generic;
using System.Runtime.InteropServices;

public class AITWebGLProfiler : MonoBehaviour
{
    [DllImport("__Internal")]
    private static extern float GetJSHeapUsed();
    
    [DllImport("__Internal")]
    private static extern float GetJSHeapTotal();
    
    [DllImport("__Internal")]
    private static extern int GetWebGLContextLostCount();
    
    [System.Serializable]
    public class WebGLMetrics
    {
        public float jsHeapUsed;        // JavaScript 힙 사용량
        public float jsHeapTotal;       // JavaScript 힙 총량
        public int contextLostCount;    // WebGL 컨텍스트 손실 횟수
        public float wasmMemoryUsage;   // WASM 메모리 사용량
        public int activeTextures;      // 활성 텍스처 수
        public int drawCalls;           // 드로우콜 수
        public float renderThreadTime;  // 렌더링 스레드 시간
    }
    
    private WebGLMetrics currentMetrics;
    private List<WebGLMetrics> metricsHistory;
    
    private void Start()
    {
        metricsHistory = new List<WebGLMetrics>();
        InvokeRepeating(nameof(CollectMetrics), 0f, 0.1f); // 100ms 간격으로 수집
    }
    
    private void CollectMetrics()
    {
        currentMetrics = new WebGLMetrics
        {
            jsHeapUsed = GetJSHeapUsed(),
            jsHeapTotal = GetJSHeapTotal(),
            contextLostCount = GetWebGLContextLostCount(),
            wasmMemoryUsage = GetWASMMemoryUsage(),
            activeTextures = GetActiveTextureCount(),
            drawCalls = GetDrawCallCount(),
            renderThreadTime = GetRenderThreadTime()
        };
        
        metricsHistory.Add(currentMetrics);
        
        // 1000개 이상 쌓이면 오래된 데이터 제거
        if (metricsHistory.Count > 1000)
        {
            metricsHistory.RemoveAt(0);
        }
        
        // 크리티컬 이슈 감지
        DetectCriticalIssues();
    }
    
    private void DetectCriticalIssues()
    {
        // 메모리 누수 감지
        if (currentMetrics.jsHeapUsed > currentMetrics.jsHeapTotal * 0.9f)
        {
            Debug.LogWarning("[AIT Profile] JavaScript 힙 메모리 부족 경고!");
            LogProfileEvent("memory_warning", currentMetrics);
        }
        
        // 과도한 드로우콜 감지
        if (currentMetrics.drawCalls > 500)
        {
            Debug.LogWarning("[AIT Profile] 과도한 드로우콜 감지: " + currentMetrics.drawCalls);
            LogProfileEvent("high_drawcalls", currentMetrics);
        }
        
        // WebGL 컨텍스트 손실 감지
        if (currentMetrics.contextLostCount > 0)
        {
            Debug.LogError("[AIT Profile] WebGL 컨텍스트 손실 발생!");
            LogProfileEvent("context_lost", currentMetrics);
        }
    }
    
    private float GetWASMMemoryUsage()
    {
        // WASM 메모리 사용량 계산
        return UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(UnityEngine.Profiling.Profiler.Area.Total);
    }
    
    private int GetActiveTextureCount()
    {
        return UnityEngine.Rendering.GraphicsSettings.currentRenderPipeline?.GetType().Name == "UniversalRenderPipelineAsset" 
            ? QualitySettings.masterTextureLimit : Texture.currentTextureMemory > 0 ? 1 : 0;
    }
    
    private int GetDrawCallCount()
    {
        return UnityEngine.Profiling.Profiler.GetStatValue(UnityEngine.Profiling.ProfilerArea.Rendering, 
            UnityEngine.Profiling.ProfilerStatisticsNames.DrawCallsCount);
    }
    
    private float GetRenderThreadTime()
    {
        return UnityEngine.Profiling.Profiler.GetStatValue(UnityEngine.Profiling.ProfilerArea.Rendering, 
            UnityEngine.Profiling.ProfilerStatisticsNames.RenderThreadTime);
    }
}
```

### 2. 토스 앱 환경 특화 분석

```c#
// JavaScript 프로파일링 - 토스 앱 통합
class AITTossEnvironmentProfiler {
    constructor() {
        this.metrics = {
            tossAppMemory: 0,
            networkLatency: 0,
            batteryLevel: 0,
            backgroundAppCount: 0,
            deviceTemperature: 0
        };
        
        this.tossAPIResponseTimes = new Map();
        this.startProfiling();
    }
    
    startProfiling() {
        // 토스 앱 메모리 모니터링
        if (window.TossApp && window.TossApp.getMemoryUsage) {
            setInterval(() => {
                this.metrics.tossAppMemory = window.TossApp.getMemoryUsage();
            }, 1000);
        }
        
        // 네트워크 지연시간 모니터링
        this.monitorNetworkLatency();
        
        // 배터리 상태 모니터링
        this.monitorBatteryStatus();
        
        // 백그라운드 앱 모니터링
        this.monitorBackgroundApps();
    }
    
    monitorNetworkLatency() {
        const startTime = performance.now();
        
        // 토스 API 호출 시간 측정
        const originalFetch = window.fetch;
        window.fetch = async (...args) => {
            const requestStart = performance.now();
            
            try {
                const response = await originalFetch.apply(this, args);
                const requestEnd = performance.now();
                const latency = requestEnd - requestStart;
                
                // API별 응답시간 기록
                const url = args[0];
                if (typeof url === 'string' && url.includes('toss.im')) {
                    this.tossAPIResponseTimes.set(url, latency);
                    this.metrics.networkLatency = latency;
                    
                    // 느린 응답 감지
                    if (latency > 3000) {
                        console.warn(`[AIT Profile] 느린 API 응답: ${url} (${latency}ms)`);
                        this.logSlowAPICall(url, latency);
                    }
                }
                
                return response;
            } catch (error) {
                console.error('[AIT Profile] API 호출 실패:', error);
                throw error;
            }
        };
    }
    
    monitorBatteryStatus() {
        if ('getBattery' in navigator) {
            navigator.getBattery().then(battery => {
                this.metrics.batteryLevel = battery.level * 100;
                
                battery.addEventListener('levelchange', () => {
                    this.metrics.batteryLevel = battery.level * 100;
                    
                    // 배터리 부족 시 성능 모드 전환
                    if (this.metrics.batteryLevel < 20) {
                        this.enableBatterySavingMode();
                    }
                });
            });
        }
    }
    
    monitorBackgroundApps() {
        // 페이지 가시성 API를 통한 백그라운드 상태 감지
        document.addEventListener('visibilitychange', () => {
            if (document.hidden) {
                console.log('[AIT Profile] 앱이 백그라운드로 전환됨');
                this.pauseHeavyOperations();
            } else {
                console.log('[AIT Profile] 앱이 포그라운드로 전환됨');
                this.resumeHeavyOperations();
            }
        });
    }
    
    enableBatterySavingMode() {
        // Unity로 배터리 절약 모드 신호 전송
        if (window.unityInstance) {
            window.unityInstance.SendMessage('AITProfiler', 'EnableBatterySavingMode', '');
        }
    }
    
    pauseHeavyOperations() {
        // 무거운 연산 일시정지
        if (window.unityInstance) {
            window.unityInstance.SendMessage('AITProfiler', 'PauseHeavyOperations', '');
        }
    }
    
    resumeHeavyOperations() {
        // 무거운 연산 재개
        if (window.unityInstance) {
            window.unityInstance.SendMessage('AITProfiler', 'ResumeHeavyOperations', '');
        }
    }
    
    logSlowAPICall(url, latency) {
        const logData = {
            timestamp: new Date().toISOString(),
            url: url,
            latency: latency,
            userAgent: navigator.userAgent,
            connectionType: navigator.connection?.effectiveType || 'unknown'
        };
        
        // 앱인토스 분석 서버로 전송
        this.sendAnalyticsData('slow_api_call', logData);
    }
    
    sendAnalyticsData(eventType, data) {
        if (window.AITAnalytics && window.AITAnalytics.trackEvent) {
            window.AITAnalytics.trackEvent(eventType, data);
        }
    }
}
```

***

## 상세 구현 방법

### 1. 실시간 성능 대시보드

```html
<!DOCTYPE html>
<html>
<head>
    <title>앱인토스 심화 프로파일러</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
    <style>
        .profiler-dashboard {
            display: grid;
            grid-template-columns: 1fr 1fr;
            gap: 20px;
            padding: 20px;
            font-family: 'Toss Product Sans', -apple-system, BlinkMacSystemFont, sans-serif;
        }
        
        .metric-card {
            background: white;
            border: 1px solid #e0e0e0;
            border-radius: 12px;
            padding: 16px;
            box-shadow: 0 2px 8px rgba(0,0,0,0.1);
        }
        
        .metric-title {
            font-size: 14px;
            font-weight: 600;
            color: #191f28;
            margin-bottom: 12px;
        }
        
        .metric-value {
            font-size: 24px;
            font-weight: 700;
            color: #3182f6;
        }
        
        .chart-container {
            position: relative;
            height: 200px;
            margin-top: 16px;
        }
        
        .alert-critical {
            background: #fff2f2;
            border-color: #f04452;
            color: #f04452;
        }
        
        .alert-warning {
            background: #fff8f0;
            border-color: #ff8c00;
            color: #ff8c00;
        }
    </style>
</head>
<body>
    <div class="profiler-dashboard">
        <!-- CPU 사용률 -->
        <div class="metric-card">
            <div class="metric-title">CPU 사용률</div>
            <div class="metric-value" id="cpu-usage">0%</div>
            <div class="chart-container">
                <canvas id="cpu-chart"></canvas>
            </div>
        </div>
        
        <!-- 메모리 사용량 -->
        <div class="metric-card">
            <div class="metric-title">메모리 사용량</div>
            <div class="metric-value" id="memory-usage">0 MB</div>
            <div class="chart-container">
                <canvas id="memory-chart"></canvas>
            </div>
        </div>
        
        <!-- GPU 사용률 -->
        <div class="metric-card">
            <div class="metric-title">GPU 사용률</div>
            <div class="metric-value" id="gpu-usage">0%</div>
            <div class="chart-container">
                <canvas id="gpu-chart"></canvas>
            </div>
        </div>
        
        <!-- 네트워크 지연시간 -->
        <div class="metric-card">
            <div class="metric-title">네트워크 지연시간</div>
            <div class="metric-value" id="network-latency">0 ms</div>
            <div class="chart-container">
                <canvas id="network-chart"></canvas>
            </div>
        </div>
        
        <!-- 드로우콜 수 -->
        <div class="metric-card">
            <div class="metric-title">드로우콜</div>
            <div class="metric-value" id="draw-calls">0</div>
            <div class="chart-container">
                <canvas id="drawcalls-chart"></canvas>
            </div>
        </div>
        
        <!-- 배터리 상태 -->
        <div class="metric-card">
            <div class="metric-title">배터리</div>
            <div class="metric-value" id="battery-level">100%</div>
            <div id="battery-status">양호</div>
        </div>
    </div>
    
    <script>
        class AITProfilerDashboard {
            constructor() {
                this.charts = {};
                this.initCharts();
                this.startDataCollection();
            }
            
            initCharts() {
                const chartOptions = {
                    responsive: true,
                    maintainAspectRatio: false,
                    scales: {
                        x: { display: false },
                        y: { 
                            beginAtZero: true,
                            max: 100
                        }
                    },
                    plugins: {
                        legend: { display: false }
                    }
                };
                
                // CPU 차트
                this.charts.cpu = new Chart(document.getElementById('cpu-chart'), {
                    type: 'line',
                    data: {
                        labels: Array.from({length: 50}, (_, i) => i),
                        datasets: [{
                            data: Array(50).fill(0),
                            borderColor: '#3182f6',
                            backgroundColor: 'rgba(49, 130, 246, 0.1)',
                            fill: true,
                            tension: 0.4
                        }]
                    },
                    options: chartOptions
                });
                
                // 메모리 차트
                this.charts.memory = new Chart(document.getElementById('memory-chart'), {
                    type: 'line',
                    data: {
                        labels: Array.from({length: 50}, (_, i) => i),
                        datasets: [{
                            data: Array(50).fill(0),
                            borderColor: '#10b981',
                            backgroundColor: 'rgba(16, 185, 129, 0.1)',
                            fill: true,
                            tension: 0.4
                        }]
                    },
                    options: {
                        ...chartOptions,
                        scales: {
                            ...chartOptions.scales,
                            y: { beginAtZero: true, max: 1000 }
                        }
                    }
                });
                
                // 추가 차트들도 동일한 방식으로 초기화...
            }
            
            startDataCollection() {
                setInterval(() => {
                    this.updateMetrics();
                }, 1000);
            }
            
            updateMetrics() {
                // Unity에서 메트릭 데이터 수집
                if (window.unityInstance) {
                    window.unityInstance.SendMessage('AITProfiler', 'GetCurrentMetrics', '');
                }
                
                // 브라우저 메트릭 수집
                this.collectBrowserMetrics();
            }
            
            collectBrowserMetrics() {
                // 메모리 사용량
                if (performance.memory) {
                    const memoryUsage = Math.round(performance.memory.usedJSHeapSize / 1024 / 1024);
                    this.updateChart('memory', memoryUsage);
                    document.getElementById('memory-usage').textContent = memoryUsage + ' MB';
                }
                
                // CPU 사용률 (근사치)
                const cpuUsage = Math.random() * 100; // 실제로는 더 정교한 계산 필요
                this.updateChart('cpu', cpuUsage);
                document.getElementById('cpu-usage').textContent = Math.round(cpuUsage) + '%';
            }
            
            updateChart(chartName, value) {
                const chart = this.charts[chartName];
                if (chart) {
                    chart.data.datasets[0].data.shift();
                    chart.data.datasets[0].data.push(value);
                    chart.update('none');
                }
            }
            
            // Unity에서 호출되는 메서드들
            updateFromUnity(metricsJson) {
                const metrics = JSON.parse(metricsJson);
                
                // GPU 사용률
                document.getElementById('gpu-usage').textContent = metrics.gpuUsage + '%';
                this.updateChart('gpu', metrics.gpuUsage);
                
                // 드로우콜 수
                document.getElementById('draw-calls').textContent = metrics.drawCalls;
                this.updateChart('drawcalls', metrics.drawCalls);
                
                // 경고 표시
                this.checkThresholds(metrics);
            }
            
            checkThresholds(metrics) {
                // CPU 사용률 경고
                const cpuCard = document.querySelector('#cpu-usage').closest('.metric-card');
                if (metrics.cpuUsage > 80) {
                    cpuCard.classList.add('alert-critical');
                } else if (metrics.cpuUsage > 60) {
                    cpuCard.classList.add('alert-warning');
                } else {
                    cpuCard.classList.remove('alert-critical', 'alert-warning');
                }
                
                // 메모리 사용량 경고
                const memoryCard = document.querySelector('#memory-usage').closest('.metric-card');
                if (metrics.memoryUsage > 500) {
                    memoryCard.classList.add('alert-critical');
                } else if (metrics.memoryUsage > 300) {
                    memoryCard.classList.add('alert-warning');
                } else {
                    memoryCard.classList.remove('alert-critical', 'alert-warning');
                }
            }
        }
        
        // 대시보드 초기화
        window.profileDashboard = new AITProfilerDashboard();
        
        // Unity에서 호출할 수 있도록 전역 함수로 노출
        window.updateProfilerFromUnity = function(metricsJson) {
            window.profileDashboard.updateFromUnity(metricsJson);
        };
    </script>
</body>
</html>
```

### 2. 메모리 누수 탐지기

```c#
// Unity C# - 메모리 누수 탐지
using UnityEngine;
using System.Collections.Generic;
using System.Linq;

public class AITMemoryLeakDetector : MonoBehaviour
{
    [System.Serializable]
    public class MemorySnapshot
    {
        public long totalMemory;
        public long managedMemory;
        public long nativeMemory;
        public long graphicsMemory;
        public long audioMemory;
        public int gameObjectCount;
        public int textureCount;
        public int meshCount;
        public float timestamp;
    }
    
    private List<MemorySnapshot> snapshots = new List<MemorySnapshot>();
    private Dictionary<string, int> objectCounts = new Dictionary<string, int>();
    private float lastSnapshotTime;
    private const float SNAPSHOT_INTERVAL = 10f; // 10초마다 스냅샷
    
    private void Start()
    {
        InvokeRepeating(nameof(TakeMemorySnapshot), 0f, SNAPSHOT_INTERVAL);
        InvokeRepeating(nameof(AnalyzeMemoryLeaks), 30f, 30f); // 30초마다 분석
    }
    
    private void TakeMemorySnapshot()
    {
        var snapshot = new MemorySnapshot
        {
            totalMemory = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(UnityEngine.Profiling.Profiler.Area.Total),
            managedMemory = System.GC.GetTotalMemory(false),
            nativeMemory = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(UnityEngine.Profiling.Profiler.Area.Native),
            graphicsMemory = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(UnityEngine.Profiling.Profiler.Area.Rendering),
            audioMemory = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(UnityEngine.Profiling.Profiler.Area.Audio),
            gameObjectCount = FindObjectsOfType<GameObject>().Length,
            textureCount = Resources.FindObjectsOfTypeAll<Texture>().Length,
            meshCount = Resources.FindObjectsOfTypeAll<Mesh>().Length,
            timestamp = Time.realtimeSinceStartup
        };
        
        snapshots.Add(snapshot);
        
        // 100개 이상 쌓이면 오래된 것 제거
        if (snapshots.Count > 100)
        {
            snapshots.RemoveAt(0);
        }
        
        // 오브젝트 타입별 개수 추적
        TrackObjectCounts();
    }
    
    private void TrackObjectCounts()
    {
        objectCounts.Clear();
        
        // 모든 GameObject 타입 추적
        var allObjects = FindObjectsOfType<MonoBehaviour>();
        foreach (var obj in allObjects)
        {
            string typeName = obj.GetType().Name;
            if (objectCounts.ContainsKey(typeName))
                objectCounts[typeName]++;
            else
                objectCounts[typeName] = 1;
        }
    }
    
    private void AnalyzeMemoryLeaks()
    {
        if (snapshots.Count < 3) return;
        
        var recent = snapshots.Skip(snapshots.Count - 3).Take(3).ToArray();
        
        // 메모리 증가 추세 분석
        bool isIncreasingTrend = true;
        for (int i = 1; i < recent.Length; i++)
        {
            if (recent[i].totalMemory <= recent[i-1].totalMemory)
            {
                isIncreasingTrend = false;
                break;
            }
        }
        
        if (isIncreasingTrend)
        {
            long memoryIncrease = recent[2].totalMemory - recent[0].totalMemory;
            float timeSpan = recent[2].timestamp - recent[0].timestamp;
            long increaseRate = (long)(memoryIncrease / timeSpan); // bytes per second
            
            if (increaseRate > 1024 * 1024) // 1MB/s 이상 증가
            {
                Debug.LogWarning($"[AIT MemLeak] 메모리 누수 의심: {increaseRate / 1024 / 1024} MB/s 증가");
                LogMemoryLeakWarning(increaseRate, recent);
            }
        }
        
        // GameObject 수 급증 감지
        DetectObjectCountSpikes();
        
        // 텍스처 메모리 누수 감지
        DetectTextureLeaks(recent);
    }
    
    private void DetectObjectCountSpikes()
    {
        if (snapshots.Count < 5) return;
        
        var lastFive = snapshots.Skip(snapshots.Count - 5).ToArray();
        var avgObjectCount = lastFive.Take(4).Average(s => s.gameObjectCount);
        var currentCount = lastFive[4].gameObjectCount;
        
        if (currentCount > avgObjectCount * 1.5f) // 50% 이상 급증
        {
            Debug.LogWarning($"[AIT MemLeak] GameObject 급증 감지: {currentCount} (평균: {avgObjectCount:F0})");
            
            // 어떤 타입의 오브젝트가 증가했는지 분석
            AnalyzeObjectTypeIncrease();
        }
    }
    
    private void AnalyzeObjectTypeIncrease()
    {
        // 이전 프레임의 오브젝트 카운트와 비교 (간단한 구현을 위해 생략)
        foreach (var kvp in objectCounts.OrderByDescending(x => x.Value).Take(10))
        {
            Debug.Log($"[AIT MemLeak] {kvp.Key}: {kvp.Value} 개");
        }
    }
    
    private void DetectTextureLeaks(MemorySnapshot[] recent)
    {
        // 텍스처 메모리 지속적 증가 감지
        bool textureMemoryIncreasing = true;
        for (int i = 1; i < recent.Length; i++)
        {
            // 그래픽 메모리 증가 추세 확인
            if (recent[i].graphicsMemory <= recent[i-1].graphicsMemory)
            {
                textureMemoryIncreasing = false;
                break;
            }
        }
        
        if (textureMemoryIncreasing)
        {
            long textureIncrease = recent[2].graphicsMemory - recent[0].graphicsMemory;
            if (textureIncrease > 10 * 1024 * 1024) // 10MB 이상 증가
            {
                Debug.LogWarning($"[AIT MemLeak] 텍스처 메모리 누수 의심: {textureIncrease / 1024 / 1024} MB 증가");
                
                // 활성 텍스처 분석
                AnalyzeActiveTextures();
            }
        }
    }
    
    private void AnalyzeActiveTextures()
    {
        var textures = Resources.FindObjectsOfTypeAll<Texture>();
        var textureInfo = new Dictionary<string, int>();
        
        foreach (var texture in textures)
        {
            string key = $"{texture.GetType().Name}_{texture.width}x{texture.height}";
            if (textureInfo.ContainsKey(key))
                textureInfo[key]++;
            else
                textureInfo[key] = 1;
        }
        
        Debug.Log("[AIT MemLeak] 활성 텍스처 분석:");
        foreach (var kvp in textureInfo.OrderByDescending(x => x.Value).Take(10))
        {
            Debug.Log($"  {kvp.Key}: {kvp.Value} 개");
        }
    }
    
    private void LogMemoryLeakWarning(long increaseRate, MemorySnapshot[] snapshots)
    {
        var leakInfo = new
        {
            increaseRate = increaseRate,
            totalMemory = snapshots[2].totalMemory,
            managedMemory = snapshots[2].managedMemory,
            nativeMemory = snapshots[2].nativeMemory,
            timestamp = System.DateTime.Now.ToString(),
            gameObjectCount = snapshots[2].gameObjectCount,
            textureCount = snapshots[2].textureCount
        };
        
        // JSON으로 직렬화하여 JavaScript에 전달
        string json = JsonUtility.ToJson(leakInfo);
        
        #if UNITY_WEBGL && !UNITY_EDITOR
        Application.ExternalCall("logMemoryLeak", json);
        #endif
    }
    
    public MemorySnapshot GetCurrentSnapshot()
    {
        return snapshots.LastOrDefault();
    }
    
    public List<MemorySnapshot> GetSnapshotHistory(int count = 10)
    {
        return snapshots.Skip(Mathf.Max(0, snapshots.Count - count)).ToList();
    }
}
```

***

## 코드 예제 및 설정

### 1. 성능 임계값 설정

```json
// ait-profile-config.json
{
    "thresholds": {
        "cpu": {
            "warning": 60,
            "critical": 80,
            "unit": "percent"
        },
        "memory": {
            "warning": 300,
            "critical": 500,
            "unit": "MB"
        },
        "drawCalls": {
            "warning": 200,
            "critical": 500,
            "unit": "count"
        },
        "frameRate": {
            "warning": 30,
            "critical": 15,
            "unit": "fps"
        },
        "networkLatency": {
            "warning": 1000,
            "critical": 3000,
            "unit": "ms"
        },
        "batteryDrain": {
            "warning": 10,
            "critical": 20,
            "unit": "percent_per_hour"
        }
    },
    "alerting": {
        "enabled": true,
        "channels": ["console", "remote", "unity"],
        "remoteEndpoint": "https://analytics.apps-in-toss.io/alerts"
    },
    "sampling": {
        "metricsInterval": 100,
        "snapshotInterval": 10000,
        "historyLimit": 1000
    }
}
```

### 2. 자동화된 성능 테스트

```c#
// Unity C# - 성능 테스트 자동화
using UnityEngine;
using System.Collections;
using System.Collections.Generic;

public class AITPerformanceTestSuite : MonoBehaviour
{
    [System.Serializable]
    public class PerformanceTest
    {
        public string testName;
        public System.Action testAction;
        public float expectedFrameRate;
        public long maxMemoryUsage;
        public int maxDrawCalls;
        public float timeoutSeconds;
    }
    
    private List<PerformanceTest> tests = new List<PerformanceTest>();
    private AITWebGLProfiler profiler;
    
    private void Start()
    {
        profiler = GetComponent<AITWebGLProfiler>();
        SetupPerformanceTests();
        StartCoroutine(RunAllTests());
    }
    
    private void SetupPerformanceTests()
    {
        // GPU 스트레스 테스트
        tests.Add(new PerformanceTest
        {
            testName = "GPU 스트레스 테스트",
            testAction = () => StartCoroutine(GPUStressTest()),
            expectedFrameRate = 30f,
            maxMemoryUsage = 200 * 1024 * 1024, // 200MB
            maxDrawCalls = 300,
            timeoutSeconds = 30f
        });
        
        // 메모리 할당 테스트
        tests.Add(new PerformanceTest
        {
            testName = "메모리 할당 테스트",
            testAction = () => StartCoroutine(MemoryAllocationTest()),
            expectedFrameRate = 45f,
            maxMemoryUsage = 150 * 1024 * 1024, // 150MB
            maxDrawCalls = 100,
            timeoutSeconds = 20f
        });
        
        // 네트워크 부하 테스트
        tests.Add(new PerformanceTest
        {
            testName = "네트워크 부하 테스트",
            testAction = () => StartCoroutine(NetworkLoadTest()),
            expectedFrameRate = 50f,
            maxMemoryUsage = 100 * 1024 * 1024, // 100MB
            maxDrawCalls = 50,
            timeoutSeconds = 15f
        });
    }
    
    private IEnumerator RunAllTests()
    {
        Debug.Log("[AIT PerfTest] 성능 테스트 시작");
        
        foreach (var test in tests)
        {
            Debug.Log($"[AIT PerfTest] 실행 중: {test.testName}");
            
            var startSnapshot = profiler.GetCurrentSnapshot();
            float startTime = Time.realtimeSinceStartup;
            
            test.testAction.Invoke();
            
            // 테스트 완료까지 대기 (타임아웃 고려)
            float elapsedTime = 0f;
            while (elapsedTime < test.timeoutSeconds)
            {
                yield return new WaitForSeconds(0.1f);
                elapsedTime = Time.realtimeSinceStartup - startTime;
                
                // 테스트별 종료 조건 확인
                if (IsTestCompleted(test))
                    break;
            }
            
            var endSnapshot = profiler.GetCurrentSnapshot();
            EvaluateTestResult(test, startSnapshot, endSnapshot);
            
            // 테스트 간 정리 시간
            yield return new WaitForSeconds(2f);
        }
        
        Debug.Log("[AIT PerfTest] 모든 성능 테스트 완료");
        GenerateTestReport();
    }
    
    private IEnumerator GPUStressTest()
    {
        // 대량의 파티클 생성
        GameObject particleContainer = new GameObject("ParticleStressTest");
        
        for (int i = 0; i < 10; i++)
        {
            GameObject particles = new GameObject($"Particles_{i}");
            particles.transform.parent = particleContainer.transform;
            
            var particleSystem = particles.AddComponent<ParticleSystem>();
            var main = particleSystem.main;
            main.maxParticles = 1000;
            main.startLifetime = 5f;
            
            yield return new WaitForSeconds(0.1f);
        }
        
        // 5초간 실행
        yield return new WaitForSeconds(5f);
        
        // 정리
        DestroyImmediate(particleContainer);
    }
    
    private IEnumerator MemoryAllocationTest()
    {
        List<Texture2D> textures = new List<Texture2D>();
        
        // 텍스처 대량 생성
        for (int i = 0; i < 50; i++)
        {
            var texture = new Texture2D(512, 512);
            textures.Add(texture);
            yield return null;
        }
        
        // 3초 대기
        yield return new WaitForSeconds(3f);
        
        // 메모리 해제
        foreach (var texture in textures)
        {
            DestroyImmediate(texture);
        }
        
        // 가비지 컬렉션 강제 실행
        System.GC.Collect();
        Resources.UnloadUnusedAssets();
    }
    
    private IEnumerator NetworkLoadTest()
    {
        // 동시 다중 네트워크 요청
        for (int i = 0; i < 10; i++)
        {
            StartCoroutine(SimulateNetworkRequest($"test_request_{i}"));
            yield return new WaitForSeconds(0.1f);
        }
        
        yield return new WaitForSeconds(5f);
    }
    
    private IEnumerator SimulateNetworkRequest(string requestId)
    {
        // 네트워크 요청 시뮬레이션
        float delay = Random.Range(0.5f, 2f);
        yield return new WaitForSeconds(delay);
        
        Debug.Log($"[AIT PerfTest] 네트워크 요청 완료: {requestId}");
    }
    
    private bool IsTestCompleted(PerformanceTest test)
    {
        // 테스트별 완료 조건 확인 로직
        return true; // 단순화
    }
    
    private void EvaluateTestResult(PerformanceTest test, 
        AITWebGLProfiler.WebGLMetrics start, AITWebGLProfiler.WebGLMetrics end)
    {
        bool passed = true;
        List<string> failures = new List<string>();
        
        // 프레임레이트 확인
        float currentFPS = 1f / Time.deltaTime;
        if (currentFPS < test.expectedFrameRate)
        {
            passed = false;
            failures.Add($"낮은 FPS: {currentFPS:F1} < {test.expectedFrameRate}");
        }
        
        // 메모리 사용량 확인
        if (end.jsHeapUsed > test.maxMemoryUsage)
        {
            passed = false;
            failures.Add($"메모리 초과: {end.jsHeapUsed} > {test.maxMemoryUsage}");
        }
        
        // 드로우콜 수 확인
        if (end.drawCalls > test.maxDrawCalls)
        {
            passed = false;
            failures.Add($"드로우콜 초과: {end.drawCalls} > {test.maxDrawCalls}");
        }
        
        string result = passed ? "통과" : "실패";
        Debug.Log($"[AIT PerfTest] {test.testName}: {result}");
        
        if (!passed)
        {
            foreach (var failure in failures)
            {
                Debug.LogWarning($"  - {failure}");
            }
        }
    }
    
    private void GenerateTestReport()
    {
        var report = new
        {
            timestamp = System.DateTime.Now.ToString(),
            testCount = tests.Count,
            platform = Application.platform.ToString(),
            unityVersion = Application.unityVersion,
            deviceInfo = SystemInfo.deviceModel,
            results = "상세 결과는 콘솔 로그 참조"
        };
        
        string json = JsonUtility.ToJson(report, true);
        Debug.Log($"[AIT PerfTest] 테스트 리포트:\n{json}");
        
        #if UNITY_WEBGL && !UNITY_EDITOR
        Application.ExternalCall("savePerformanceTestReport", json);
        #endif
    }
}
```

***

## 문제 해결 및 디버깅

### 1. 일반적인 성능 문제 진단

```c#
// Unity C# - 성능 문제 진단기
public class AITPerformanceDiagnostic : MonoBehaviour
{
    public enum PerformanceIssue
    {
        HighCPUUsage,
        MemoryLeak,
        ExcessiveDrawCalls,
        LowFrameRate,
        NetworkLatency,
        BatteryDrain
    }
    
    private Dictionary<PerformanceIssue, System.Action> diagnosticActions;
    
    private void Start()
    {
        InitializeDiagnostics();
    }
    
    private void InitializeDiagnostics()
    {
        diagnosticActions = new Dictionary<PerformanceIssue, System.Action>
        {
            { PerformanceIssue.HighCPUUsage, DiagnoseCPUUsage },
            { PerformanceIssue.MemoryLeak, DiagnoseMemoryLeaks },
            { PerformanceIssue.ExcessiveDrawCalls, DiagnoseDrawCalls },
            { PerformanceIssue.LowFrameRate, DiagnoseFrameRate },
            { PerformanceIssue.NetworkLatency, DiagnoseNetworkIssues },
            { PerformanceIssue.BatteryDrain, DiagnoseBatteryDrain }
        };
    }
    
    public void RunDiagnostic(PerformanceIssue issue)
    {
        Debug.Log($"[AIT Diagnostic] {issue} 진단 시작");
        
        if (diagnosticActions.ContainsKey(issue))
        {
            diagnosticActions[issue].Invoke();
        }
    }
    
    private void DiagnoseCPUUsage()
    {
        Debug.Log("[AIT Diagnostic] CPU 사용률 분석");
        
        // 프로파일러 데이터 분석
        var renderTime = UnityEngine.Profiling.Profiler.GetStatValue(
            UnityEngine.Profiling.ProfilerArea.Rendering, 
            UnityEngine.Profiling.ProfilerStatisticsNames.RenderThreadTime);
            
        var mainTime = UnityEngine.Profiling.Profiler.GetStatValue(
            UnityEngine.Profiling.ProfilerArea.CPU,
            UnityEngine.Profiling.ProfilerStatisticsNames.MainThreadTime);
        
        Debug.Log($"  렌더링 시간: {renderTime}ms");
        Debug.Log($"  메인 스레드 시간: {mainTime}ms");
        
        // CPU 집약적 작업 감지
        if (renderTime > 16.67f) // 60fps 기준
        {
            Debug.LogWarning("  렌더링 성능 문제 감지");
            SuggestRenderingOptimizations();
        }
        
        if (mainTime > 16.67f)
        {
            Debug.LogWarning("  메인 스레드 성능 문제 감지");
            SuggestMainThreadOptimizations();
        }
    }
    
    private void SuggestRenderingOptimizations()
    {
        Debug.Log("[AIT Suggestion] 렌더링 최적화 권장사항:");
        Debug.Log("  - 드로우콜 수 줄이기 (배칭 활용)");
        Debug.Log("  - 텍스처 아틀라스 사용");
        Debug.Log("  - LOD (Level of Detail) 구현");
        Debug.Log("  - 오클루전 컬링 활성화");
        Debug.Log("  - 쉐이더 복잡도 검토");
    }
    
    private void SuggestMainThreadOptimizations()
    {
        Debug.Log("[AIT Suggestion] 메인 스레드 최적화 권장사항:");
        Debug.Log("  - 무거운 연산을 코루틴으로 분할");
        Debug.Log("  - 오브젝트 풀링 사용");
        Debug.Log("  - Update 호출 최적화");
        Debug.Log("  - 가비지 컬렉션 최소화");
    }
    
    private void DiagnoseMemoryLeaks()
    {
        Debug.Log("[AIT Diagnostic] 메모리 누수 분석");
        
        // 현재 메모리 상태
        long totalMemory = System.GC.GetTotalMemory(false);
        long managedMemory = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(
            UnityEngine.Profiling.Profiler.Area.Total);
        
        Debug.Log($"  총 메모리: {totalMemory / 1024 / 1024} MB");
        Debug.Log($"  관리 메모리: {managedMemory / 1024 / 1024} MB");
        
        // 리소스 개수 확인
        var gameObjects = FindObjectsOfType<GameObject>().Length;
        var textures = Resources.FindObjectsOfTypeAll<Texture>().Length;
        var meshes = Resources.FindObjectsOfTypeAll<Mesh>().Length;
        
        Debug.Log($"  GameObject 수: {gameObjects}");
        Debug.Log($"  텍스처 수: {textures}");
        Debug.Log($"  메시 수: {meshes}");
        
        // 의심스러운 수치 감지
        if (gameObjects > 1000)
        {
            Debug.LogWarning("  GameObject 수 과다 - 오브젝트 풀링 고려");
        }
        
        if (textures > 100)
        {
            Debug.LogWarning("  텍스처 수 과다 - 텍스처 아틀라스 고려");
        }
    }
    
    private void DiagnoseDrawCalls()
    {
        Debug.Log("[AIT Diagnostic] 드로우콜 분석");
        
        var drawCalls = UnityEngine.Profiling.Profiler.GetStatValue(
            UnityEngine.Profiling.ProfilerArea.Rendering,
            UnityEngine.Profiling.ProfilerStatisticsNames.DrawCallsCount);
        
        var batches = UnityEngine.Profiling.Profiler.GetStatValue(
            UnityEngine.Profiling.ProfilerArea.Rendering,
            UnityEngine.Profiling.ProfilerStatisticsNames.BatchesCount);
        
        Debug.Log($"  드로우콜 수: {drawCalls}");
        Debug.Log($"  배치 수: {batches}");
        
        if (drawCalls > 200)
        {
            Debug.LogWarning("  드로우콜 수 과다");
            Debug.Log("  권장사항: 스태틱 배칭, 동적 배칭, GPU 인스턴싱 활용");
        }
        
        float batchingEfficiency = batches > 0 ? (float)drawCalls / batches : 0;
        Debug.Log($"  배칭 효율성: {batchingEfficiency:F2}");
    }
    
    private void DiagnoseFrameRate()
    {
        Debug.Log("[AIT Diagnostic] 프레임레이트 분석");
        
        float currentFPS = 1f / Time.deltaTime;
        float targetFPS = Application.targetFrameRate > 0 ? Application.targetFrameRate : 60;
        
        Debug.Log($"  현재 FPS: {currentFPS:F1}");
        Debug.Log($"  목표 FPS: {targetFPS}");
        
        if (currentFPS < targetFPS * 0.8f) // 80% 이하
        {
            Debug.LogWarning("  프레임레이트 저하 감지");
            
            // 원인 분석
            AnalyzeFrameRateBottlenecks();
        }
    }
    
    private void AnalyzeFrameRateBottlenecks()
    {
        Debug.Log("  프레임레이트 저하 원인 분석:");
        
        // CPU vs GPU 바운드 확인
        var cpuTime = UnityEngine.Profiling.Profiler.GetStatValue(
            UnityEngine.Profiling.ProfilerArea.CPU,
            UnityEngine.Profiling.ProfilerStatisticsNames.MainThreadTime);
            
        var gpuTime = UnityEngine.Profiling.Profiler.GetStatValue(
            UnityEngine.Profiling.ProfilerArea.Rendering,
            UnityEngine.Profiling.ProfilerStatisticsNames.RenderThreadTime);
        
        if (cpuTime > gpuTime)
        {
            Debug.Log("  - CPU 바운드: 스크립트 최적화 필요");
        }
        else
        {
            Debug.Log("  - GPU 바운드: 그래픽 최적화 필요");
        }
    }
    
    private void DiagnoseNetworkIssues()
    {
        Debug.Log("[AIT Diagnostic] 네트워크 성능 분석");
        
        // 네트워크 상태 확인 (WebGL에서는 제한적)
        #if UNITY_WEBGL && !UNITY_EDITOR
        Application.ExternalCall("analyzeNetworkPerformance");
        #endif
        
        Debug.Log("  네트워크 최적화 권장사항:");
        Debug.Log("  - 요청 크기 최소화");
        Debug.Log("  - 압축 활용");
        Debug.Log("  - 캐싱 전략 구현");
        Debug.Log("  - 연결 재사용");
    }
    
    private void DiagnoseBatteryDrain()
    {
        Debug.Log("[AIT Diagnostic] 배터리 소모 분석");
        
        // 배터리 소모 주요 원인들 분석
        Debug.Log("  배터리 소모 최적화 권장사항:");
        Debug.Log("  - 프레임레이트 제한 (30fps 고려)");
        Debug.Log("  - 백그라운드에서 업데이트 중단");
        Debug.Log("  - 불필요한 센서 사용 중단");
        Debug.Log("  - 네트워크 요청 최소화");
        Debug.Log("  - 화면 밝기 고려한 UI 디자인");
    }
}
```

***

## 모범 사례

### 1. 지속적 성능 모니터링

```c#
// 프로덕션 환경에서의 성능 모니터링
public class AITProductionProfiler : MonoBehaviour
{
    private const float REPORT_INTERVAL = 300f; // 5분마다 리포트
    private bool isMonitoring = false;
    
    private void Start()
    {
        // 프로덕션 환경에서만 활성화
        if (Application.isEditor || Debug.isDebugBuild)
            return;
            
        StartCoroutine(MonitorPerformance());
    }
    
    private IEnumerator MonitorPerformance()
    {
        isMonitoring = true;
        
        while (isMonitoring)
        {
            // 경량화된 성능 메트릭 수집
            var metrics = CollectLightweightMetrics();
            
            // 임계값 초과 시에만 전송
            if (ShouldReportMetrics(metrics))
            {
                SendMetricsToAnalytics(metrics);
            }
            
            yield return new WaitForSeconds(REPORT_INTERVAL);
        }
    }
    
    private PerformanceMetrics CollectLightweightMetrics()
    {
        return new PerformanceMetrics
        {
            fps = Mathf.RoundToInt(1f / Time.deltaTime),
            memoryUsage = System.GC.GetTotalMemory(false),
            loadTime = Time.realtimeSinceStartup,
            sessionDuration = Time.time,
            crashCount = 0, // 크래시 추적 시스템 필요
            platform = Application.platform.ToString()
        };
    }
    
    private bool ShouldReportMetrics(PerformanceMetrics metrics)
    {
        // 성능 이슈가 있을 때만 전송
        return metrics.fps < 20 || 
               metrics.memoryUsage > 500 * 1024 * 1024; // 500MB
    }
    
    private void SendMetricsToAnalytics(PerformanceMetrics metrics)
    {
        string json = JsonUtility.ToJson(metrics);
        
        #if UNITY_WEBGL && !UNITY_EDITOR
        Application.ExternalCall("sendPerformanceMetrics", json);
        #endif
    }
}
```

### 2. 성능 최적화 우선순위 가이드

1. 메모리 최적화 (최우선)
   * WebGL 환경에서 메모리는 가장 제한적인 리소스
   * 가비지 컬렉션 최소화가 핵심

2. 드로우콜 최적화
   * 배칭을 통한 드로우콜 감소
   * 텍스처 아틀라스 활용

3. CPU 최적화
   * Update 호출 최적화
   * 코루틴을 통한 작업 분산

4. 네트워크 최적화
   * 요청 크기 및 빈도 최적화
   * 캐싱 전략 구현

이러한 심화 프로파일링 도구를 통해 개발자는 앱인토스 플랫폼의 특성을 고려한 정밀한 성능 분석과 최적화를 수행할 수 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/runtime/compressed-texture.md
description: Unity 앱인토스 미니앱 런타임 최적화 가이드입니다. 실행 중 성능 및 메모리 최적화 방법을 확인하세요.
---

# 압축 텍스처 최적화

앱인토스 Unity 게임에서 텍스처 압축을 통해 메모리 사용량을 줄이고 로딩 성능을 향상시키는 방법을 다뤄요.

## 1. 텍스처 압축 전략

### 앱인토스 텍스처 압축 매니저

```c#
using UnityEngine;
using System.Collections;
using System.Collections.Generic;

public class TextureCompressionManager : MonoBehaviour
{
    public static TextureCompressionManager Instance { get; private set; }
    
    [System.Serializable]
    public class CompressionProfile
    {
        [Header("압축 설정")]
        public string profileName;
        public TextureImporterCompression compressionType;
        public int compressionQuality = 50;
        public bool generateMipMaps = true;
        
        [Header("해상도 설정")]
        public int maxTextureSize = 1024;
        public bool enableResolutionFallback = true;
        
        [Header("플랫폼별 설정")]
        public PlatformSettings[] platformSettings;
    }
    
    [System.Serializable]
    public class PlatformSettings
    {
        public RuntimePlatform platform;
        public TextureFormat preferredFormat;
        public int maxSize;
        public int compressionQuality;
    }
    
    [Header("압축 프로필")]
    public CompressionProfile[] compressionProfiles;
    
    [Header("실시간 압축 설정")]
    public bool enableRuntimeCompression = true;
    public bool enableAdaptiveQuality = true;
    public float memoryThresholdMB = 100f;
    
    // 내부 상태
    private Dictionary<string, CompressionProfile> profileMap;
    private Dictionary<Texture2D, TextureFormat> originalFormats;
    private Queue<Texture2D> compressionQueue;
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeCompressionSystem();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeCompressionSystem()
    {
        profileMap = new Dictionary<string, CompressionProfile>();
        originalFormats = new Dictionary<Texture2D, TextureFormat>();
        compressionQueue = new Queue<Texture2D>();
        
        foreach (var profile in compressionProfiles)
        {
            profileMap[profile.profileName] = profile;
        }
        
        // 메모리 모니터링 시작
        if (enableRuntimeCompression)
        {
            StartCoroutine(MonitorMemoryAndCompress());
        }
        
        Debug.Log("텍스처 압축 시스템 초기화 완료");
    }
    
    IEnumerator MonitorMemoryAndCompress()
    {
        while (enabled)
        {
            float currentMemoryMB = System.GC.GetTotalMemory(false) / (1024f * 1024f);
            
            if (currentMemoryMB > memoryThresholdMB)
            {
                yield return StartCoroutine(CompressLargeTextures());
            }
            
            yield return new WaitForSeconds(5f);
        }
    }
    
    IEnumerator CompressLargeTextures()
    {
        var textures = Resources.FindObjectsOfTypeAll<Texture2D>();
        var largeTextures = new List<Texture2D>();
        
        foreach (var texture in textures)
        {
            if (ShouldCompressTexture(texture))
            {
                largeTextures.Add(texture);
            }
        }
        
        // 크기별로 정렬 (큰 것부터)
        largeTextures.Sort((a, b) => (b.width * b.height).CompareTo(a.width * a.height));
        
        foreach (var texture in largeTextures)
        {
            CompressTexture(texture, "runtime_optimization");
            yield return null; // 프레임 분산
        }
        
        Debug.Log($"실시간 텍스처 압축 완료: {largeTextures.Count}개 텍스처");
    }
    
    bool ShouldCompressTexture(Texture2D texture)
    {
        // 이미 압축된 텍스처인지 확인
        if (IsCompressedFormat(texture.format))
        {
            return false;
        }
        
        // 큰 텍스처인지 확인
        int pixels = texture.width * texture.height;
        if (pixels < 512 * 512) // 512x512 미만은 압축하지 않음
        {
            return false;
        }
        
        // 중요한 UI 텍스처인지 확인
        if (texture.name.Contains("UI_") || texture.name.Contains("Icon_"))
        {
            return false;
        }
        
        return true;
    }
    
    public void CompressTexture(Texture2D texture, string profileName)
    {
        if (!profileMap.ContainsKey(profileName))
        {
            Debug.LogWarning($"압축 프로필을 찾을 수 없습니다: {profileName}");
            return;
        }
        
        var profile = profileMap[profileName];
        
        // 원본 포맷 저장
        if (!originalFormats.ContainsKey(texture))
        {
            originalFormats[texture] = texture.format;
        }
        
        // 플랫폼별 최적 포맷 선택
        var targetFormat = GetOptimalFormatForPlatform(texture, profile);
        
        // 텍스처 압축 수행
        StartCoroutine(CompressTextureAsync(texture, targetFormat, profile));
    }
    
    TextureFormat GetOptimalFormatForPlatform(Texture2D texture, CompressionProfile profile)
    {
        var currentPlatform = Application.platform;
        
        foreach (var platformSetting in profile.platformSettings)
        {
            if (platformSetting.platform == currentPlatform)
            {
                return platformSetting.preferredFormat;
            }
        }
        
        // 기본 포맷 선택
        if (HasAlpha(texture))
        {
            return TextureFormat.DXT5; // 알파 채널이 있는 경우
        }
        else
        {
            return TextureFormat.DXT1; // RGB만 있는 경우
        }
    }
    
    bool HasAlpha(Texture2D texture)
    {
        return texture.format == TextureFormat.RGBA32 ||
               texture.format == TextureFormat.ARGB32 ||
               texture.format == TextureFormat.RGBA4444 ||
               texture.format == TextureFormat.ARGB4444;
    }
    
    IEnumerator CompressTextureAsync(Texture2D texture, TextureFormat targetFormat, CompressionProfile profile)
    {
        Debug.Log($"텍스처 압축 시작: {texture.name} ({texture.format} → {targetFormat})");
        float startTime = Time.realtimeSinceStartup;
        
        // 원본 데이터 백업
        var originalPixels = texture.GetPixels32();
        var originalWidth = texture.width;
        var originalHeight = texture.height;
        
        try
        {
            // 해상도 조정이 필요한 경우
            if (originalWidth > profile.maxTextureSize || originalHeight > profile.maxTextureSize)
            {
                var newSize = CalculateTargetSize(originalWidth, originalHeight, profile.maxTextureSize);
                yield return StartCoroutine(ResizeTexture(texture, newSize.x, newSize.y));
            }
            
            // 압축 실행
            EditorApplication.delayCall += () => {
                try 
                {
                    texture.Compress(true);
                    Debug.Log($"텍스처 압축 완료: {texture.name}");
                }
                catch (System.Exception e)
                {
                    Debug.LogError($"텍스처 압축 실패: {texture.name} - {e.Message}");
                }
            };
            
            yield return new WaitForSeconds(0.1f); // 압축 완료 대기
            
            float compressionTime = Time.realtimeSinceStartup - startTime;
            
            // 압축 결과 분석
            AnalyzeCompressionResult(texture, originalWidth, originalHeight, compressionTime);
        }
        catch (System.Exception e)
        {
            Debug.LogError($"텍스처 압축 중 오류 발생: {e.Message}");
            
            // 실패시 원본 복구
            RestoreOriginalTexture(texture, originalPixels, originalWidth, originalHeight);
        }
    }
    
    Vector2Int CalculateTargetSize(int width, int height, int maxSize)
    {
        float aspectRatio = (float)width / height;
        
        if (width > height)
        {
            return new Vector2Int(maxSize, Mathf.RoundToInt(maxSize / aspectRatio));
        }
        else
        {
            return new Vector2Int(Mathf.RoundToInt(maxSize * aspectRatio), maxSize);
        }
    }
    
    IEnumerator ResizeTexture(Texture2D texture, int newWidth, int newHeight)
    {
        var rt = RenderTexture.GetTemporary(newWidth, newHeight);
        Graphics.Blit(texture, rt);
        
        var resizedTexture = new Texture2D(newWidth, newHeight, texture.format, false);
        
        RenderTexture.active = rt;
        resizedTexture.ReadPixels(new Rect(0, 0, newWidth, newHeight), 0, 0);
        resizedTexture.Apply();
        
        RenderTexture.active = null;
        RenderTexture.ReleaseTemporary(rt);
        
        // 원본 텍스처 데이터를 새로운 크기로 교체
        texture.Resize(newWidth, newHeight);
        texture.SetPixels32(resizedTexture.GetPixels32());
        texture.Apply();
        
        DestroyImmediate(resizedTexture);
        
        yield return null;
    }
    
    void RestoreOriginalTexture(Texture2D texture, Color32[] originalPixels, int originalWidth, int originalHeight)
    {
        texture.Resize(originalWidth, originalHeight);
        texture.SetPixels32(originalPixels);
        texture.Apply();
        
        Debug.Log($"텍스처 원본 복구: {texture.name}");
    }
    
    void AnalyzeCompressionResult(Texture2D texture, int originalWidth, int originalHeight, float compressionTime)
    {
        // 압축 전후 메모리 사용량 계산
        long originalSize = (long)originalWidth * originalHeight * 4; // RGBA32 기준
        long compressedSize = CalculateCompressedSize(texture);
        
        float compressionRatio = (float)originalSize / compressedSize;
        
        var analyticsData = new Dictionary<string, object>
        {
            {"texture_name", texture.name},
            {"original_width", originalWidth},
            {"original_height", originalHeight},
            {"compressed_width", texture.width},
            {"compressed_height", texture.height},
            {"original_format", originalFormats.ContainsKey(texture) ? originalFormats[texture].ToString() : "Unknown"},
            {"compressed_format", texture.format.ToString()},
            {"original_size_bytes", originalSize},
            {"compressed_size_bytes", compressedSize},
            {"compression_ratio", compressionRatio},
            {"compression_time", compressionTime},
            {"device_model", SystemInfo.deviceModel},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("texture_compression", analyticsData);
        
        Debug.Log($"텍스처 압축 분석: {texture.name} - 압축률 {compressionRatio:F2}x, 시간 {compressionTime:F2}초");
    }
    
    long CalculateCompressedSize(Texture2D texture)
    {
        switch (texture.format)
        {
            case TextureFormat.DXT1:
                return texture.width * texture.height / 2; // 4비트 per pixel
            case TextureFormat.DXT5:
                return texture.width * texture.height; // 8비트 per pixel
            case TextureFormat.PVRTC_RGB2:
            case TextureFormat.PVRTC_RGBA2:
                return texture.width * texture.height / 4; // 2비트 per pixel
            case TextureFormat.PVRTC_RGB4:
            case TextureFormat.PVRTC_RGBA4:
                return texture.width * texture.height / 2; // 4비트 per pixel
            case TextureFormat.ETC_RGB4:
            case TextureFormat.ETC2_RGB:
                return texture.width * texture.height / 2; // 4비트 per pixel
            case TextureFormat.ETC2_RGBA8:
                return texture.width * texture.height; // 8비트 per pixel
            default:
                return texture.width * texture.height * 4; // 기본값 (RGBA32)
        }
    }
    
    bool IsCompressedFormat(TextureFormat format)
    {
        switch (format)
        {
            case TextureFormat.DXT1:
            case TextureFormat.DXT5:
            case TextureFormat.PVRTC_RGB2:
            case TextureFormat.PVRTC_RGBA2:
            case TextureFormat.PVRTC_RGB4:
            case TextureFormat.PVRTC_RGBA4:
            case TextureFormat.ETC_RGB4:
            case TextureFormat.ETC2_RGB:
            case TextureFormat.ETC2_RGBA8:
            case TextureFormat.ASTC_4x4:
            case TextureFormat.ASTC_6x6:
            case TextureFormat.ASTC_8x8:
                return true;
            default:
                return false;
        }
    }
    
    // 공개 API
    public void CompressAllTextures(string profileName = "default")
    {
        var textures = Resources.FindObjectsOfTypeAll<Texture2D>();
        
        foreach (var texture in textures)
        {
            if (ShouldCompressTexture(texture))
            {
                compressionQueue.Enqueue(texture);
            }
        }
        
        StartCoroutine(ProcessCompressionQueue(profileName));
    }
    
    IEnumerator ProcessCompressionQueue(string profileName)
    {
        Debug.Log($"텍스처 압축 큐 처리 시작: {compressionQueue.Count}개 텍스처");
        
        while (compressionQueue.Count > 0)
        {
            var texture = compressionQueue.Dequeue();
            CompressTexture(texture, profileName);
            
            yield return new WaitForSeconds(0.1f); // 처리 간격
        }
        
        Debug.Log("텍스처 압축 큐 처리 완료");
    }
    
    public void RestoreTexture(Texture2D texture)
    {
        if (originalFormats.ContainsKey(texture))
        {
            // 원본 포맷 복구 로직 (실제 구현 시 원본 데이터 보존 필요)
            Debug.Log($"텍스처 복구: {texture.name} → {originalFormats[texture]}");
        }
    }
    
    public float GetCompressionRatio()
    {
        var textures = Resources.FindObjectsOfTypeAll<Texture2D>();
        long totalOriginal = 0;
        long totalCompressed = 0;
        
        foreach (var texture in textures)
        {
            if (originalFormats.ContainsKey(texture))
            {
                totalOriginal += texture.width * texture.height * 4; // 원본 RGBA32 추정
                totalCompressed += CalculateCompressedSize(texture);
            }
        }
        
        return totalOriginal > 0 ? (float)totalOriginal / totalCompressed : 1f;
    }
    
    public Dictionary<string, object> GetCompressionStats()
    {
        var textures = Resources.FindObjectsOfTypeAll<Texture2D>();
        var stats = new Dictionary<string, object>
        {
            {"total_textures", textures.Length},
            {"compressed_textures", 0},
            {"total_memory_mb", 0f},
            {"compression_ratio", GetCompressionRatio()}
        };
        
        int compressedCount = 0;
        long totalMemory = 0;
        
        foreach (var texture in textures)
        {
            if (IsCompressedFormat(texture.format))
            {
                compressedCount++;
            }
            totalMemory += CalculateCompressedSize(texture);
        }
        
        stats["compressed_textures"] = compressedCount;
        stats["total_memory_mb"] = totalMemory / (1024f * 1024f);
        
        return stats;
    }
}
```

텍스처 압축은 모바일 게임의 핵심 최적화 요소에요.\
플랫폼별 최적 압축 포맷을 선택하고, 시각적 품질과 메모리 효율성 사이의 균형을 잘 맞추는 것이 중요해요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/환경
  확인/getOperationalEnvironment.md
---

# 애플리케이션 환경 확인하기

## `getOperationalEnvironment`

`getOperationalEnvironment` 함수로 애플리케이션의 환경 정보를 사용해서 애플리케이션이 현재 어느 배포 환경(예: `sandbox`, `toss`)에서 실행 중인지 확인할 수 있어요.\
토스 앱에서 실행 중이라면 `'toss'`, 샌드박스 환경에서 실행 중이라면 `'sandbox'`를 반환해요.

운영 환경은 앱이 실행되는 컨텍스트를 의미하며, 특정 기능의 사용 가능 여부를 판단하는 데 활용할 수 있어요.

## 시그니처

```typescript
function getOperationalEnvironment(): 'toss' | 'sandbox';
```

### 반환 값

현재 운영 환경을 나타내는 문자열이에요.

* `'toss'`: 토스 앱에서 실행 중이에요.
* `'sandbox'`: 샌드박스 환경에서 실행 중이에요.

## 예제

### 현재 운영 환경 확인하기

애플리케이션이 배포된 환경에 따라 실행 환경이 달라질 수 있어요. 예를 들어, `sandbox` 환경에서는 일부 테스트 기능을 제공하고, `toss` 환경에서는 실제 서비스를 제공할 수 있어요. 실행 환경을 확인하면 이러한 기능 차이를 관리할 수 있죠.

다음은 실행 환경을 확인하는 예시예요.

::: code-group

```js [js]
import { getOperationalEnvironment } from '@apps-in-toss/web-framework';

const environment = getOperationalEnvironment();
```

```tsx [React]
import { getOperationalEnvironment } from '@apps-in-toss/web-framework';
import { Text } from '@toss/tds-mobile';

function EnvironmentInfo() {
  const environment = getOperationalEnvironment();

  return <Text>{`현재 실행 환경은 '${environment}'입니다.`}</Text>;
}
```

```tsx [React Native]
import { getOperationalEnvironment } from '@apps-in-toss/framework';
import { Text } from '@toss/tds-react-native';

function EnvironmentInfo() {
  const environment = getOperationalEnvironment();

  return <Text>{`현재 실행 환경은 '${environment}'입니다.`}</Text>;
}
```

:::

## 실행 환경에 따라 기능 제한하기

특정 배포 환경에서만 제공해야 하는 기능이 있을 수 있어요. 아래는 `sandbox` 환경에서만 특별한 기능을 제공하는 예시예요.

```tsx{4,8-9}
import { View, Text } from 'react-native';
import { getOperationalEnvironment } from '@apps-in-toss/framework';

const isSandbox = getOperationalEnvironment() === 'sandbox'; // 'sandbox' 환경인지 확인하는 변수

function Component() {
  const handlePress = () => {
    if (isSandbox) {
      // 'sandbox' 환경에서 제공할 기능
    } else {
      // 다른 환경에서 제공할 기능
    }
  };

  return <Button onPress={handlePress}>자세히 보기</Button>;
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인증/tosscertAccessToken.md
---

# 액세스 토큰 발급

토스 본인 인증을 위한 **Access Token**을 발급받는 API예요. 발급받은 토큰은 이후 모든 서비스 API 호출 시 인증 용도로 사용돼요.

토큰에는 만료시간(`expires_in`)이 존재하며, 만료되면 반드시 새 토큰을 발급받아야 해요.\
이미 유효한 토큰이 있는 상태에서 불필요하게 API를 반복 호출하지 않도록 주의하세요.

:::info BaseURL
`https://oauth2.cert.toss.im`
:::

* Content-type : application/x-www-form-urlencoded
* Method : `POST`
* Endpoint : `/token`

***

## 요청 예시

::: code-group

```bash [Shell(curl)]
curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=test_a8e23336d673ca70922b485fe806eb2d' \
--data-urlencode 'client_secret=test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3' \
--data-urlencode 'scope=ca'
```

```java
URL url = new URL("https://oauth2.cert.toss.im/token");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST"); 

httpConn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("grant_type=client_credentials&" +
        "client_id=test_a8e23336d673ca70922b485fe806eb2d&" +
        "client_secret=test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3&" +
        "scope=ca");
writer.flush();
writer.close(); 

httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() == 200
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
```

```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://oauth2.cert.toss.im/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type' : 'application/x-www-form-urlencoded',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'grant_type=client_credentials&client_id=test_a8e23336d673ca70922b485fe806eb2d&client_secret=test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3&scope=ca');

$response = curl_exec($ch);

curl_close($ch);
```

:::

## 요청 헤더

| 이름 | 타입 | 필수값 여부 | 설명 |
|---------------|---------|--------------|---------------------------------------------|
| Content-Type | string | Y | `application/x-www-form-urlencoded` |

## 요청 파라미터

| 이름 | 타입 | 필수값 여부 | 설명 |
| --- | --- | --- | --- |
| grant\_type | string | Y | 고정 값: `client_credentials` |
| scope | string | Y | 인증 요청 범위 (예: `ca`) |
| client\_id | string | Y | 고객사에 발급된 클라이언트 아이디 |
| client\_secret | string | Y | 고객사에 발급된 클라이언트 시크릿 |

***

## 응답

| 이름 | 타입 | 설명 |
| --- | --- | --- |
| access\_token | string | Access Token 값 |
| scope | string | 발급된 인증 범위 |
| token\_type | string | 토큰 타입 (항상 `Bearer`) |
| expires\_in | number | 토큰 만료 시간(초 단위) |

```json
{
  "access_token": "eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ",
  "scope": "ca",
  "token_type": "Bearer",
  "expires_in": 31536000
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/사진/fetchAlbumPhotos.md
---

# 앨범 가져오기

## `fetchAlbumPhotos`

사용자의 앨범에서 사진 목록을 불러오는 함수예요.
최대 개수와 해상도를 설정할 수 있고 갤러리 미리보기, 이미지 선택 기능 등에 활용할 수 있어요.

## 시그니처

```typescript
function fetchAlbumPhotos(options: {
  maxCount: number;
  maxWidth: number;
  base64: boolean;
}): Promise<ImageResponse[]>;
```

### 파라미터

### 프로퍼티

### 반환 값

앨범 사진의 고유 ID와 데이터 URI를 포함한 배열을 반환해요.

## FetchAlbumPhotosPermissionError

사진첩 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof FetchAlbumPhotosPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class FetchAlbumPhotosPermissionError extends PermissionError {
  constructor();
}
```

## 예제

### 사진의 최대 폭을 360px로 제한하여 가져오기

사진을 가져오는 예제예요.
"권한 확인하기"버튼을 눌러서 현재 사진첩 읽기 권한을 확인해요.
사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`FetchAlbumPhotosPermissionError`](./FetchAlbumPhotosPermissionError)를 반환해요.
"권한 요청하기"버튼을 눌러서 사진첩 읽기 권한을 요청할 수 있어요.

::: code-group

```js [js]
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError } from '@apps-in-toss/web-framework';

const base64 = true;

async function handleFetchAlbumPhotos() {
  try {
    const response = await fetchAlbumPhotos({
      base64,
      maxWidth: 360,
    });

    response.forEach((image) => {
      const imageUri = base64 ? 'data:image/jpeg;base64,' + image.dataUri : image.dataUri;
      console.log('이미지 URI:', imageUri);
    });
  } catch (error) {
    if (error instanceof FetchAlbumPhotosPermissionError) {
      console.log('앨범 읽기 권한 없음');
    }
    console.error('앨범을 가져오는 데 실패했어요:', error);
  }
}

function handleGetPermissionForFetchAlbumPhotos() {
  const permission = await fetchAlbumPhotos.getPermission();
  return permission;
}

function handleOpenPermissionForFetchAlbumPhotos() {
  const permission = await fetchAlbumPhotos.openPermissionDialog();
  return permission;
}
```

```tsx [React]
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/web-framework';
import { useState } from 'react';

const base64 = true;

function AlbumPhotoList() {
  const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);

  const handlePress = async () => {
    try {
      const response = await fetchAlbumPhotos({
        base64,
        maxWidth: 360,
      });
      setAlbumPhotos((prev) => [...prev, ...response]);
    } catch (error) {
      if (error instanceof FetchAlbumPhotosPermissionError) {
        // 앨범 읽기 권한 없음
      }
      console.error('앨범을 가져오는 데 실패했어요:', error);
    }
  };

  return (
    <div>
      {albumPhotos.map((image) => {
        // base64 형식으로 반환된 이미지를 표시하려면 데이터 URL 스키마 Prefix를 붙여야해요.
        const imageUri = base64 ? 'data:image/jpeg;base64,' + image.dataUri : image.dataUri;

        return <Image source={{ uri: imageUri }} key={image.id} />;
      })}
      <input type="button" value="앨범 가져오기" onClick={handlePress} />
      <input type="button"
        value="권한 확인하기"
        onClick={async () => {
          const permission = await fetchAlbumPhotos.getPermission();
          alert(permission);
        }}
      />
      <input type="button"
        value="권한 요청하기"
        onClick={async () => {
          const permission = await fetchAlbumPhotos.openPermissionDialog();
          alert(permission);
        }}
      />
    </div>
  );
}
```

```tsx [React Native]
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Image, View } from 'react-native';

const base64 = true;

function AlbumPhotoList() {
  const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);

  const handlePress = async () => {
    try {
      const response = await fetchAlbumPhotos({
        base64,
        maxWidth: 360,
      });
      setAlbumPhotos((prev) => [...prev, ...response]);
    } catch (error) {
      if (error instanceof FetchAlbumPhotosPermissionError) {
        // 앨범 읽기 권한 없음
      }
      console.error('앨범을 가져오는 데 실패했어요:', error);
    }
  };

  return (
    <View>
      {albumPhotos.map((image) => {
        // base64 형식으로 반환된 이미지를 표시하려면 데이터 URL 스키마 Prefix를 붙여야해요.
        const imageUri = base64 ? 'data:image/jpeg;base64,' + image.dataUri : image.dataUri;

        return <Image source={{ uri: imageUri }} key={image.id} />;
      })}
      <Button title="앨범 가져오기" onPress={handlePress} />
      <Button
        title="권한 확인하기"
        onPress={async () => {
          const permission = await fetchAlbumPhotos.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="권한 요청하기"
        onPress={async () => {
          const permission = await fetchAlbumPhotos.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}

```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-album-photos](https://github.com/toss/apps-in-toss-examples/tree/main/with-album-photos) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/development/test/function.md'
description: >-
  앱인토스 콘솔에서 앱 내 기능을 설정하는 방법을 안내합니다. 사용자가 특정 기능으로 바로 진입할 수 있도록 앱 내 기능을 등록하고
  관리하세요.
---

# 앱 내 기능

콘솔의 **'앱 내 기능'** 은 사용자가 **검색 결과나 미니홈 화면에서 특정 기능으로 바로 진입**할 수 있도록 도와주는 기능이에요.\
즉, 사용자가 홈 화면을 거치지 않고 특정 서비스의 세부 기능으로 이동할 수 있어요.

> 예시: ‘식단 기록하기’ → 선택 시 홈 화면을 건너뛰고 곧바로 식단 기록 화면으로 이동

::: tip 꼭 확인하세요

* **비게임 앱**은 앱 내 기능을 **최소 1개 이상 등록**해야 해요.
* 앱 내 기능 검토에는 **영업일 기준 1~2일**이 소요될 수 있어요.
  :::

![](/assets/function_0.DqhNG86B.png)

## 앱 내 기능 최초 등록하기 (신규 출시하는 앱)

* 미니앱을 최초로 출시하는 경우에는 앱을 출시할 때 앱 내 기능을 함께 등록할 수 있어요.
  * **접속방법 :** 앱인토스 콘솔 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 ‘앱 출시’→ 미니앱 선택 → 좌측 메뉴 ‘앱 출시’ → ‘+ 등록하기 ‘ → ait 번들 업로드 후 입력 가능

### 1. 앱 출시 메뉴에서 ‘등록하기’ 를 눌러서 번들을 등록해 주세요.

![](/assets/function_1.CQwL-fxB.png)

### 2. 빌드한 ait 파일을 업로드 해주세요.

![](/assets/function_2.DFxsZMrh.png)

### 3. 출시하기 전에 앱 내 기능을 함께 등록해 주세요.

![](/assets/function_3.CWI20Cnu.png)

* 사용자가 바로 접속 할 수 있는 기능의 이름과 이동할 **intoss://{{appName}}/pages** 를 입력해 주세요.
  * 쿼리 파라미터를 설정할 수 있어요.
* 토스 UX 라이팅을 기반으로 앱 내 기능은 **‘~하기’** 또는 **‘명사형’** 으로 작성해 주세요.
  * 예) ‘송금 내역 확인하기’, ‘해외 송금하기’, ‘여행 예약 내역 확인하기’ 등
* 미니앱 서비스의 기능이 드러나게 작성해 주세요.
  * ‘예약 확인하기’, ‘내역 확인’, ‘보러가기’, ‘시청하기’ 등으로만 작성할 경우 무슨 서비스의 기능인지 사용자가 알기 어려워요.
* 미니앱 출시 검토와 함께 앱 내 기능 검토가 진행돼요.
* 실제 미니앱이 출시 되었을 때, 설정한 앱 내 기능이 정상적으로 접속이 되는지 꼭 확인해 주세요.

### 개발 환경별 피처 구성

#### 1. Webview

라우터 경로를 피처 주소와 매핑해요.

```tsx
<Route path="/search" element={<SearchPage />} />
```

피처 주소는 `intoss://{appName}/search`로 입력하면 해당 페이지로 이동할 수 있어요.

#### 2. React Native (Bedrock 기반)

Next.js 유사 **파일 기반 라우팅**을 사용해요.\
/`pages/search.tsx` → `/search` 경로 매핑 → `intoss://{appName}/search`로 진입 시 렌더링\
자세한 구조는 [파일 기반 라우팅 이해하기](/tutorials/react-native.html#파일-기반-라우팅-이해하기) 를 참고하세요.

### 4. 검토 결과는 ‘앱 내 기능’ 탭에서 확인할 수 있어요.

![](/assets/function_4.Zo9XScrl.png)

## 앱 내 기능 등록 및 수정하기 (이미 출시된 앱)

* 미니앱을 이미 출시한 경우라면 ‘앱 내 기능’ 탭에서 앱 내 기능만 따로 등록/수정을 할 수 있어요.
  * **접속방법 :** 앱인토스 콘솔 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 ‘앱 출시’→ 미니앱 선택 → 좌측 메뉴 ‘앱 출시’ → ‘앱 내 기능’ 탭 선택
* 앱 내 기능만 따로 추가/수정하는 경우는 앱 내 기능만 검토하기 때문에 영업일 기준 1~2일이 소요 될수 있어요.
* 현재 운영 중인 미니앱에서도 새롭게 추가하거나 수정하는 경우, 앱 내 기능이 정상적으로 접속이 되는지 꼭 확인해 주세요.

### 1. \[수정하기] 버튼을 눌러 앱 내 기능을 수정할 수 있어요.

![](/assets/function_5.CGDWSPcQ.png)

### 2. 검토 결과는 ‘앱 내 기능’ 탭에서 확인할 수 있어요.

![](/assets/function_6.C0IHT0Mu.png)

![](/assets/function_7.BPnZwR1S.png)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/환경
  확인/isMinVersionSupported.md
---

# 앱 최소 버전 확인하기

## `isMinVersionSupported`

`isMinVersionSupported` 함수는 현재 토스 앱 버전이 지정한 최소 버전 이상인지 확인해요.

이 함수는 현재 실행 중인 토스 앱의 버전이 파라미터로 전달된 최소 버전 요구사항을 충족하는지 확인해요. 특정 기능이 최신 버전에서만 동작할 때, 사용자에게 앱 업데이트를 안내할 수 있어요.

## 시그니처

```typescript
function isMinVersionSupported(minVersions: {
  android: `${number}.${number}.${number}` | 'always' | 'never';
  ios: `${number}.${number}.${number}` | 'always' | 'never';
}): boolean;
```

### 파라미터

### 반환 값

## 예제

### 앱 버전 확인하기

::: code-group

```js [js]
import { isMinVersionSupported } from '@apps-in-toss/web-framework';

const isSupported = isMinVersionSupported({
  android: '1.2.0',
  ios: '1.3.0',
});
```

```tsx [React]
import { isMinVersionSupported } from '@apps-in-toss/web-framework';
import { Text } from '@toss/tds-mobile';

function VersionCheck() {
  const isSupported = isMinVersionSupported({
    android: '1.2.0',
    ios: '1.3.0',
  });

  return <div>{!isSupported && <Text>최신 버전으로 업데이트가 필요해요.</Text>}</div>;
}
```

```tsx [React Native]
import { isMinVersionSupported } from '@apps-in-toss/framework';
import { Text } from '@toss/tds-react-native';
import { View } from 'react-native';

function VersionCheck() {
  const isSupported = isMinVersionSupported({
    android: '1.2.0',
    ios: '1.3.0'
  });

  return (
    <View>
      {!isSupported && (
        <Text>최신 버전으로 업데이트가 필요해요.</Text>
      )}
    </View>
  );
}
```

:::

---

---
url: 'https://developers-apps-in-toss.toss.im/design/prepare/deus.md'
description: >-
  앱인토스 파트너사를 위한 UI 디자인 툴 앱빌더 사용 가이드입니다. 프로젝트 생성, 컴포넌트 활용, 반응형 디자인, 개발자 모드 등 앱빌더
  기능을 확인하세요.
---

# 앱빌더

## **1. '앱빌더' 소개**

앱빌더는 앱인토스 파트너사를 위한 UI 디자인 툴이에요.\
별다른 설치 없이 토스의 UI 스타일 가이드를 따른 화면을 빠르게 완성할 수 있어요.

### **앱빌더는 이런 점이 좋아요**

* 디자인 라이브러리를 따로 가져오지 않아도 필요한 컴포넌트가 이미 들어있어요.
* 오른쪽 속성 패널에서 색상, 텍스트, 간격 등을 쉽게 조정할 수 있어요.
* 별다른 설치 없이 웹에서 바로 사용할 수 있어요.
* **콘솔에서 미니앱을 선택해 디자인 메뉴를 누르면 바로 사용할 수 있어요.**

**참고**

* 앱빌더 **개발자 모드**는 우측 패널 상단 토글을 ON 하면 이용할 수 있어요.
* 지금은 기본 UI 디자인 기능만 제공돼요.

**주의**

* 현재는 **베타 버전**이에요. 일부 기능이 없거나 오류가 발생할 수 있어요.
* 아직 공식 출시 전이기 때문에 **캡처나 화면 녹화 등으로 외부에 공유하지 말아 주세요.**

## **2. 프로젝트 생성과 삭제**

앱빌더에서 디자인을 시작하려면 먼저 프로젝트를 만들어야 해요.\
영상으로 프로젝트를 **생성하고 삭제하는 방법을 알아볼게요.**

### 프로젝트 생성

홈 화면 오른쪽 상단에 '+ 새로 만들기' 버튼으로 새 프로젝트 만들 수 있어요.

### 프로젝트 삭제

프로젝트는 영구 삭제할 수 없고, 필요에 따라 보관함에 넣거나 꺼낼 수 있어요.

### 프로젝트 즐겨찾기

프로젝트에 마우스를 올리면 보이는 '별 버튼'을 클릭해 즐겨찾기에 추가, 해제할 수 있어요.\
즐겨찾기한 프로젝트는 화면 상단에 고정돼요.

### 프로젝트 폴더

왼쪽 패널 '+' 버튼으로 만들 수 있어요.

## 3. 디자인 시작하기

새 프로젝트를 열어 브랜드 스타일을 설정한 후, 가이드와 템플릿을 바로 활용할 수 있어요.\
영상으로 **브랜드 스타일 설정 방법**과 미리 준비된 **가이드, 템플릿**을 함께 살펴볼게요.

### **브랜드 스타일 설정**

새 프로젝트를 열면 "시작하기" 모달에서 서비스 이름과 버튼 색상을 선택할 수 있어요.

* 서비스 이름 : 앱인토스 콘솔에 등록된 이름만 선택할 수 있어요.
* 버튼 색상 : 서비스의 기본 색상(primary color)로, 대부분의 에셋에 적용돼요. 일부 색상은 웹 접근성을 지키기 위해 보정될 수 있어요.

### **페이지**

페이지는 한 프로젝트 안에서 **서로 다른 캔버스**에 디자인할 수 있는 기능이에요.\
왼쪽 패널 상단의 페이지 섹션에서 새 페이지를 만들거나 삭제할 수 있어요.

* **준비하기 페이지**: 앱빌더 기본 사용법을 확인할 수 있어요.
* **템플릿 페이지**: 바로 복제해 쓸 수 있는 UI 세트가 준비돼 있어요.

### **디자인 방법**

앱빌더에서는 두 가지 방법으로 디자인할 수 있어요.

1. **퀵스타트**: 토스에서 쓰는 UI 화면을 그대로 가져와 사용할 수 있어요.
2. **커스텀**: 디자인 에셋을 조합해 UI를 완성할 수 있어요.

## **4. 퀵스타트로 디자인하기**

퀵스타트란 토스앱에서 쓰이는 UI를 불러와 일부 옵션만 수정할 수 있는 기능이에요.\
단일 화면뿐 아니라, 여러 화면이 묶인 플로우도 제공돼요.\
영상으로 **퀵스타트 기능 활용법**을 살펴볼게요.

### **퀵스타트 수정 방법**

퀵스타트를 선택하면 **오른쪽 패널**에서 텍스트나 일부 설정을 수정할 수 있어요.

내부 요소는 **Ctrl(Cmd) + 클릭**으로 선택할 수 있어요. 단, 오른쪽 패널에서 변경할 수 있는 옵션 외 다른 요소를 **변경하거나 삭제하는 건 지원하지 않아요.** 필요한 내용만 간단히 바꿔서 쓰는 용도로 활용해 주세요.

## **5. 커스텀으로 디자인하기**

커스텀이란 토스에서 제공하는 디자인 에셋을 조합해 UI를 만드는 방법이에요.\
필요한 퀵스타트가 없을 땐, 기본 화면을 추가하고 에셋을 조합해 직접 UI를 만들 수 있어요.\
영상으로 **커스텀 기능 활용법**을 살펴볼게요.

### **기본 화면 추가**

화면 크기는 아이폰 13 미니 기준(375x812)이에요. 디자인 에셋도 이 너비에 맞춰 제작돼 있어요.\
**화면 너비를 임의로 조정하면 일부 요소가 어색해질 수 있으니 권장하지 않아요.**

## **6. 텍스트**

앱빌더에서는 'Text' 에셋을 활용해 텍스트에 TDS를 간편하게 적용할 수 있어요.\
‘Text' 에셋을 추가한 뒤, 오른쪽 패널에서 원하는대로 설정해요.\
영상으로 **텍스트를 추가하고 편집하는 방법**을 알아볼게요.

**종류 선택**

* ‘일반형’은 일반적인 줄글 형식, ‘포스트형’은 제목으로 활용하기 적합한 볼드체라고 생각하면 돼요.

**텍스트**

* '텍스트' 입력칸에서 내용을 편집할 수 있어요.
* **줄바꿈은 shift+enter**로 할 수 있어요.

## **7. 아이콘, 그래픽**

**토스팀이 제공하는 그래픽 요소만 사용할 수 있어요.**\
영상으로 **그래픽을 추가하고 편집하는 방법**을 알아볼게요.\
그래픽을 추가하는 방법은 다음과 같아요.

1. **상단 컨트롤바의 '리소스'** 를 눌러 원하는 그래픽을 클릭하거나
2. **우측 패널 커스텀에서 'Asset' 추가** → ‘변경하기’ 버튼 → 원하는 그래픽을 클릭해요.

***

앱빌더 베타 버전에서는 3D 그래픽을 따로 제공하지 않아요.\
대신, 2D 그래픽을 선택해 3D로 변환할 수 있어요.\
영상으로 **3D 그래픽을 생성하는 방법**을 알아볼게요.

* 만든 3D 그래픽은 **`저장하기`** 버튼을 누르면 토스팀의 검토가 끝난 후 자유롭게 쓸 수 있어요.
* 토스에서 사용하는 3D 그래픽은 현재 앱빌더에서 지원이 어렵고, 제공을 검토 중이에요. 양해 부탁드려요.
* 퀵스타트에 제공되는 3D 그래픽을 따로 가져와 사용할 수 없어요.

## **8. 레이아웃**

앱빌더에서는 붙이기 기능을 통해 레이아웃을 빠르게 구성할 수 있어요. 영상으로 **붙이기 기능 활용법**을 알아볼게요.

* 여러 에셋을 **Shift + 클릭**으로 선택한 뒤, 오른쪽에 뜨는 툴바에서 가로/세로/겹쳐 붙이기로 그룹화할 수 있어요.
* **떼어내기**로 그룹을 해제할 수도 있어요.
* 붙인 뒤 오른쪽 패널에서 여백, 배경색, 모서리 둥글기로 조절할 수 있어요.

붙인 이후 오른쪽 패널에서 여백, 배경색, 모서리 둥글기 등을 조절할 수 있어요.\
영상으로 **붙이기 기능 활용 후 스타일 편집 방법**을 알아볼게요.

**Stack Layout**

* Fit: 내용에 맞게 길이 조정
* Fill: 화면을 채우도록 길이 조정
* Fixed: 사용자가 지정한 길이
* Distribute: 붙이기 시작점
* Gap: 사이 여백
* Padding: 모서리 여백

**Style**

* Visible: 보이기/숨기
* Opacity: 투명도 (1이 100%예요. 만약 10% 투명도를 주고 싶다면 0.1을 입력하면 돼요.)
* Fill: 배경색
* Border: 테두리 색상
* Radius: 모서리 둥글기
* Shadow: 그림자 효과

## **9. 프로토타입**

오른쪽 상단 플레이 버튼으로 프로토타입(모바일 기기 해상도 미리보기)을 볼 수 있어요.\
영상으로 **프로토타입 기능 활용법**을 알아볼게요.

상단 컨트롤바에 휴대폰 아이콘 모양을 선택하면 디바이스 프리뷰 기능을 사용할 수 있어요. 디바이스 프리뷰 기능으로 기기별 해상도를 확인해 보세요.\
화면 내부의 모든 에셋의 너비를 **Fill**로 설정하면 반응형 디자인을 만들 수 있어요.\
**프로토타입 공유 버튼**으로 링크를 복사하면, 실제 모바일 기기에서 UI를 바로 볼 수 있어요.\
영상으로 **프로토타입 링크 생성 방법**을 알아볼게요.

## **10. 앱빌더 튜토리얼 영상**

상단에 소개된 기능들을 활용해 앱빌더로 검색 UI를 만들어보는 튜토리얼 영상이에요.

[**👉 영상 보러 가기**](https://www.notion.so/237714bbfde780eba495e21c126f1487?pvs=21)

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/intro/overview.md'
---

# 앱인토스 Unity 적용 가이드

Unity로 만든 게임을 앱인토스 미니앱 환경에 빠르게 전환할 수 있는 가이드예요.\
기존 Unity 프로젝트를 그대로 유지하면서, WebGL을 통해 앱인토스 미니앱 플랫폼에 손쉽게 적용할 수 있어요.

***

## 소개

앱인토스 Unity WebGL 미니앱 가이드는 기존 Unity 게임을 미니앱으로 옮길 때,\
엔진 교체나 핵심 코드 수정 없이도 앱인토스 플랫폼에서 그대로 실행할 수 있도록 돕습니다.

이 가이드의 목표는 개발 리소스를 최소화하고, Unity 프로젝트를 효율적으로 전환하는 거예요.\
기존 빌드 환경과 코드베이스를 그대로 유지하면서 앱인토스 미니앱 런타임에 자연스럽게 통합되도록 설계됐어요.

***

## 문서 구조

### 📚 기본 문서

* [소개](/unity/intro/overview) - 프로젝트 개요 및 특징

- [입문 가이드](/unity/intro/migration-guide) - 단계별 개발 가이드

### 🔍 호환성 및 평가

* [기술 원리](/unity/guide/runtime-structure) - 기술 아키텍처 개요
* [호환성 평가](/unity/guide/precheck) - 게임 적합성 검사
* [권장 Unity 버전](/unity/guide/recommend-engine) - 버전별 지원 현황

### ⚡ 성능 최적화

* [성능 최적화 개요](/unity/optimization/perf-optimization) - 최적화 전략
* [시작 속도 향상](/unity/optimization/start/startup-speed) - 로딩 최적화
* [메모리 최적화](/unity/optimization/runtime/memory) - 메모리 관리
* [렌더링 최적화](/unity/optimization/runtime/performance) - 그래픽 성능

### 🛠 개발 도구

* [디버깅 가이드](/unity/debug/debug-exception) - 오류 해결
* [프로파일링](/unity/optimization/runtime/profile) - 성능 분석

***

## 지원 및 도움말

커뮤니티: [앱인토스 개발자 포럼](https://techchat-apps-in-toss.toss.im/)
API 문서: [앱인토스 개발자센터](https://developers-apps-in-toss.toss.im/)

---

---
url: 'https://developers-apps-in-toss.toss.im/intro/overview.md'
description: >-
  앱인토스(Apps in Toss)는 토스 앱 내에서 서비스를 앱인앱 형태로 제공하는 플랫폼입니다. 3,000만 토스 유저에게 바로 노출하고,
  SDK와 API를 활용해 빠르게 개발하며, 다양한 솔루션으로 성장할 수 있습니다.
---

# 앱인토스란

앱인토스(Apps in Toss)는 파트너사가 개발한 서비스를 토스 앱 내부에서 '앱인앱(App-in-App)'의 형태로 노출할 수 있게 하는 플랫폼이에요.

지금 바로 3,000만 누적 토스 사용자에게 서비스를 선보이고, 사용자 확보와 매출 확장을 동시에 도모해보세요.

앱인토스의 다양한 소식은 공식 홈페이지와 블로그에서 확인할 수 있어요.

![최소한의 리소스 개발 시작하기](/assets/og-apps-in-toss-3000.BtjLyQpd.png)

***

## 앱인토스에서 무엇을 제공하나요?

앱인토스는 단순히 앱을 출시하는 것에 그치지 않아요.\
누구나 최소한의 리소스로 빠르게 앱을 개발하고, 토스의 강력한 유저 풀에서 성장할 수 있도록 필수적인 기능과 도구를 제공해요.

![](/assets/overview.B7qHvJPv.png)

### 다양한 솔루션 도구를 제공해요

앱인토스는 WebView와 React Native 기반의 SDK를 제공하고 있어요.\
파트너사는 SDK만 연동해 빌드 결과물을 업로드하면, 내부 검수 절차 후 바로 출시할 수 있어요.\
즉, 복잡한 네이티브 개발 없이도 누구나 앱을 쉽게 만들 수 있어요.

![](/assets/overview_flow.DIThwOhQ.png)

토스 SDK와 API, UI 컴포넌트 등을 활용해 로그인·결제·인증 같은 핵심 기능을 직접 구현하지 않고도 빠르게 적용할 수 있어요.\
그리고 파트너사의 앱 개발부터 디자인, 마케팅, 수익화까지 전 과정을 지원하는 솔루션을 제공해요.\
앱인토스의 인프라를 통해서 노출, 광고, 정산 관리까지 자동화된 환경을 제공받을 수 있어요.

![](/assets/overview_solution.CpmEhbkg.png)

### 노출 효과를 극대화할 수 있어요

출시한 서비스는 카테고리에 따라 토스 전체 탭의 홈에 노출돼요.\
키워드 기반의 검색을 통해서도 쉽게 접속할 수 있어요.\
토스가 가진 방대한 트래픽이 곧 앱인토스 파트너사의 기회가 돼요.

![](/assets/overview_nongame.B6P1qCbm.png)

![](/assets/overview_game.uxpDk_hV.png)

특히 토스 앱을 통한 푸시, 알림 발송과 토스 홈 광고 노출은 파트너사의 서비스로 강력한 트래픽을 유입시켜요.

![](/assets/overview_push.DVi_3sX3.png)

## 앱인토스 서비스에 대한 자세한 내용은 웨비나 영상에서 확인할 수 있어요.

### (1) 사업소개

### (2) 파트너십 밸류 : 기술&디자인 인프라

### (3) 파트너십 밸류 : 토스의 유저 트래픽

### (4) 파트너십 밸류 : 다양한 수익화 모델

### (5) 파트너십 프로세스

***

## 자주 묻는 질문

\<FaqAccordion :items="\[
{
q: '앱인토스 서비스는 누구를 대상으로 제공되나요?',
a: \`앱인토스 서비스를 이용 가능한 OS 최소 버전은 아래와 같아요.

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/runtime/asset.md'
---
# 에셋 최적화

앱인토스 Unity 게임의 모든 에셋을 효율적으로 관리하고 최적화하는 가이드예요.\
이 문서를 따라 하면 최상의 성능과 최소한의 메모리 사용량을 함께 달성할 수 있어요.

***

## 1. 텍스처 최적화

### 스마트 텍스처 압축 시스템

```c#
#if UNITY_EDITOR
using UnityEngine;
using UnityEditor;
using System.Collections.Generic;
using System.IO;

public class AppsInTossTextureOptimizer : EditorWindow
{
    [System.Serializable]
    public class TextureOptimizationRule
    {
        public string folderPath;
        public TextureImporterType textureType;
        public int maxSize;
        public TextureImporterFormat androidFormat;
        public TextureImporterFormat iOSFormat;
        public TextureImporterFormat webGLFormat;
        public bool generateMipMaps;
        public FilterMode filterMode;
        public TextureWrapMode wrapMode;
        public int compressionQuality;
    }
    
    [Header("앱인토스 최적화 규칙")]
    public List<TextureOptimizationRule> optimizationRules = new List<TextureOptimizationRule>();
    
    [MenuItem("AppsInToss/Texture Optimizer")]
    public static void ShowWindow()
    {
        GetWindow<AppsInTossTextureOptimizer>("Texture Optimizer");
    }
    
    void OnEnable()
    {
        InitializeDefaultRules();
    }
    
    void InitializeDefaultRules()
    {
        optimizationRules.Clear();
        
        // UI 텍스처 규칙
        optimizationRules.Add(new TextureOptimizationRule
        {
            folderPath = "UI",
            textureType = TextureImporterType.Sprite,
            maxSize = 1024,
            androidFormat = TextureImporterFormat.ETC2_RGBA8,
            iOSFormat = TextureImporterFormat.ASTC_6x6,
            webGLFormat = TextureImporterFormat.DXT5,
            generateMipMaps = false,
            filterMode = FilterMode.Bilinear,
            wrapMode = TextureWrapMode.Clamp,
            compressionQuality = 50
        });
        
        // 환경 텍스처 규칙
        optimizationRules.Add(new TextureOptimizationRule
        {
            folderPath = "Environment",
            textureType = TextureImporterType.Default,
            maxSize = 512,
            androidFormat = TextureImporterFormat.ETC2_RGB4,
            iOSFormat = TextureImporterFormat.ASTC_6x6,
            webGLFormat = TextureImporterFormat.DXT1,
            generateMipMaps = true,
            filterMode = FilterMode.Trilinear,
            wrapMode = TextureWrapMode.Repeat,
            compressionQuality = 50
        });
        
        // 캐릭터 텍스처 규칙
        optimizationRules.Add(new TextureOptimizationRule
        {
            folderPath = "Characters",
            textureType = TextureImporterType.Default,
            maxSize = 1024,
            androidFormat = TextureImporterFormat.ETC2_RGBA8,
            iOSFormat = TextureImporterFormat.ASTC_4x4,
            webGLFormat = TextureImporterFormat.DXT5,
            generateMipMaps = true,
            filterMode = FilterMode.Trilinear,
            wrapMode = TextureWrapMode.Clamp,
            compressionQuality = 75
        });
        
        // 앱인토스 브랜딩 텍스처 규칙 (고품질 유지)
        optimizationRules.Add(new TextureOptimizationRule
        {
            folderPath = "AppsInToss",
            textureType = TextureImporterType.Sprite,
            maxSize = 2048,
            androidFormat = TextureImporterFormat.RGBA32,
            iOSFormat = TextureImporterFormat.RGBA32,
            webGLFormat = TextureImporterFormat.RGBA32,
            generateMipMaps = false,
            filterMode = FilterMode.Trilinear,
            wrapMode = TextureWrapMode.Clamp,
            compressionQuality = 100
        });
    }
    
    void OnGUI()
    {
        GUILayout.Label("앱인토스 텍스처 최적화", EditorStyles.boldLabel);
        GUILayout.Space(10);
        
        // 전체 최적화 버튼
        if (GUILayout.Button("모든 텍스처 최적화", GUILayout.Height(30)))
        {
            OptimizeAllTextures();
        }
        
        GUILayout.Space(10);
        
        // 규칙별 최적화
        foreach (var rule in optimizationRules)
        {
            DrawOptimizationRule(rule);
        }
        
        GUILayout.Space(10);
        
        // 통계 표시
        DrawTextureStatistics();
    }
    
    void DrawOptimizationRule(TextureOptimizationRule rule)
    {
        GUILayout.BeginVertical("box");
        
        GUILayout.Label($"폴더: {rule.folderPath}", EditorStyles.boldLabel);
        GUILayout.Label($"최대 크기: {rule.maxSize}px");
        GUILayout.Label($"Android: {rule.androidFormat}");
        GUILayout.Label($"iOS: {rule.iOSFormat}");
        GUILayout.Label($"WebGL: {rule.webGLFormat}");
        
        if (GUILayout.Button($"{rule.folderPath} 폴더 최적화"))
        {
            OptimizeTexturesInFolder(rule);
        }
        
        GUILayout.EndVertical();
        GUILayout.Space(5);
    }
    
    void OptimizeAllTextures()
    {
        EditorUtility.DisplayProgressBar("텍스처 최적화", "모든 텍스처를 최적화하는 중...", 0);
        
        try
        {
            foreach (var rule in optimizationRules)
            {
                OptimizeTexturesInFolder(rule);
            }
            
            AssetDatabase.SaveAssets();
            AssetDatabase.Refresh();
            
            Debug.Log("앱인토스 텍스처 최적화 완료");
            ShowNotification(new GUIContent("최적화 완료!"));
        }
        finally
        {
            EditorUtility.ClearProgressBar();
        }
    }
    
    void OptimizeTexturesInFolder(TextureOptimizationRule rule)
    {
        string folderPath = Path.Combine("Assets", rule.folderPath);
        
        if (!Directory.Exists(folderPath))
        {
            Debug.LogWarning($"폴더를 찾을 수 없습니다: {folderPath}");
            return;
        }
        
        string[] textureGuids = AssetDatabase.FindAssets("t:Texture2D", new[] { folderPath });
        int optimizedCount = 0;
        
        for (int i = 0; i < textureGuids.Length; i++)
        {
            string guid = textureGuids[i];
            string assetPath = AssetDatabase.GUIDToAssetPath(guid);
            
            EditorUtility.DisplayProgressBar(
                $"{rule.folderPath} 텍스처 최적화", 
                $"{Path.GetFileName(assetPath)}", 
                (float)i / textureGuids.Length
            );
            
            if (OptimizeTexture(assetPath, rule))
            {
                optimizedCount++;
            }
        }
        
        Debug.Log($"{rule.folderPath} 폴더 최적화 완료: {optimizedCount}/{textureGuids.Length}개 텍스처");
    }
    
    bool OptimizeTexture(string assetPath, TextureOptimizationRule rule)
    {
        TextureImporter importer = AssetImporter.GetAtPath(assetPath) as TextureImporter;
        if (importer == null) return false;
        
        bool wasChanged = false;
        
        // 기본 설정
        if (importer.textureType != rule.textureType)
        {
            importer.textureType = rule.textureType;
            wasChanged = true;
        }
        
        if (importer.mipmapEnabled != rule.generateMipMaps)
        {
            importer.mipmapEnabled = rule.generateMipMaps;
            wasChanged = true;
        }
        
        if (importer.filterMode != rule.filterMode)
        {
            importer.filterMode = rule.filterMode;
            wasChanged = true;
        }
        
        if (importer.wrapMode != rule.wrapMode)
        {
            importer.wrapMode = rule.wrapMode;
            wasChanged = true;
        }
        
        // 플랫폼별 설정
        wasChanged |= SetPlatformSettings(importer, "Android", rule.maxSize, rule.androidFormat, rule.compressionQuality);
        wasChanged |= SetPlatformSettings(importer, "iPhone", rule.maxSize, rule.iOSFormat, rule.compressionQuality);
        wasChanged |= SetPlatformSettings(importer, "WebGL", rule.maxSize, rule.webGLFormat, rule.compressionQuality);
        
        // 앱인토스 특화 설정
        if (assetPath.Contains("AppsInToss") || assetPath.Contains("Toss"))
        {
            importer.userData = "AppsInToss_Asset";
            wasChanged = true;
        }
        
        if (wasChanged)
        {
            AssetDatabase.ImportAsset(assetPath, ImportAssetOptions.ForceUpdate);
            return true;
        }
        
        return false;
    }
    
    bool SetPlatformSettings(TextureImporter importer, string platform, int maxSize, 
                            TextureImporterFormat format, int quality)
    {
        var platformSettings = importer.GetPlatformTextureSettings(platform);
        bool changed = false;
        
        if (platformSettings.overridden != true)
        {
            platformSettings.overridden = true;
            changed = true;
        }
        
        if (platformSettings.maxTextureSize != maxSize)
        {
            platformSettings.maxTextureSize = maxSize;
            changed = true;
        }
        
        if (platformSettings.format != format)
        {
            platformSettings.format = format;
            changed = true;
        }
        
        if (platformSettings.compressionQuality != quality)
        {
            platformSettings.compressionQuality = quality;
            changed = true;
        }
        
        if (changed)
        {
            importer.SetPlatformTextureSettings(platformSettings);
        }
        
        return changed;
    }
    
    void DrawTextureStatistics()
    {
        GUILayout.Label("텍스처 통계", EditorStyles.boldLabel);
        
        var allTextures = AssetDatabase.FindAssets("t:Texture2D");
        long totalSize = 0;
        int uncompressedCount = 0;
        int oversizedCount = 0;
        
        foreach (string guid in allTextures)
        {
            string path = AssetDatabase.GUIDToAssetPath(guid);
            var texture = AssetDatabase.LoadAssetAtPath<Texture2D>(path);
            
            if (texture != null)
            {
                totalSize += UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(texture);
                
                var importer = AssetImporter.GetAtPath(path) as TextureImporter;
                if (importer != null)
                {
                    if (importer.textureCompression == TextureImporterCompression.Uncompressed)
                    {
                        uncompressedCount++;
                    }
                    
                    if (texture.width > 1024 || texture.height > 1024)
                    {
                        oversizedCount++;
                    }
                }
            }
        }
        
        GUILayout.Label($"전체 텍스처: {allTextures.Length}개");
        GUILayout.Label($"총 메모리 사용량: {totalSize / (1024 * 1024)}MB");
        GUILayout.Label($"압축되지 않은 텍스처: {uncompressedCount}개", uncompressedCount > 0 ? EditorStyles.boldLabel : EditorStyles.label);
        GUILayout.Label($"대형 텍스처 (1024px 초과): {oversizedCount}개", oversizedCount > 0 ? EditorStyles.boldLabel : EditorStyles.label);
        
        if (uncompressedCount > 0 || oversizedCount > 0)
        {
            EditorGUILayout.HelpBox("일부 텍스처가 최적화되지 않았습니다. 전체 최적화를 실행하세요.", MessageType.Warning);
        }
    }
}
#endif
```

***

## 2. 오디오 최적화

### 오디오 압축 및 관리

```c#
#if UNITY_EDITOR
public class AppsInTossAudioOptimizer : EditorWindow
{
    [System.Serializable]
    public class AudioOptimizationRule
    {
        public string folderPath;
        public AudioImporterSampleSettings mobileSettings;
        public AudioImporterSampleSettings webGLSettings;
        public bool force3D;
        public bool enableCompression;
        public float compressionQuality;
    }
    
    public List<AudioOptimizationRule> audioRules = new List<AudioOptimizationRule>();
    
    [MenuItem("AppsInToss/Audio Optimizer")]
    public static void ShowWindow()
    {
        GetWindow<AppsInTossAudioOptimizer>("Audio Optimizer");
    }
    
    void OnEnable()
    {
        InitializeAudioRules();
    }
    
    void InitializeAudioRules()
    {
        audioRules.Clear();
        
        // 음악 파일 규칙
        audioRules.Add(new AudioOptimizationRule
        {
            folderPath = "Audio/Music",
            mobileSettings = new AudioImporterSampleSettings
            {
                loadType = AudioClipLoadType.Streaming,
                compressionFormat = AudioCompressionFormat.Vorbis,
                quality = 0.7f,
                sampleRateSetting = AudioSampleRateSetting.OptimizeForSize
            },
            webGLSettings = new AudioImporterSampleSettings
            {
                loadType = AudioClipLoadType.Streaming,
                compressionFormat = AudioCompressionFormat.Vorbis,
                quality = 0.5f,
                sampleRateSetting = AudioSampleRateSetting.OptimizeForSize
            },
            force3D = false,
            enableCompression = true,
            compressionQuality = 70f
        });
        
        // 효과음 규칙
        audioRules.Add(new AudioOptimizationRule
        {
            folderPath = "Audio/SFX",
            mobileSettings = new AudioImporterSampleSettings
            {
                loadType = AudioClipLoadType.DecompressOnLoad,
                compressionFormat = AudioCompressionFormat.ADPCM,
                quality = 1.0f,
                sampleRateSetting = AudioSampleRateSetting.PreserveSampleRate
            },
            webGLSettings = new AudioImporterSampleSettings
            {
                loadType = AudioClipLoadType.CompressedInMemory,
                compressionFormat = AudioCompressionFormat.Vorbis,
                quality = 0.8f,
                sampleRateSetting = AudioSampleRateSetting.OptimizeForSize
            },
            force3D = false,
            enableCompression = true,
            compressionQuality = 80f
        });
        
        // 앱인토스 특화 오디오 (토스 사운드)
        audioRules.Add(new AudioOptimizationRule
        {
            folderPath = "Audio/Toss",
            mobileSettings = new AudioImporterSampleSettings
            {
                loadType = AudioClipLoadType.DecompressOnLoad,
                compressionFormat = AudioCompressionFormat.PCM,
                quality = 1.0f,
                sampleRateSetting = AudioSampleRateSetting.PreserveSampleRate
            },
            webGLSettings = new AudioImporterSampleSettings
            {
                loadType = AudioClipLoadType.DecompressOnLoad,
                compressionFormat = AudioCompressionFormat.PCM,
                quality = 1.0f,
                sampleRateSetting = AudioSampleRateSetting.PreserveSampleRate
            },
            force3D = false,
            enableCompression = false, // 토스 브랜드 오디오는 고품질 유지
            compressionQuality = 100f
        });
    }
    
    void OnGUI()
    {
        GUILayout.Label("앱인토스 오디오 최적화", EditorStyles.boldLabel);
        
        if (GUILayout.Button("모든 오디오 최적화"))
        {
            OptimizeAllAudio();
        }
        
        foreach (var rule in audioRules)
        {
            DrawAudioRule(rule);
        }
        
        DrawAudioStatistics();
    }
    
    void OptimizeAllAudio()
    {
        foreach (var rule in audioRules)
        {
            OptimizeAudioInFolder(rule);
        }
        
        AssetDatabase.SaveAssets();
        AssetDatabase.Refresh();
        Debug.Log("오디오 최적화 완료");
    }
    
    void OptimizeAudioInFolder(AudioOptimizationRule rule)
    {
        string folderPath = Path.Combine("Assets", rule.folderPath);
        string[] audioGuids = AssetDatabase.FindAssets("t:AudioClip", new[] { folderPath });
        
        foreach (string guid in audioGuids)
        {
            string assetPath = AssetDatabase.GUIDToAssetPath(guid);
            OptimizeAudioClip(assetPath, rule);
        }
    }
    
    void OptimizeAudioClip(string assetPath, AudioOptimizationRule rule)
    {
        AudioImporter importer = AssetImporter.GetAtPath(assetPath) as AudioImporter;
        if (importer == null) return;
        
        // 모바일 플랫폼 설정
        importer.SetOverrideSampleSettings("Android", rule.mobileSettings);
        importer.SetOverrideSampleSettings("iOS", rule.mobileSettings);
        
        // WebGL 설정
        importer.SetOverrideSampleSettings("WebGL", rule.webGLSettings);
        
        // 3D 설정
        if (rule.force3D)
        {
            importer.threeD = true;
        }
        
        AssetDatabase.ImportAsset(assetPath);
    }
    
    void DrawAudioRule(AudioOptimizationRule rule)
    {
        GUILayout.BeginVertical("box");
        GUILayout.Label($"폴더: {rule.folderPath}");
        GUILayout.Label($"모바일 형식: {rule.mobileSettings.compressionFormat}");
        GUILayout.Label($"WebGL 형식: {rule.webGLSettings.compressionFormat}");
        
        if (GUILayout.Button($"{rule.folderPath} 최적화"))
        {
            OptimizeAudioInFolder(rule);
        }
        
        GUILayout.EndVertical();
    }
    
    void DrawAudioStatistics()
    {
        var allAudio = AssetDatabase.FindAssets("t:AudioClip");
        long totalSize = 0;
        int uncompressedCount = 0;
        
        foreach (string guid in allAudio)
        {
            string path = AssetDatabase.GUIDToAssetPath(guid);
            var clip = AssetDatabase.LoadAssetAtPath<AudioClip>(path);
            
            if (clip != null)
            {
                totalSize += UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(clip);
                
                var importer = AssetImporter.GetAtPath(path) as AudioImporter;
                if (importer?.defaultSampleSettings.compressionFormat == AudioCompressionFormat.PCM)
                {
                    uncompressedCount++;
                }
            }
        }
        
        GUILayout.Label("오디오 통계", EditorStyles.boldLabel);
        GUILayout.Label($"전체 오디오 클립: {allAudio.Length}개");
        GUILayout.Label($"총 메모리 사용량: {totalSize / (1024 * 1024)}MB");
        GUILayout.Label($"압축되지 않은 클립: {uncompressedCount}개");
    }
}
#endif
```

***

## 3. 메시 최적화

### 자동 메시 최적화 시스템

```c#
#if UNITY_EDITOR
public class AppsInTossMeshOptimizer : EditorWindow
{
    [Header("메시 최적화 설정")]
    public int maxVertexCount = 1000;
    public bool optimizeMeshes = true;
    public bool generateLightmapUVs = false;
    public bool keepQuads = false;
    public bool weldVertices = true;
    public float weldingThreshold = 1e-4f;
    
    [Header("LOD 생성")]
    public bool generateLODs = true;
    public float[] lodReductions = { 0.8f, 0.5f, 0.25f };
    public float[] lodDistances = { 10f, 25f, 50f };
    
    [MenuItem("AppsInToss/Mesh Optimizer")]
    public static void ShowWindow()
    {
        GetWindow<AppsInTossMeshOptimizer>("Mesh Optimizer");
    }
    
    void OnGUI()
    {
        GUILayout.Label("앱인토스 메시 최적화", EditorStyles.boldLabel);
        
        maxVertexCount = EditorGUILayout.IntField("최대 버텍스 수", maxVertexCount);
        optimizeMeshes = EditorGUILayout.Toggle("메시 최적화", optimizeMeshes);
        weldVertices = EditorGUILayout.Toggle("버텍스 결합", weldVertices);
        
        if (weldVertices)
        {
            weldingThreshold = EditorGUILayout.FloatField("결합 임계값", weldingThreshold);
        }
        
        GUILayout.Space(10);
        
        generateLODs = EditorGUILayout.Toggle("LOD 자동 생성", generateLODs);
        
        if (generateLODs)
        {
            EditorGUILayout.LabelField("LOD 감소율:");
            for (int i = 0; i < lodReductions.Length; i++)
            {
                lodReductions[i] = EditorGUILayout.Slider($"LOD {i+1}", lodReductions[i], 0.1f, 1f);
            }
            
            EditorGUILayout.LabelField("LOD 거리:");
            for (int i = 0; i < lodDistances.Length; i++)
            {
                lodDistances[i] = EditorGUILayout.FloatField($"LOD {i+1} 거리", lodDistances[i]);
            }
        }
        
        GUILayout.Space(10);
        
        if (GUILayout.Button("선택된 메시 최적화"))
        {
            OptimizeSelectedMeshes();
        }
        
        if (GUILayout.Button("모든 메시 최적화"))
        {
            OptimizeAllMeshes();
        }
        
        GUILayout.Space(10);
        DrawMeshStatistics();
    }
    
    void OptimizeSelectedMeshes()
    {
        var selection = Selection.gameObjects;
        
        foreach (var go in selection)
        {
            OptimizeGameObject(go);
        }
        
        Debug.Log($"선택된 {selection.Length}개 오브젝트 최적화 완료");
    }
    
    void OptimizeAllMeshes()
    {
        var allMeshFilters = FindObjectsOfType<MeshFilter>();
        
        EditorUtility.DisplayProgressBar("메시 최적화", "모든 메시를 최적화하는 중...", 0);
        
        try
        {
            for (int i = 0; i < allMeshFilters.Length; i++)
            {
                EditorUtility.DisplayProgressBar(
                    "메시 최적화", 
                    $"{allMeshFilters[i].name} 최적화 중...", 
                    (float)i / allMeshFilters.Length
                );
                
                OptimizeGameObject(allMeshFilters[i].gameObject);
            }
        }
        finally
        {
            EditorUtility.ClearProgressBar();
        }
        
        Debug.Log($"전체 {allMeshFilters.Length}개 메시 최적화 완료");
    }
    
    void OptimizeGameObject(GameObject go)
    {
        var meshFilter = go.GetComponent<MeshFilter>();
        if (meshFilter?.sharedMesh == null) return;
        
        var originalMesh = meshFilter.sharedMesh;
        
        // 버텍스 수 체크
        if (originalMesh.vertexCount > maxVertexCount)
        {
            Debug.LogWarning($"{go.name}: 버텍스 수가 많습니다 ({originalMesh.vertexCount} > {maxVertexCount})");
        }
        
        // 메시 최적화
        if (optimizeMeshes)
        {
            OptimizeMesh(originalMesh);
        }
        
        // LOD 생성
        if (generateLODs && !go.GetComponent<LODGroup>())
        {
            CreateLODGroup(go);
        }
        
        // 앱인토스 특화 최적화
        ApplyAppsInTossOptimizations(go);
    }
    
    void OptimizeMesh(Mesh mesh)
    {
        if (weldVertices)
        {
            MeshUtility.Optimize(mesh);
        }
        
        // 법선 벡터 재계산
        mesh.RecalculateNormals();
        
        // 바운딩 박스 재계산
        mesh.RecalculateBounds();
        
        // 탄젠트 재계산
        mesh.RecalculateTangents();
    }
    
    void CreateLODGroup(GameObject go)
    {
        var lodGroup = go.AddComponent<LODGroup>();
        var lods = new LOD[lodReductions.Length + 1]; // +1 for original
        
        // 원본 메시 (LOD 0)
        var renderers = go.GetComponentsInChildren<Renderer>();
        lods[0] = new LOD(1.0f, renderers);
        
        // 감소된 LOD들 생성
        for (int i = 0; i < lodReductions.Length; i++)
        {
            var lodGO = CreateReducedMesh(go, lodReductions[i], i + 1);
            if (lodGO != null)
            {
                float screenHeight = 1.0f / (lodDistances[i] / 10f);
                lods[i + 1] = new LOD(screenHeight, lodGO.GetComponentsInChildren<Renderer>());
            }
        }
        
        lodGroup.SetLODs(lods);
    }
    
    GameObject CreateReducedMesh(GameObject original, float reduction, int lodLevel)
    {
        var meshFilter = original.GetComponent<MeshFilter>();
        if (meshFilter?.sharedMesh == null) return null;
        
        // 간단한 메시 감소 (실제로는 더 정교한 알고리즘 필요)
        var lodGO = new GameObject($"{original.name}_LOD{lodLevel}");
        lodGO.transform.parent = original.transform.parent;
        lodGO.transform.localPosition = original.transform.localPosition;
        lodGO.transform.localRotation = original.transform.localRotation;
        lodGO.transform.localScale = original.transform.localScale;
        
        var lodMeshFilter = lodGO.AddComponent<MeshFilter>();
        var lodRenderer = lodGO.AddComponent<MeshRenderer>();
        
        // 간소화된 메시 생성
        var simplifiedMesh = CreateSimplifiedMesh(meshFilter.sharedMesh, reduction);
        lodMeshFilter.sharedMesh = simplifiedMesh;
        lodRenderer.sharedMaterial = original.GetComponent<MeshRenderer>().sharedMaterial;
        
        return lodGO;
    }
    
    Mesh CreateSimplifiedMesh(Mesh originalMesh, float reduction)
    {
        // 간단한 버텍스 간소화 (실제로는 Mesh Simplification 라이브러리 사용 권장)
        var vertices = originalMesh.vertices;
        var triangles = originalMesh.triangles;
        var normals = originalMesh.normals;
        var uvs = originalMesh.uv;
        
        int targetVertexCount = Mathf.RoundToInt(vertices.Length * reduction);
        
        if (targetVertexCount >= vertices.Length) return originalMesh;
        
        // 단순한 버텍스 샘플링 (실제로는 더 정교한 간소화 필요)
        var step = vertices.Length / targetVertexCount;
        var newVertices = new List<Vector3>();
        var newNormals = new List<Vector3>();
        var newUVs = new List<Vector2>();
        
        for (int i = 0; i < vertices.Length; i += step)
        {
            newVertices.Add(vertices[i]);
            if (i < normals.Length) newNormals.Add(normals[i]);
            if (i < uvs.Length) newUVs.Add(uvs[i]);
        }
        
        var simplifiedMesh = new Mesh();
        simplifiedMesh.vertices = newVertices.ToArray();
        simplifiedMesh.normals = newNormals.ToArray();
        simplifiedMesh.uv = newUVs.ToArray();
        
        // 삼각형 재구성 (매우 간단한 버전)
        var newTriangles = new List<int>();
        for (int i = 0; i < newVertices.Count - 2; i++)
        {
            newTriangles.Add(i);
            newTriangles.Add(i + 1);
            newTriangles.Add(i + 2);
        }
        
        simplifiedMesh.triangles = newTriangles.ToArray();
        simplifiedMesh.RecalculateBounds();
        
        return simplifiedMesh;
    }
    
    void ApplyAppsInTossOptimizations(GameObject go)
    {
        // 앱인토스 특화 최적화 태그 추가
        if (go.name.Contains("Toss") || go.name.Contains("AppsInToss"))
        {
            go.tag = "AppsInTossAsset";
        }
        
        // 모바일 최적화 설정
        var meshRenderer = go.GetComponent<MeshRenderer>();
        if (meshRenderer != null)
        {
            // 라이트맵 설정 최적화
            meshRenderer.lightmapIndex = -1;
            meshRenderer.realtimeLightmapIndex = -1;
            
            // 그림자 최적화
            if (go.name.Contains("Background") || go.name.Contains("Environment"))
            {
                meshRenderer.shadowCastingMode = UnityEngine.Rendering.ShadowCastingMode.Off;
            }
        }
    }
    
    void DrawMeshStatistics()
    {
        GUILayout.Label("메시 통계", EditorStyles.boldLabel);
        
        var allMeshFilters = FindObjectsOfType<MeshFilter>();
        int totalVertices = 0;
        int totalTriangles = 0;
        int highPolyCount = 0;
        long totalMemory = 0;
        
        foreach (var mf in allMeshFilters)
        {
            if (mf.sharedMesh != null)
            {
                totalVertices += mf.sharedMesh.vertexCount;
                totalTriangles += mf.sharedMesh.triangles.Length / 3;
                totalMemory += UnityEngine.Profiling.Profiler.GetRuntimeMemorySizeLong(mf.sharedMesh);
                
                if (mf.sharedMesh.vertexCount > maxVertexCount)
                {
                    highPolyCount++;
                }
            }
        }
        
        GUILayout.Label($"총 메시 수: {allMeshFilters.Length}");
        GUILayout.Label($"총 버텍스: {totalVertices:N0}");
        GUILayout.Label($"총 삼각형: {totalTriangles:N0}");
        GUILayout.Label($"메모리 사용량: {totalMemory / (1024 * 1024)}MB");
        
        if (highPolyCount > 0)
        {
            GUILayout.Label($"고폴리곤 메시: {highPolyCount}개", EditorStyles.boldLabel);
            EditorGUILayout.HelpBox($"{highPolyCount}개의 메시가 {maxVertexCount} 버텍스를 초과합니다.", MessageType.Warning);
        }
    }
}
#endif
```

에셋 최적화는 앱인토스 게임 성능의 기초예요.\
텍스처, 오디오, 메시를 체계적으로 최적화하여 메모리 사용량을 최소화하고 로딩 성능을 극대화하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/연락처/fetchContacts.md
---

# 연락처 가져오기

## `fetchContacts`

`fetchContacts` 는 사용자의 연락처 목록을 페이지 단위로 가져오는 함수예요.

## 시그니처

사용자의 연락처 목록을 페이지 단위로 가져오는 함수예요.

## 시그니처

```typescript
function fetchContacts(options: {
  size: number;
  offset: number;
  query?: {
    contains?: string;
  };
}): Promise<ContactResult>;
```

### 파라미터

### 프로퍼티

### 반환 값

연락처 목록과 페이지네이션 정보를 포함한 객체를 반환해요.

* `result`: 가져온 연락처 목록이에요.
* `nextOffset`: 다음 호출에 사용할 오프셋 값이에요. 더 가져올 연락처가 없으면 `null`이에요.
* `done`: 모든 연락처를 다 가져왔는지 여부를 나타내요. 모두 가져왔다면 `true`예요.

## FetchContactsPermissionError

연락처 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof FetchContactsPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class FetchContactsPermissionError extends PermissionError {
    constructor();
}
```

## 예제

### 특정 문자열이 포함된 연락처 목록 가져오기

연락처 목록을 가져오는 예제예요.
"권한 확인하기"버튼을 눌러서 현재 연락처 읽기 권한을 확인해요.
사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`FetchContactsPermissionError`](./FetchContactsPermissionError)를 반환해요.
"권한 요청하기"버튼을 눌러서 연락처 읽기 권한을 요청할 수 있어요.

::: code-group

```js [js]
import { fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/web-framework';

async function handleFetchContacts() {
  try {
    const response = await fetchContacts({
      size: 10,
      offset: 0,
      query: { contains: '김' },
    });
    
    return response;
  } catch (error) {
    if (error instanceof FetchContactsPermissionError) {
      console.log('연락처 읽기 권한 없음');
    }
    console.error('연락처를 가져오는 데 실패했어요:', error);
  }
}

async function handleGetPermissionForFetchContacts() {
  const permission = await fetchContacts.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForFetchContacts() {
  const permission = await fetchContacts.openPermissionDialog();
  return permission;
}
```

```tsx [React]
import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function ContactsList() {
  const [contacts, setContacts] = useState<{
    result: ContactEntity[];
    nextOffset: number | null;
    done: boolean;
  }>({
    result: [],
    nextOffset: null,
    done: false,
  });

  const handlePress = async () => {
    try {
      if (contacts.done) {
        console.log('모든 연락처를 가져왔어요.');
        return;
      }

      const response = await fetchContacts({
        size: 10,
        offset: contacts.nextOffset ?? 0,
        query: { contains: '김' },
      });
      setContacts((prev) => ({
        result: [...prev.result, ...response.result],
        nextOffset: response.nextOffset,
        done: response.done,
      }));
    } catch (error) {
      if (error instanceof FetchContactsPermissionError) {
        console.log('연락처 읽기 권한 없음');
      }
      console.error('연락처를 가져오는 데 실패했어요:', error);
    }
  };

  return (
    <div>
      {contacts.result.map((contact, index) => (
        <span key={index}>
          {contact.name}: {contact.phoneNumber}
        </span>
      ))}
      <input type="button"
        value={contacts.done ? '모든 연락처를 가져왔어요.' : '다음 연락처 가져오기'}
        disabled={contacts.done}
        onClick={handlePress}
      />
      <input type="button"
        value="권한 확인하기"
        onClick={async () => {
          const permission = await fetchContacts.getPermission();
          alert(permission);
        }}
      />
      <input type="button"
        value="권한 요청하기"
        onClick={async () => {
          const permission = await fetchContacts.openPermissionDialog();
          alert(permission);
        }}
      />
    </div>
  );
}
```

```tsx [React Native]
import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function ContactsList() {
  const [contacts, setContacts] = useState<{
    result: ContactEntity[];
    nextOffset: number | null;
    done: boolean;
  }>({
    result: [],
    nextOffset: null,
    done: false,
  });

  const handlePress = async () => {
    try {
      if (contacts.done) {
        console.log('모든 연락처를 가져왔어요.');
        return;
      }

      const response = await fetchContacts({
        size: 10,
        offset: contacts.nextOffset ?? 0,
        query: { contains: '김' },
      });
      setContacts((prev) => ({
        result: [...prev.result, ...response.result],
        nextOffset: response.nextOffset,
        done: response.done,
      }));
    } catch (error) {
      if (error instanceof FetchContactsPermissionError) {
        console.log('연락처 읽기 권한 없음');
      }
      console.error('연락처를 가져오는 데 실패했어요:', error);
    }
  };

  return (
    <View>
      {contacts.result.map((contact, index) => (
        <Text key={index}>
          {contact.name}: {contact.phoneNumber}
        </Text>
      ))}
      <Button
        title={contacts.done ? '모든 연락처를 가져왔어요.' : '다음 연락처 가져오기'}
        disabled={contacts.done}
        onPress={handlePress}
      />
      <Button
        title="권한 확인하기"
        onPress={async () => {
          const permission = await fetchContacts.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="권한 요청하기"
        onPress={async () => {
          const permission = await fetchContacts.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-contacts](https://github.com/toss/apps-in-toss-examples/tree/main/with-contacts) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/분석/LoggingArea.md
---

# 영역 단위로 기록하기

## `LoggingArea`

`LoggingArea` 함수로 여러 컴포넌트의 텍스트를 하나로 묶어서 로그를 남길 수 있어요. 지정한 영역이 노출되거나 클릭 했을 때 로그를 수집할 수 있어요.

## 시그니처

```typescript
function LoggingArea({ children, params: _params, ...props }: LoggingAreaProps): import("react/jsx-runtime").JSX.Element;
```

## 예제

### 여러 컴포넌트를 하나의 영역으로 묶어서 분석하는 예시

```tsx
import { Analytics } from '@apps-in-toss/framework';
import { View, Text } from 'react-native';

// 영역 안의 노출이나 클릭 정보를 자동으로 수집해요.
function TrackElements() {
  return (
    <Analytics.Area>
      <View>
        <Text>Hello</Text>
        <Text>World!</Text>
      </View>
    </Analytics.Area>
  );
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/tutorials/examples.md'
description: >-
  앱인토스 미니앱 개발을 위한 실전 예제 코드 모음입니다. Vue, React, jQuery 등 다양한 프레임워크로 구현된 완성형 미니앱
  예제부터 카메라, 위치 정보, 광고, 인앱 결제, 로그인, 공유 등 주요 네이티브 기능을 활용하는 방법까지 포함합니다.
---

# 예제 코드 모음

## 튜토리얼 예제

* [weekly-todo-vue](https://developers-apps-in-toss.toss.im/examples/weekly-todo-vue.txt) - Vue 3 Composition API를 활용한 주간 할일 관리 미니앱입니다. 로컬 스토리지를 이용한 데이터 저장, 요일별 할일 관리 기능을 포함합니다.
* [weekly-todo-react](https://developers-apps-in-toss.toss.im/examples/weekly-todo-react.txt) - React Hooks를 활용한 주간 할일 관리 미니앱입니다. useState, useEffect를 이용한 상태 관리와 로컬 스토리지 연동을 보여줍니다.
* [weekly-todo-jquery](https://developers-apps-in-toss.toss.im/examples/weekly-todo-jquery.txt) - jQuery를 활용한 주간 할일 관리 미니앱입니다. 간단한 DOM 조작과 이벤트 핸들링으로 구현한 예제입니다.
* [random-balls](https://developers-apps-in-toss.toss.im/examples/random-balls.txt) - Canvas API를 활용한 랜덤 볼 애니메이션 예제입니다. requestAnimationFrame을 이용한 부드러운 애니메이션 구현 방법을 보여줍니다.

## 기능별 예제

### 인증 및 로그인

* [with-app-login](https://developers-apps-in-toss.toss.im/examples/with-app-login.txt) - 토스 앱 로그인 기능을 구현한 예제입니다. 사용자 인증, 토큰 관리, 로그인 상태 유지 방법을 다룹니다.

### 광고

* [with-rewarded-ad](https://developers-apps-in-toss.toss.im/examples/with-rewarded-ad.txt) - 리워드 광고 노출 및 보상 지급 로직을 구현한 예제입니다. 사용자가 광고를 시청한 후 게임 내 코인이나 아이템을 지급하는 방법을 보여줍니다.
* [with-interstitial-ad](https://developers-apps-in-toss.toss.im/examples/with-interstitial-ad.txt) - 전면 광고(인터스티셜 광고) 노출 기능을 구현한 예제입니다. 적절한 타이밍에 전면 광고를 표시하는 방법을 다룹니다.

### 결제

* [with-in-app-purchase](https://developers-apps-in-toss.toss.im/examples/with-in-app-purchase.txt) - 인앱 구매 기능을 구현한 예제입니다. 상품 조회, 구매 요청, 구매 검증 프로세스를 포함합니다.

### 게임

* [with-game](https://developers-apps-in-toss.toss.im/examples/with-game.txt) - 게임 센터 연동 기능을 통합한 예제입니다. 점수 기록, 리더보드, 업적 시스템 등 게임 관련 기능을 포괄적으로 다룹니다.

### 위치

* [with-location-tracking](https://developers-apps-in-toss.toss.im/examples/with-location-tracking.txt) - 실시간 위치 추적 기능을 구현한 예제입니다. 사용자의 이동 경로를 추적하고 지도에 표시하는 방법을 보여줍니다.
* [with-location-once](https://developers-apps-in-toss.toss.im/examples/with-location-once.txt) - 현재 위치를 일회성으로 조회하는 예제입니다. 주변 상점 찾기, 배달 주소 설정 등에 활용할 수 있습니다.
* [with-location-callback](https://developers-apps-in-toss.toss.im/examples/with-location-callback.txt) - 위치 정보 변경 시 콜백을 받아 처리하는 예제입니다. 위치 기반 알림이나 실시간 배송 추적에 활용할 수 있습니다.

### 미디어

* [with-camera](https://developers-apps-in-toss.toss.im/examples/with-camera.txt) - 카메라로 사진 촬영 및 업로드 기능을 구현한 예제입니다. 프로필 사진 변경, 상품 등록 등에 활용할 수 있습니다.
* [with-album-photos](https://developers-apps-in-toss.toss.im/examples/with-album-photos.txt) - 앨범에서 여러 장의 사진을 선택하는 기능을 구현한 예제입니다. 다중 이미지 업로드, 갤러리 기능 구현 시 참고할 수 있습니다.

### 연락처

* [with-contacts](https://developers-apps-in-toss.toss.im/examples/with-contacts.txt) - 디바이스 연락처 정보에 접근하고 조회하는 예제입니다. 친구 초대, 연락처 동기화 기능에 활용할 수 있습니다.
* [with-contacts-viral](https://developers-apps-in-toss.toss.im/examples/with-contacts-viral.txt) - 연락처 기반 바이럴 마케팅 기능을 구현한 예제입니다. 친구 추천, 초대 보상 시스템 등을 포함합니다.

### 공유

* [with-share-text](https://developers-apps-in-toss.toss.im/examples/with-share-text.txt) - 텍스트 콘텐츠를 다른 앱으로 공유하는 기능을 구현한 예제입니다. 메시지, SNS 공유 등에 활용할 수 있습니다.
* [with-share-link](https://developers-apps-in-toss.toss.im/examples/with-share-link.txt) - 링크 URL을 공유하는 기능을 구현한 예제입니다. 앱 초대 링크, 상품 공유, 컨텐츠 바이럴에 활용할 수 있습니다.

### 시스템 정보

* [with-platform-os](https://developers-apps-in-toss.toss.im/examples/with-platform-os.txt) - 사용자의 OS 플랫폼 정보(iOS/Android)를 확인하는 예제입니다. 플랫폼별 UI/UX 분기 처리에 활용할 수 있습니다.
* [with-operational-environment](https://developers-apps-in-toss.toss.im/examples/with-operational-environment.txt) - 미니앱의 운영 환경(개발/스테이징/프로덕션)을 확인하는 예제입니다. 환경별 API 엔드포인트 설정에 활용할 수 있습니다.
* [with-network-status](https://developers-apps-in-toss.toss.im/examples/with-network-status.txt) - 네트워크 연결 상태를 확인하고 변경을 감지하는 예제입니다. 오프라인 모드 처리, 네트워크 에러 핸들링에 활용할 수 있습니다.
* [with-locale](https://developers-apps-in-toss.toss.im/examples/with-locale.txt) - 사용자의 언어 및 지역 설정을 확인하는 예제입니다. 다국어 지원, 지역별 컨텐츠 제공에 활용할 수 있습니다.

### 데이터 저장 및 클립보드

* [with-storage](https://developers-apps-in-toss.toss.im/examples/with-storage.txt) - 로컬 스토리지를 활용한 데이터 저장 및 조회 예제입니다. 사용자 설정, 게임 진행 상황, 임시 데이터 저장에 활용할 수 있습니다.
* [with-clipboard-text](https://developers-apps-in-toss.toss.im/examples/with-clipboard-text.txt) - 클립보드에 텍스트를 복사하고 붙여넣는 기능을 구현한 예제입니다. 쿠폰 코드 복사, 공유 링크 복사 등에 활용할 수 있습니다.

### UI 피드백

* [with-haptic-feedback](https://developers-apps-in-toss.toss.im/examples/with-haptic-feedback.txt) - 햅틱(진동) 피드백을 구현한 예제입니다. 버튼 클릭, 성공/실패 알림, 게임 액션 등에 촉각 피드백을 제공하여 사용자 경험을 향상시킬 수 있습니다.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/overlay/useOverlayBase.md
---

# 오버레이 생성·관리하기

## `useOverlayBase`

`useOverlayBase`는 Dialog처럼 별도의 UI 레이어를 띄우는 Overlay를 선언적으로 다루기 위한 hook이에요.
이 hook을 사용하려면 사용하는 화면의 \_app.tsx에 를 추가해야 해요.
Promise와 함께 사용할 수 있어서 비동기 작업과 결합해 Overlay를 제어할 때 유용해요.
여러 개의 Overlay가 필요할 때는 useOverlayBase를 여러 번 호출하면 돼요.

## 시그니처

```typescript
function useOverlayBase({ exitOnUnmount }?: Options): {
    open: (overlayElement: CreateOverlayElement) => void;
    close: () => void;
};
```

### 파라미터

useOverlayBase를 호출한 컴포넌트가 unmount될 때 overlay도 자동으로 unmount(=exit)되도록 설정하는 옵션이예요.
만약 exitOnUnmount를 false로 설정하면, useOverlayBase를 호출한 컴포넌트가 unmount되어도 overlay는 자동으로 unmount되지 않고 등록된 overlay가 메모리에 계속 남아 있어요.
이럴 때는 원하는 시점에 직접 exit 함수를 호출해서 overlay를 수동으로 unmount 해주세요.

### 반환 값

`open` 함수는 `overlayElement`를 받아 Overlay를 표시하고, `close` 함수는 등록된 Overlay를 닫아요.

## 예제

```tsx
// _app.tsx
import { OverlayProvider } from '@apps-in-toss/framework';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <OverlayProvider>
      <Component {...pageProps} />
    </OverlayProvider>
  )
}
```

```tsx
// Page.tsx
import { useOverlayBase } from '@react-native-bedrock/core';

const overlay = useOverlayBase();
const openFooConfirmDialog = () => {
  return new Promise<boolean>(resolve => {
    overlay.open(({ isOpen, close }) => (
      <FooConfirmDialog
        open={isOpen}
        onClose={() => {
          resolve(false);
          close();
        }}
        onConfirm={() => {
          resolve(true);
          close();
        }}
      />
    ));
  });
};

await openFooConfirmDialog();
// ConfirmDialog의 confirmButton을 누르거나 onClose가 호출된 후
console.log('dialog closed');
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  이동/openURL.md
---

# 외부 URL 열기

`openURL` 함수는 지정한 URL을 기기의 기본 브라우저나 연결된 앱에서 열 수 있게 해주는 유틸리티예요.\
이 함수는 React Native의 [`Linking.openURL`](https://reactnative.dev/docs/0.72/linking#openurl)을 내부적으로 사용해요.

## 시그니처

```typescript
function openURL(url: string): Promise<any>;
```

### 파라미터

### 반환 값

## 예제

### 외부 웹사이트 열기

```tsx
import { openURL } from '@granite-js/react-native';
import { Button } from 'react-native';

function Page() {
  const handlePress = () => {
    openURL('https://google.com');
  };

  return <Button title="구글 웹사이트 열기" onPress={handlePress} />;
}
```

### 딥링크 열기

```tsx
import { openURL } from '@granite-js/react-native';

openURL('intoss://{appName}'); 
```

## 참고사항

* 외부 URL을 열 수 없는 경우(잘못된 스킴, 네트워크 차단 등)에는 Promise가 reject될 수 있어요.
* iOS에서는 `Info.plist` 파일의 `LSApplicationQueriesSchemes`에 허용할 스킴을 추가해야 해요.
* WebView 환경에서는 브라우저 탭이 새로 열리며, 기본 앱에서는 외부 앱 또는 브라우저로 전환돼요.

---

---
url: 'https://developers-apps-in-toss.toss.im/marketing/guideline.md'
description: >-
  앱인토스 미니앱 서비스 외부 광고 및 마케팅 가이드입니다. 마케팅 메시지 작성법, 토스 미니앱 배지, 디자인 템플릿, 앱인토스 로고 활용
  방법을 확인하세요.
---

# 외부 광고 가이드

앱인토스에 론칭한 미니앱 서비스 마케팅을 진행할 때 필요한 ‘마케팅 메세지’, ‘토스 미니앱 배지’, ‘마케팅 디자인 템플릿’ 등을 확인할 수 있어요. 이를 통해 파트너사는 보다 효과적인 마케팅을 할 수 있어요.

## 1. 외부 광고 가이드가 무엇인가요?

앱인토스의 외부 광고 가이드는 앱인토스에 론칭한 미니앱 서비스를 외부 채널에서 홍보할 때 지켜야 할 기준이에요.
**’토스 미니앱’** 과 **‘앱인토스’ 브랜드를 정확하게 사용**하고, **정책을 준수**할 수 있도록 돕는 게 목적이에요.

::: tip  **본 가이드라인에 사용되는 용어의 정의를 알려 드려요**

* **‘앱인토스(Apps-in-Toss)’** 는 미니앱 론칭을 지원하는 시스템이자 생태계를 뜻하는 공식 명칭이에요. 이 용어는 백엔드와 파트너사를 대상으로 사용돼요.
* **‘토스 미니앱(Toss Mini App)’** 은 토스 앱 내에서 B2C 사용자를 대상으로 제공되는 UI 및 마케팅·홍보 용어를 뜻해요.
* **\[서비스명]** 은 토스 미니앱에서 노출되고 있는 이름이자, 토스 앱에서 검색할 수 있는 이름이에요.
  :::

## 2. 마케팅 **메시지는 어떻게 작성해야 하나요?**

앱인토스에 론칭한 미니앱을 마케팅 할 때 헤드라인과 카피문구는 토스 앱의 사용자 경험을 고려하여 작성해야 해요.

‘토스’에서 론칭한 서비스를 찾아볼 수 있도록 유도하는 **콜투액션(Call to Action, ‘CTA’)** 또는 **‘토스 미니앱’** 으로 인지할 수 있는 문구를 활용해야 해요.

### 대표 문구 템플릿은 아래와 같아요.

아래와 같은 메시지와 소셜 해시태그(#)를 활용해서 미니앱 서비스를 알려보세요.

* **\[서비스명]을 ‘토스 미니앱’으로 만나보세요.**
* **‘토스’에서 \[서비스명]을 만나보세요.**
* **‘토스’에서 \[서비스명]을 검색해보세요.**
* **\[서비스명]을 토스에서 설치 없이 바로 사용해보세요.**
* **#서비스명 #토스미니앱 #토스에서만나보세요**

### CTA 버튼 예시는 아래와 같아요.

퍼포먼스 마케팅과 같이 미니앱 서비스로 전환을 유도할 때 아래와 같은 메시지를 활용해서 앱 이용을 유도해보세요.

* **토스 미니앱 사용하러 가기**
* **토스에서 \[서비스명] 사용하기**
* **토스에서 \[서비스명] 써보기**

### ‘토스 미니앱 론칭’ 외에 용어는 사용이 어려워요.

마케팅 채널에서는 **‘토스 미니앱 론칭’으로만 표현**이 되어야 하고, 아래와 같은 표현을 사용하는 것은 지양해주세요.

* **토스 공식 파트너사**
* **토스 입점사**
* **토스 제휴사**

## 3. 토스 미니앱 배지 및 가이드

모든 디지털 및 인쇄 마케팅 자료에 아래 파일로 첨부 드린 ‘토스 미니앱 배지’를 활용하여 앱 이용을 유도해 보세요.

![](/assets/guideline_1.uZa1ZrEr.png)

토스 미니앱 배지 일러스트 템플릿

### **배지 활용 가이드**

* 블랙 배지를 기본형으로 하며, 화이트 배지의 경우 블랙 배지를 시각적으로 활용하기 힘들다고 판단되는 경우 활용이 가능해요.
* 레이아웃 또는 동영상 당 하나의 ‘토스 미니앱 배지’를 사용 가능해요. 배지가 중심 아트워크가 되지 않도록 앱 이미지 또는 주요 메시지의 하위에 배치하며, 배지를 수정하거나, 각도를 바꾸거나, 애니메이션 효과를 넣으면 안돼요.

## 4. 마케팅 디자인 템플릿

토스 미니앱 출시 소식을 아래 첨부드린 마케팅 디자인 템플릿을 활용해 손쉽게 알려보세요.
별도 디자인 작업 필요 없이 **\[서비스명]** 과 **\[서비스 로고]** 를 넣어서 여러 사이즈, 다양한 스타일의 이미지를 만들 수 있어요. 아래 첨부 파일을 확인해주세요.

![](/assets/guideline_2.s--pIt02.png)

![](/assets/guideline_3.DAGnZTNW.png)

![](/assets/guideline_4.BxTBNXSP.png)

마케팅 디자인 일러스트 템플릿

## 5. 앱인토스 로고 및 가이드

앱인토스 로고의 경우 주로 홍보나 보도자료에서 \[회사명(개발사명)]과 함께 활용할 수 있어요.
표기는 아래와 같이 ‘ **| ’(Bar) 표기**를 활용 해야 하며, 필요 시 [채널톡](https://apps-in-toss.channel.io/workflows/787658)으로 문의해 주세요.

![](/assets/guideline_5.BPE89L6U.png)

## 6. 권리 고지 및 법적 안내

* 토스의 상표 로고는, 본 마케팅 가이드에서 제공하는 토스 미니앱 배지와 마케팅 디자인 템플릿, 토스 미니앱 UI를 제외한 그 외의 로고를 사용하기 위해서는 토스의 확인이 필요해요. 아래에서 자세한 기준을 확인해 주세요.
  * 사용 가능: 토스 미니앱 배지, 마케팅 디자인 템플릿, 토스 미니앱 UI
  * **사전 확인: 앱인토스 로고**
  * **사용 불가: 토스 로고 단독 사용, 토스 UI/아이콘 등**
* 사전 확인이 필요한 로고 (앱인토스 로고) 를 사용하기 위해서는 [채널톡](https://apps-in-toss.channel.io/workflows/787658)으로 문의해 주세요.
* 앱인토스 서비스를 위해 파트너사에 제공된 프로그램을 통해 생성된 산출물의 소유권 및 지식재산권은 토스에 있으며, 해당 산출물은 서비스 목적 범위 내에서만 활용하실 수 있어요.

## 7. 문의 및 검수 요청 채널

마케팅과 관련하여 궁금하신 점이 있거나 검수 요청이 필요하다면 [채널톡](https://apps-in-toss.channel.io/workflows/787658)으로 문의해 주세요.

(참고) 검수를 해야 하는 기준은 아래와 같아요.

* **검수 필수**: 신규 마케팅 캠페인 런칭 전, 보도자료 배포 전, 토스 로고 및 배지를 편집한 경우
* **검수 권장**: 제공된 마케팅 디자인 템플릿의 광고 카피 변경, 배지 위치 조정 등
* **검수 제외**: 자체 SNS 포스팅 중 일반적인 서비스 소개

## 자주 묻는 질문

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/InView.md
---

# 요소 노출 감지하기

## `InView`

`InView` 컴포넌트는 화면에 요소가 보이기 시작하거나 화면에서 사라지는 것을 감지하는 컴포넌트예요.
요소가 화면에 조금이라도 보이기 시작하면 `onChanged` 핸들러가 호출되고 첫 번째 인자로 `true` 값이 전달돼요. 반대로 요소가 화면에서 사라지면 `false` 값이 전달돼요.
`onChanged` 핸들러의 두 번째 인자로 요소의 화면 노출 비율이 전달돼요. 노출 비율 값은 `0`에서 `1.0` 사이예요. 예를 들어 `0.2`가 전달되면 컴포넌트가 20%만큼 화면에 노출된 상태라는 의미예요.

::: tip 유의하세요

`InView`는 반드시 `IOContext`가 포함된 [IOScrollView](/bedrock/reference/framework/화면%20제어/IOScrollView) 또는 [IOFlatList](/bedrock/reference/framework/화면%20제어/IOFlatList) 내부에서 사용해야 해요.
만약 `IOContext` 외부에서 사용하면 `IOProviderMissingError`가 발생해요.

:::

## 시그니처

```typescript
class InView<T = ViewProps> extends PureComponent<InViewProps<T>> {
  static contextType: import("react").Context<IOContextValue>;
  static defaultProps: Partial<InViewProps>;
  context: undefined | IOContextValue;
  mounted: boolean;
  protected element: Element;
  protected instance: undefined | ObserverInstance;
  protected view: any;
  constructor(props: InViewProps<T>);
  componentDidMount(): void;
  componentWillUnmount(): void;
  protected handleChange: (inView: boolean, areaThreshold: number) => void;
  protected handleRef: (ref: any) => void;
  protected handleLayout: (event: LayoutChangeEvent) => void;
  measure: (...args: any) => void;
  measureInWindow: (...args: any) => void;
  measureLayout: (...args: any) => void;
  setNativeProps: (...args: any) => void;
  focus: (...args: any) => void;
  blur: (...args: any) => void;
  render(): import("react/jsx-runtime").JSX.Element | null;
}
```

### 파라미터

## 예제

### `InView`컴포넌트로 요소의 `10%` 지점을 감지하기

```tsx
import { LayoutChangeEvent, View, Text, Dimensions } from "react-native";
import { InView, IOScrollView } from '@granite-js/react-native';

function InViewExample() {
  const handleLayout = (event: LayoutChangeEvent) => {
    console.log("레이아웃 변경됨", event.nativeEvent.layout);
  };

  const handleChange = (inView: boolean, areaThreshold: number) => {
    if (inView) {
      console.log(`${areaThreshold * 100}% 비율만큼 화면에 보이는 상태`);
    } else {
      console.log("화면에 보이지 않는 상태");
    }
  };

  return (
    <IOScrollView>
      <View style={{ height: HEIGHT, width: "100%", backgroundColor: "blue" }}>
        <Text style={{ color: "white" }}>스크롤을 내려주세요</Text>
      </View>
      <InView onLayout={handleLayout} onChange={handleChange}>
        <View style={{ width: 100, height: 300, backgroundColor: "yellow" }}>
          <View
            style={{
              position: "absolute",
              top: 30,
              width: 100,
              height: 1,
              borderWidth: 1,
            }}
          >
            <Text style={{ position: "absolute", top: 0 }}>10% 지점</Text>
          </View>
        </View>
      </InView>
    </IOScrollView>
  );
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/위치
  정보/Location.md
---

# 위치 정보 객체

## `Location`

`Location` 는 위치 정보를 나타내는 객체예요.

## 시그니처

```typescript
interface Location {
    /**
     * Android에서만 지원하는 옵션이에요.
     *
     * - `FINE`: 정확한 위치
     * - `COARSE`: 대략적인 위치
     *
     * @see https://developer.android.com/codelabs/approximate-location
     */
    accessLocation?: 'FINE' | 'COARSE';
    /**
     * 위치가 업데이트된 시점의 유닉스 타임스탬프예요.
     */
    timestamp: number;
    /**
     * @description 위치 정보를 나타내는 객체예요. 자세한 내용은 [LocationCoords](/react-native/reference/framework/Types/LocationCoords.html)을 참고해주세요.
     */
    coords: LocationCoords;
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/porting-tutorials/unity-sdk.md'
---
# 유니티 SDK

SDK 포팅은 Unity 프로젝트를 앱인토스 환경에 **가장 빠르게 포팅하는 방법**입니다.\
Unity 전용으로 제공되는 **앱인토스 유니티 패키지**를 설치하면,\
Vite 프로젝트 구성이나 JS Bridge 구현 없이 바로 앱인토스 기능을 사용할 수 있어요.

![](/assets/unity_sdk_structure_1.BzmhD3ep.png)

***

## SDK 포팅이란?

SDK 포팅은 앱인토스 연동에 필요한 과정을 Unity 안에서 자동으로 처리하는 방식이에요.

* WebView SDK 연동을 위한 **JS Bridge**가 기본 포함되어 있어요.
* Unity에서 바로 **C# 코드로 앱인토스 API**를 호출할 수 있어요.
* WebGL 빌드부터 `.ait` 파일 생성까지 한 번에 자동화돼요.

따라서 기존처럼 Vite 프로젝트를 만들고 WebGL을 감싸거나 postMessage를 직접 구현할 필요가 없어요.

***

## 언제 사용하면 좋을까요?

* Unity 코드만으로 앱인토스 미니앱 포팅을 끝내고 싶을 때
* JS Bridge를 직접 작성하고 싶지 않을 때
* 앱인토스 기능을 C# 코드에서 바로 호출하고 싶을 때
* 자동화된 빌드로 빠르게 `.ait` 파일을 만들고 싶을 때

***

## 패키지 구성요소

앱인토스 유니티 패키지는 WebGL 환경에서 앱인토스 SDK를 사용할 수 있도록\
**C# API Layer**와 **JavaScript Bridge(.jslib)** 두 가지를 함께 제공합니다.

![](/assets/unity_sdk_structure_2.tndIcPpi.png)

#### 1. C# Header (C# API Wrapper)

Unity C# 코드에서 앱인토스 기능을 **직접 호출할 수 있도록** 제공되는 API입니다.

* 앱인토스 API를 C# 메서드로 감싸 편리하게 사용할 수 있어요.
* 내부적으로 `DllImport("__Internal")`를 사용해 WebGL 빌드 시 JS 함수와 연결돼요.
* 별도의 JavaScript 없이 C# 코드만으로 앱인토스를 연동할 수 있어요.

예시:

```csharp
public static async Task<string> GetClipboardText()
{
#if UNITY_WEBGL && !UNITY_EDITOR
    var tcs = new TaskCompletionSource<string>();
    string callbackId = AITCore.Instance.RegisterCallback<string>(
        result => tcs.TrySetResult(result),
        error => tcs.TrySetException(error)
    );
    __getClipboardText_Internal(callbackId, "string");
    return await tcs.Task;
#else
    // Unity Editor mock implementation
    UnityEngine.Debug.Log($"[AIT Mock] GetClipboardText called");
    await Task.CompletedTask;
    return "";
#endif
}
#if UNITY_WEBGL && !UNITY_EDITOR
        [System.Runtime.InteropServices.DllImport("__Internal")]
        private static extern void __getClipboardText_Internal(string callbackId, string typeName);
#endif
```

#### 2. JavaScript Bridge (.jslib)

`.jslib` 파일은 Unity WebGL 환경에서 **C#과 JavaScript를 연결하는 브릿지** 역할을 합니다.

* C#에서 호출하는 JS 함수들이 이 파일에 정의돼요.
* 실제로 앱인토스 WebView SDK와 통신하는 로직도 여기에서 처리돼요.
* JS → C# 호출 역시 지원해 양방향 메시징 구조를 만들 수 있어요.

예시:

```js
mergeInto(LibraryManager.library, {
    __getClipboardText_Internal: function(callbackId, typeName) {
        // 비동기 함수 (Promise 반환)
        var callback = UTF8ToString(callbackId);
        var typeNameStr = UTF8ToString(typeName);

        console.log('[AIT jslib] getClipboardText called, callbackId:', callback);

        try {
            var promiseResult = window.AppsInToss.getClipboardText();
            console.log('[AIT jslib] getClipboardText returned:', promiseResult, 'isPromise:', promiseResult && typeof promiseResult.then === 'function');

            if (!promiseResult || typeof promiseResult.then !== 'function') {
                // Promise가 아닌 경우 (undefined, null 등) - 즉시 응답
                console.log('[AIT jslib] getClipboardText did not return a Promise, sending immediate response');
                var payload = JSON.stringify({
                    CallbackId: callback,
                    TypeName: typeNameStr,
                    Result: JSON.stringify({ success: true, data: JSON.stringify(promiseResult), error: '' })
                });
                SendMessage('AITCore', 'OnAITCallback', payload);
                return;
            }

            promiseResult
                .then(function(result) {
                    console.log('[AIT jslib] getClipboardText resolved:', result);
                    var payload = JSON.stringify({
                        CallbackId: callback,
                        TypeName: typeNameStr,
                        Result: JSON.stringify({ success: true, data: JSON.stringify(result), error: '' })
                    });
                    SendMessage('AITCore', 'OnAITCallback', payload);
                })
                .catch(function(error) {
                    console.log('[AIT jslib] getClipboardText rejected:', error);
                    var payload = JSON.stringify({
                        CallbackId: callback,
                        TypeName: typeNameStr,
                        Result: JSON.stringify({ success: false, data: '', error: error.message || String(error) })
                    });
                    SendMessage('AITCore', 'OnAITCallback', payload);
                });
        } catch (error) {
            console.log('[AIT jslib] getClipboardText sync error:', error);
            var payload = JSON.stringify({
                CallbackId: callback,
                TypeName: typeNameStr,
                Result: JSON.stringify({ success: false, data: '', error: error.message || String(error) })
            });
            SendMessage('AITCore', 'OnAITCallback', payload);
        }
    },

});

```

***

## 설치 방법

앱인토스 유니티 패키지는 Unity Package Manager를 통해 Git URL로 설치할 수 있어요.\
이 방법이 가장 간단하고, 패키지 업데이트도 쉽게 관리할 수 있기 때문에 권장해요.

#### 1. Package Manager 열기

Unity 에디터에서   **`Window → Package Manager`** 를 선택합니다.

![](/assets/package_manager_1.DaoVV6i3.png)

#### 2. Git URL로 설치

1. 왼쪽 상단의 `+` 버튼을 클릭하고
2. `Add package from git URL...` 을 선택한 뒤
3. 제공된 Git URL을 입력하고 **Install**를 눌러 설치를 진행합니다.

```
https://github.com/toss/apps-in-toss-unity-sdk.git
```

![](/assets/package_manager_2.BoOv_0OJ.png)

#### 3. 설치 완료 확인

설치가 정상적으로 완료되면:

* Package Manager 목록에 **AppsInToss SDK**가 표시되고
* Unity 메뉴 상단에 **AIT** 항목이 새로 추가돼요.
* `Packages/Apps In Toss SDK/Runtime/SDK` 경로 아래에 `AIT.*.cs` 파일들이 생성돼요.
* `Packages/Apps In Toss SDK/Runtime/SDK/Plugins/*.jslib` 파일도 함께 제공돼요.

## AIT 메뉴 살펴보기

앱인토스 유니티 패키지가 설치되면 Unity 에디터 상단에 **AIT** 메뉴가 추가돼요.\
이 메뉴에서 WebGL 빌드, 패키징(.ait 생성), 테스트 서버 실행 등 SDK 포팅 과정에 필요한 대부분의 기능을 사용할 수 있습니다.

아래는 각 메뉴의 기능이에요.

![](/assets/package_manager_3.BROBxYtX.png)

#### Dev Server

개발용 테스트 서버를 실행하거나 종료해요.\
WebGL 빌드 결과물을 로컬 환경에서 빠르게 확인할 때 사용해요.

#### Production Server

서비스용(배포용) 환경에서 실행할 때 사용하는 서버 도구예요.\
Dev Server와 달리, 디버깅 기능이나 Mock 브릿지가 비활성화되어 있어\
최종 패키징 전에 실제 배포 환경과 유사한 테스트를 진행할 수 있어요.

#### Build

Unity 프로젝트를 WebGL로 빌드해요. SDK가 필요한 설정을 자동으로 적용해 WebGL 플레이어를 생성합니다.

#### Package

WebGL 빌드 결과물을 앱인토스 형식으로 패키징해요.\
`.ait` 파일이 생성되며, 미니앱 QR 테스트나 배포에 사용돼요.

#### Build & Package

WebGL 빌드 + `.ait` 패키징을 한 번에 실행해요.\
가장 자주 사용하는 옵션이에요.

#### Publish

생성된 `.ait` 파일을 앱인토스 콘솔로 업로드하는 기능이에요.\
`Configuration` 에 배포 키(API Key)가 등록되어야해요.\
테스트 또는 배포 단계에서 편리하게 사용할 수 있어요.

#### Clean

이전 빌드 결과물을 삭제해요.\
깨끗한 상태에서 다시 빌드하고 싶을 때 사용합니다.

#### Open Build Output

빌드 결과물이 저장된 폴더를 바로 열어요.\
WebGL 빌드 파일과 `.ait` 출력 파일을 빠르게 확인할 수 있어요.

#### Configuration

앱인토스 미니앱 포팅과 관련된 빌드 옵션을 설정하는 메뉴예요.\
`.ait` 패키징을 위해 빌드 전 꼭 설정해야해요.

![](/assets/package_manager_4.Cq0pn3pY.png)

:::tip 꼭 입력해야할 정보
아래 항목들은 `.ait` 패키지를 생성할 때 반드시 필요해요.

* **앱 ID**
  * 앱인토스 콘솔에 등록한 `appName`과 동일해야 해요.
* **표시 이름**
  * 앱에서 노출될 이름이에요.
* **아이콘**
  * 테스트 단계에서는 없어도 되지만, 실제 배포 시에는 반드시 등록해야 해요.

서버 설정의 Granite, Vite 관련 항목은 샌드박스앱 테스트시 이용돼요.
:::

#### Debug

디버그 도구를 모아둔 메뉴예요.\
로그를 확인하거나 내부 상태를 점검할 때 사용합니다.

***

## SDK 사용하기

앱인토스 유니티 SDK를 설치하면 C# 코드에서 바로 `AIT.*` API를 호출할 수 있어요.\
JS Bridge를 직접 작성할 필요 없이, 앱인토스 기능들을 Unity 코드만으로 사용할 수 있는 방식이에요.

아래는 가장 기본적인 API 호출 흐름과 예제입니다.

#### API 호출 기본 구조

앱인토스 API는 대부분 비동기(async) 방식으로 동작해요:

```csharp
var result = await AIT.SomeApi(options);
```

* 성공 시 API별 결과 모델이 반환돼요.
* 실패 시 AITException이 발생할 수 있어 예외 처리가 필요해요.
* WebView 환경에서 JS ↔ Unity 간 메시지 교환을 통해 실행돼요.

사용 가능한 전체 AIT API 목록은 [앱인토스 SDK 레퍼런스](/bedrock/reference/framework/시작하기/intro.html)에서 확인할 수 있어요.

Unity SDK에서는 모든 API를 `AIT.*` 형태로 동일하게 호출할 수 있어요.\
예를 들어, 웹뷰 SDK의 `getDeviceId` 는 아래처럼 `PascalCase`로 호출해요.

```csharp
var result = await AIT.GetDeviceId(options);
```

#### 예제

```csharp
using AppsInToss;
using UnityEngine;
using System.Threading.Tasks;

public class GameManager : MonoBehaviour
{
    async void Start()
    {
        try
        {
            // 기기 ID 조회
            string deviceId = await AIT.GetDeviceId();
            Debug.Log($"Device ID: {deviceId}");

            // 플랫폼 OS 조회
            PlatformOS os = await AIT.GetPlatformOS();
            Debug.Log($"Platform: {os}");

            // 네트워크 상태 확인
            NetworkStatus status = await AIT.GetNetworkStatus();
            Debug.Log($"Network: {status}");
        }
        catch (AITException ex)
        {
            Debug.LogError($"API 호출 실패: {ex.Message} (code: {ex.Code})");
        }
    }

    // 햅틱 피드백 예제
    public async void VibrateDevice()
    {
        try
        {
            var options = new GenerateHapticFeedbackOptions {
                style = "medium"
            };

            await AIT.GenerateHapticFeedback(options);
            Debug.Log("Haptic feedback generated");
        }
        catch (AITException ex)
        {
            Debug.LogError($"햅틱 피드백 실패: {ex.Message}");
        }
    }
}
```

***

## 사용 시 주의사항

앱인토스 AIT API는 **일반 브라우저 환경에서는 작동하지 않아요.**\
앱인토스 실행 환경에서만 기능을 사용할 수 있어요.

테스트 가능한 환경은 다음 두 가지예요:

1. 앱인토스 샌드박스 앱
   * 개발 중 기능 검증을 위해 제공되는 테스트 앱이에요.
   * Unity WebGL 빌드를 실행하고 AIT API가 정상적으로 연결되는지 확인할 수 있어요.
   * 샌드박스앱은 [여기](/development/test/sandbox.html)에서 다운로드 받을 수 있어요.

자세한 테스트 방법은 [여기](/tutorials/webview.html#미니앱-실행하기-시뮬레이터·실기기)를 참고해주세요.

2. `.ait` 파일 업로드 후 미니앱 테스트 실행
   * AIT 메뉴에서 Build & Package로 `.ait` 파일 생성
   * 앱인토스 콘솔에 업로드
   * QR 코드로 미니앱 실행

자세한 테스트 방법은 [여기](/development/test/toss.html)를 참고해주세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/porting-tutorials/unity.md'
description: Unity 게임을 앱인토스 미니앱으로 포팅하는 가이드입니다. Unity WebGL 빌드 및 앱인토스 연동 방법을 확인하세요.
---

# 유니티 SDK

앱인토스에 Unity 게임을 배포하려면, Unity 프로젝트를 **WebGL**로 빌드해야해요.\
이 가이드는 Unity에서 WebGL 빌드를 만드는 기본적인 방법을 안내해요.

## 1. WebGL 모듈 설치

Unity Hub에서 WebGL 플랫폼이 설치되어 있어야 해요.

1. Unity Hub 실행
2. Installs 탭 선택
3. 사용 중인 Unity 버전 옆의 점 세 개(···) 클릭 → Add Modules
4. WebGL Build Support 체크 → 설치
5. 설치가 완료되면 Unity에서 File > Build Settings로 진입했을 때 플랫폼 목록에 **WebGL**이 나타나요.

![](/assets/build_webgl.BaliDsvc.png)

## 2. 플랫폼 전환

1. Unity 프로젝트 열기
2. File > Build Settings 이동
3. WebGL 선택 → Switch Platform 클릭

## 3. Player 설정 조정

Edit > Project Settings > Player 메뉴에서 다음 항목을 설정해 주세요.

* Publishing Settings
  * Compression Format: `Brotli` 로 설정

## 4. 빌드하기

1. File > Build Settings로 이동
2. WebGL 선택된 상태에서 → Build 클릭
3. 출력 폴더 지정 (예: Build/)

## 5. 결과물 확인

빌드가 완료되면 보통 `index.html`, `Build`, `TemplateData` 폴더가 생성돼요.\
Unity 프로젝트 설정이나 버전에 따라 생성되는 폴더는 조금 다를 수 있어요.\
이 폴더들을 Vite 프로젝트에 포함해 웹페이지 형태로 띄울 수 있어요.

Vite로 Unity WebGL을 감싸는 방법은 [Vite로 Unity WebGL 감싸기](./vite-unity.md)를 참고해 주세요.

::: tip 참고하세요
Unity 6000.1.8 미만 버전에서는 2D 물리 엔진(Rigidbody2D) 사용 시 WebGL 빌드에서 **GC 메모리 누수 이슈**가 있었어요.\
자세한 내용은 [Unity Discussions 포럼](https://discussions.unity.com/t/memory-leak-when-using-rigidbody2d-physics-in-webgl/1649803)에서 확인할 수 있어요.

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/이벤트
  제어/back-event.md
---

# 이벤트 제어하기

이 문서에서는 앱 동작 중 발생하는 주요 이벤트를 감지하고 제어하는 방법을 안내해요.\
대표적으로 **뒤로가기 버튼 이벤트**와 **앱 진입 완료 이벤트**를 다룰 수 있어요.

## 1. 뒤로가기 버튼 이벤트 감지하기

뒤로가기 버튼 이벤트를 제어하면 사용자가 실수로 페이지를 닫는 상황을 방지할 수 있어요.\
예를 들어 결제 중이거나 폼 작성 중일 때, 뒤로가기를 눌러 화면이 닫히지 않게 막을 수 있어요.

### 주요 기능

| 기능 | 설명 |
|------|------|
| `backEvent` | 뒤로가기 버튼을 누르면 발생하는 이벤트예요. |
| `graniteEvent.addEventListener('backEvent', { ... })` | 이벤트를 구독해요. |
| `onEvent` | 뒤로가기 버튼이 눌리면 호출돼요. 기본 뒤로가기는 차단돼요. |
| `onError` | 이벤트 처리 중 오류가 발생했을 때 호출돼요. |
| `unsubscription()` | 등록된 이벤트 리스너를 해제할 수 있어요. |

React Native에서는 `useBackEvent()` 훅으로 동일한 로직을 구현할 수 있어요.

### 예제

아래 예시는 사용자가 뒤로가기를 눌렀을 때 확인창을 띄우고, “확인”을 누르면 이동을 허용하는 예시예요.

::: code-group

```js [js]
import { graniteEvent } from '@apps-in-toss/web-framework';

const unsubscription = graniteEvent.addEventListener('backEvent', {
  onEvent: () => {
    const shouldLeave = window.confirm('작성 중인 내용이 저장되지 않아요. 나가시겠어요?');
    if (shouldLeave) {
      // 나가는 코드를 작성해요.
    }
  },
  onError: (error) => {
    console.error(`에러가 발생했어요: ${error}`);
  },
});

window.addEventListener('pagehide', () => {
  unsubscription();
});
```

```tsx [React]
import { graniteEvent } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';

function ConfirmBackNavigation() {
  const [formValue, setFormValue] = useState('');

  useEffect(() => {
    const unsubscription = graniteEvent.addEventListener('backEvent', {
      onEvent: () => {
        const shouldLeave = window.confirm('작성 중인 내용이 저장되지 않아요. 나가시겠어요?');
        if (shouldLeave) {
          // 나가는 코드를 작성해요.
        }
      },
      onError: (error) => {
        alert(`에러가 발생했어요: ${error}`);
      },
    });

    return unsubscription;
  }, []);

  return (
    <div>
      <h2>입력 폼</h2>
      <textarea
        value={formValue}
        onChange={(e) => setFormValue(e.target.value)}
        placeholder="여기에 내용을 입력해 주세요"
        rows={5}
        style={{ width: '100%' }}
      />
    </div>
  );
}
```

```tsx [React Native]
import { useEffect, useState } from "react";
import { Alert, Button, View } from "react-native";
import { useBackEvent } from '@granite-js/react-native';

function UseBackEventExample() {
  const backEvent = useBackEvent();

  const [handler, setHandler] = useState<{ callback: () => void } | undefined>(
    undefined
  );

  useEffect(() => {
    const callback = handler?.callback;

    if (callback != null) {
      backEvent.addEventListener(callback);

      return () => {
        backEvent.removeEventListener(callback);
      };
    }

    return;
  }, [backEvent, handler]);

  return (
    <View>
      <Button
        title="Add BackEvent"
        onPress={() => {
          setHandler({ callback: () => Alert.alert("back") });
        }}
      />
      <Button
        title="Remove BackEvent"
        onPress={() => {
          setHandler(undefined);
        }}
      />
    </View>
  );
}
```

:::

## 2. 앱 진입 완료 이벤트 감지하기

앱 진입 후 표시되는 “○○으로 이동했어요” 안내 문구가 사라지는 시점을 감지할 수 있어요.
이 시점을 기준으로 초기화, 데이터 로딩, 애니메이션 시작 등 작업을 수행할 수 있어요.

### 개요

`appsInTossEvent`를 사용하면 토스 앱에서 전달되는 다양한 상태 이벤트를 감지할 수 있어요.
그중 `entryMessageExited` 이벤트는 앱 진입 직후 안내 메시지가 **화면에서 사라지는 시점**을 알려줘요.

이 이벤트를 활용하면 앱이 사용자 입력을 받을 준비가 된 **ready 상태**를 정확히 감지할 수 있어요.

### 주요 기능

| 이벤트 | 설명 |
|--------|------|
| `appsInTossEvent.addEventListener('entryMessageExited', { onEvent })` | 안내 메시지가 화면에서 사라지는 즉시 호출돼요. |
| `onEvent` | 이벤트 발생 시 실행할 콜백 함수를 정의해요. |
| `onError` | 이벤트 처리 중 오류가 발생하면 호출돼요. |
| `unsubscription()` | 등록된 이벤트 리스너를 해제할 수 있어요. |

### 예제

아래 예시는 안내 메시지가 사라진 직후 게임을 시작하는 예시예요.

::: code-group

```js [js]
import { appsInTossEvent } from '@apps-in-toss/web-framework';

function startGame() {
  console.log('게임을 시작합니다!');
}

const unsubscription = appsInTossEvent.addEventListener('entryMessageExited', {
  onEvent: () => {
    startGame();
  },
  onError: (error) => {
    console.error('게임 시작 이벤트 처리 중 오류:', error);
  },
});

window.addEventListener('pagehide', () => {
  unsubscription();
});
```

```tsx [React]
import { appsInTossEvent } from '@apps-in-toss/web-framework';
import { useEffect } from 'react';

/**
 * 안내 메시지가 사라진 시점에 게임을 시작하는 컴포넌트예요.
 *
 * @example
 * import { GameStarter } from './GameStarter';
 *
 * const App = () => <GameStarter />;
 */
function GameStarter() {
  useEffect(() => {
    const unsubscription = appsInTossEvent.addEventListener('entryMessageExited', {
      onEvent: () => {
        // 진입 메시지가 사라진 직후 게임 시작
        startGame();
      },
      onError: (error) => {
        console.error('게임 시작 이벤트 처리 중 오류:', error);
      },
    });

    return () => {
      unsubscription();
    };
  }, []);

  /**
   * 게임을 시작하는 함수예요.
   * 타이머 시작, 캐릭터 등장 등 초기 게임 로직을 이곳에 작성해요.
   */
  const startGame = () => {
    console.log('게임을 시작합니다!');
    // 게임 시작 로직 추가
  };

  return (
    <div>
      <h2>게임을 준비 중...</h2>
    </div>
  );
}
```

```tsx [React Native]
import { appsInTossEvent } from '@apps-in-toss/framework';
import { useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';

/**
 * 안내 메시지가 사라진 시점에 게임을 시작하는 컴포넌트예요.
 *
 * @example
 * import { GameStarter } from './GameStarter';
 *
 * const App = () => <GameStarter />;
 */
function GameStarter() {
  useEffect(() => {
    const unsubscription = appsInTossEvent.addEventListener('entryMessageExited', {
      onEvent: () => {
        // 진입 메시지가 사라진 직후 게임 시작
        startGame();
      },
      onError: (error) => {
        console.error('게임 시작 이벤트 처리 중 오류:', error);
      },
    });

    return () => {
      unsubscription();
    };
  }, []);

  /**
   * 게임을 시작하는 함수예요.
   * 타이머 시작, 캐릭터 등장 등 초기 게임 로직을 이곳에 작성해요.
   */
  const startGame = () => {
    console.log('게임을 시작합니다!');
    // 게임 시작 로직 추가
  };

  return (
    <View>
      <Text>게임을 준비 중...</Text>
    </View>
  );
}
```

## 참고사항

* `graniteEvent`는 네이티브 이벤트(뒤로가기 등)를, `appsInTossEvent`는 토스 앱 내부 상태 변화를 감지해요.
* 등록된 이벤트 리스너는 반드시 **컴포넌트 언마운트 시 해제**해야 해요.
* 이벤트 기반으로 실행되는 작업에는 반드시 **에러 핸들러(onError)** 를 추가해 예외 상황을 대비하세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/ads/intro.md'
description: 인앱 광고 인앱 광고 개괄적인 소개입니다. 인앱 광고에 대해 이해할 수 있습니다.
---

# 이해하기

앱인토스에서 제공하는 **전면형·보상형 광고로 바로 수익화** 해보세요.\
서비스에 수익화를 위한 광고를 자연스럽게 녹이면서 **이탈은 줄이고, ARPDAU·LTV는 높일 수 있어요.**

***

## 인앱 광고가 무엇인가요?

인앱 광고는 **앱 내부에 노출되는 광고**로, **서비스 이용 중 자연스럽게 사용자에게 도달하는 광고 방식**이에요.\
인앱 광고는 **전면형 광고**와 **보상형 광고**로 나뉘어요.

* 전면형 광고: 광고가 전체화면으로 표시되며, 화면 전환 지점에서 보여줘요.
* 보상형 광고: ‘광고를 시청하면 보상 지급’의 구조로, 사용자가 원할 때 광고를 볼 수 있어요.

![](/assets/ads-intro-1.DoTDXkAO.png)

## 인앱 광고를 사용하면 무엇이 좋나요?

* 전면 광고와 리워드 광고를 선택하여 원하는 플로우에 노출해요.
* 출시 첫날부터 바로 광고 수익이 발생해, 즉시 수익화가 가능해요.
* 인앱 광고를 통해 사용자가 계속 서비스를 이용하도록 유도하여 리텐션을 높일 수 있어요.
  * 게임에서는 ‘광고 보고 이어하기’를 통해 사용자가 도전 중이던 스테이지를 이어서 플레이할 수 있게 해, 자연스럽게 다시 이용하도록 유도할 수 있어요.

## 참고해 주세요

* **인앱 광고 테스트는 반드시 [테스트용 ID](https://developers-apps-in-toss.toss.im/ads/develop.html#%E1%84%90%E1%85%A6%E1%84%89%E1%85%B3%E1%84%90%E1%85%B3%E1%84%92%E1%85%A1%E1%84%80%E1%85%B5)를 사용**해야 해요. (운영 ID 사용 시 제재될 수 있어요.)
  * 전면형 광고: `ait-ad-test-interstitial-id`
  * 리워드 광고: `ait-ad-test-rewarded-id`
* 사용자에게 광고가 과도하게 노출되지 않도록 주의해 주세요.
* 광고 재생 시 앱 사운드는 잠시 멈추고, 끝나면 자동으로 다시 이어지도록 해주세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/game-center/intro.md'
description: '게임 센터 서비스 소개입니다. 주요 기능, 혜택, 적용 방법을 확인하세요.'
---

# 이해하기

**게임 프로필 & 리더보드**로 플레이에 소셜을 더해요.\
소셜 효과를 통해 게임 체류시간과 리텐션을 강화하고, 게임 공유를 통해 신규 유입 확대를 기대할 수 있어요.

## 게임 프로필 & 리더보드는 무엇인가요?

게임 리더보드/프로필 기능 은 게임 서비스에만 제공되는 서비스에요.

`게임 프로필` 은 게임 전에 사용자가 프로필을 등록하도록 하는 기능이에요.\
프로필 생성은 딱 한 번만 설정하면 되며, 이후에는 **김토스님 반가워요!** 형태의 환영 메시지가 노출돼요.

![](/assets/game-intro-1.BHEnAzBV.png)

`리더보드`는 게임 안에서 유저들의 점수를 볼 수 있는 랭킹 기능을 제공해요.\
사용자는 리더보드를 통해 서로 친구를 맺을 수 있고, 친구에게 내 점수를 자랑할 수 있어요.

![](/assets/game-intro-2.DK4iRlNU.png)

## 리더보드를 사용하면 무엇이 좋은가요?

* 프로필 생성 이후엔 게임 진입 시 자동 환영이 되며 매끄러운 온보딩을 설계할 수 있어요.
* 리더보드를 통한 랭킹 시스템, 친구와의 경쟁과 같은 소셜 기능은 리텐션을 강화할 수 있어요.
* 내 점수 자랑하기라는 공유 기능을 통해 자연스러운 바이럴 루프를 만들 수 있어요

## 참고해 주세요

1. **게임 전 프로필 등록은 필수**이며, 프로필을 생성하지 않은 사용자는 게임을 진행할 수 없어요.
2. 게임 프로필에 사용자 **식별자 값은 포함되지 않아요.** (사용자 식별자 값이 필요한 경우에는 토스 로그인을 연동해 주세요.)
3. 점수 제출 타이밍의 경우, 게임 시작이 아닌 게임 종료 후에 호출해 주세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/game-login/intro.md'
description: '게임 로그인 서비스 소개입니다. 주요 기능, 혜택, 적용 방법을 확인하세요.'
---

# 이해하기

게임 로그인은 유저의 동의를 받지 않아도 바로 서비스를 사용할 수 있도록 할 수 있어,\
**약 80%의 유저의 초기 이탈을 막을 수 있어요.**

## 게임 로그인이 무엇인가요?

게임 로그인이란 **별도의 서버 구축과 유저 동의 없이 유저를 식별**할 수 있도록 하는 기능이에요.

토스 내부 게임 데이터 분석 결과 **약 80%의 유저가 로그인 약관 동의 단계에서 이탈**하는 것을 확인했고,\
**\[토스 로그인 기능]이 게임 플레이 시 진입장벽**이 된 다는 것을 확인했어요.

그에 따라 앱인토스는 게임 내 유저 동의라는 이탈 포인트를 삭제하고 바로 게임 서비스를 이용하도록 하는 게임 로그인 기능을 제공하고 있어요.

| 구분 | 토스 로그인 | 게임 로그인 |
|------|--------------|--------------|
| 사용 가능 대상 | 모든 제휴사 | 게임 미니앱 전용 |
| 서버 구축 필요 | ✅ 필요 | ❌ 불필요 |
| 콘솔 설정 | ✅ 필요 | ❌ 불필요 |
| 유저 동의 | ✅ 필요 | ❌ 불필요 |
| 프로모션 연동 | ✅ 가능 | ✅ 가능 |

## 게임 로그인을 사용하면 무엇이 좋은가요?

게임 로그인을 사용하면 다음과 같은 장점이 있어요.

* 서버간 연동이 필요 없어요.
* 서버가 없어도 [토스 프로모션 기능](/promotion/intro.md)을 사용할 수 있어요.
* 유저의 로그인 동의과정이 필요 없어요. ( 유저가 이탈하는 포인트 삭제 가능)
* 미니앱 내에서 바로 유저를 안정적으로 식별할 수 있도록 도와줘요.

## 참고해주세요

* **게임 로그인 기능은 게임 카테고리 미니앱에서만 제공됨**에 따라 **비게임 미니앱은 [토스 로그인](/login/intro.md)을 사용**해야 해요.

---

---
url: 'https://developers-apps-in-toss.toss.im/iap/intro.md'
---
# 이해하기

앱인토스의 인앱 결제를 연동해 **디지털 상품·권한·콘텐츠를 손쉽게 판매**해 보세요.\
**구매 흐름을 짧게 하고 매출을 빠르게 늘릴 수 있어요.**

***

## 인앱 결제가 무엇인가요?

인앱 결제는 앱 내부에서 유료 상품을 직접 구매할 수 있는 결제 방식이에요.\
사용자가 앱을 떠나지 않고도 필요한 기능, 아이템, 콘텐츠 등을 바로 결제할 수 있어요.\
인앱 결제의 상품은 소모성과 비소모성으로 나뉘어요.

* 소모성 아이템: 사용하면 사라지며, 계속 사용하려면 다시 구매해야 해요.
* 비소모성 아이템: 한 번 구입하면 계속 사용할 수 있어요.

![](/assets/iap-intro-1.DbZeue-K.png)

## 인앱 결제를 사용하면 무엇이 좋나요?

* 사용자가 앱을 벗어나지 않고 필요한 상품을 바로 구매할 수 있기 때문에 이탈을 방지할 수 있어요.
* 출시 초기부터 바로 유료 아이템, 구독 상품을 판매해 수익을 만들 수 있어요.
* 소모성 아이템, 비소모성 아이템으로 다양한 상품을 활용하여 매출을 극대화할 수 있어요.

## 참고해 주세요

* **인앱 결제의 환불**은 **Apple과 Google 정책**에 따르고 있어요.
* **판매가**는 **공급가에 VAT가 더해진 금액**이에요.
* 결제 진행 시 앱 내 기능(음악, 영상 등)은 **잠시 멈추고 완료 후 자동 복귀**하도록 해주세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/intelli/intro.md'
description: '토스 홈 광고 서비스 소개입니다. 주요 기능, 혜택, 적용 방법을 확인하세요.'
---

# 이해하기

**토스 앱의 홈 상단 배너에 광고**를 함으로써 푸시, 알림과 또 다른 **트래픽**을 만들 수 있어요.\
토스 홈 광고를 통해서 **토스 사용자에게 임팩트 있는 메시지**를 보내보세요.

## 토스 홈 광고가 무엇인가요?

**토스 홈 화면 최상단에 노출**되는 **내부 서비스 추천 배너**예요.\
주목도가 굉장히 높아, 토스팀의 강력한 정보 전달 수단으로 활용되고 있어요.

![](/assets/intro_intelli_1.CGteOZw9.png)

토스 홈 광고의 소재는 **액션 문구, 서브 문구, 아이콘**으로 구성되어 있어요.

* 액션 문구: "~하기"와 같이, 액션을 유도하고자 하는 문구를 작성해요.
* 서브 문구: 광고의 핵심 내용을 뒷받침하는 문구를 작성해요.
* 아이콘: 서브 문구와 액션 문구에서 작성한 주제를 중심으로 아이콘을 설정해요.

## 토스 홈 광고를 사용하면 무엇이 좋은가요?

* 토스 앱 첫 화면인 홈의 상단에 노출되기 때문에 가장 많은 사용자에게 도달해요.
* 토스라는 브랜드 맥락 안에서 제공되기 때문에 자연스럽고 신뢰감 있는 메시지를 전달해요.
* 캠페인을 손쉽게 진행하고, 성과 데이터를 바로 확인하며 개선할 수 있어요.
* 사용자 특성에 맞춘 노출로 효율적인 전환을 기대할 수 있어요.

## 참고해 주세요

* **소재의 CTR이 4% 미만이면 광고 채널의 평균 효율 대비 낮다고 판단하여 자동으로 노출 종료돼요.**
  * 소재별로 1,000회 이상 노출된 후 CTR이 4% 미만일 경우, 해당 소재는 일시적으로 노출이 중단되며 CTR 예측 모델이 약 2~4시간 동안 학습을 진행해요.
  * 학습이 완료된 뒤 재노출을 시도하고, 그럼에도 CTR이 4% 미만으로 유지되면 해당 소재의 노출은 최종 종료돼요.
* 토스 홈 광고는 내부 배너를 활용한 광고이기 때문에 아래의 규칙을 지켜야 해요.
  1. 자극적인 광고적 표현을 사용하지 않았나요?
  2. 클릭 후 화면을 예측할 수 있나요?
  3. 가치가 명확한 메시지를 담았나요?
  4. 혜택을 받기 위한 조건을 숨기지 않았나요?
  5. 꼭 봐야 할, 전환율이 높은 세그먼트에게만 노출하나요?

---

---
url: 'https://developers-apps-in-toss.toss.im/login/intro.md'
description: 토스로그인 기능에 대한 개괄적인 소개입니다. 토스로그인에 대해 파악하기 위해 참고해주세요.
---

# 이해하기

앱인토스에서 **토스 회원을 한 번에 연동**해 보세요.\
동의 한 번으로 **가입부터 로그인·정보 제공**까지 이어져, 토스 회원 연동을 쉽게 할 수 있어요.

***

## 토스 로그인이 무엇인가요?

**토스 계정**으로 빠르고 안전하게 로그인할 수 있는 기능이에요.\
로그인 시 사용자에게 표시될 **동의 항목을 설정**할 수 있어요.\
그리고 앱인토스 서비스를 운영하기 위한 **약관/동의문**과 **연결 끊기 콜백 정보를 등록**할 수 있어요.

![](/assets/login-intro-1.DDSZ-qGN.png)

## 토스 로그인을 사용하면 무엇이 좋은가요?

* 별도 폼 작성 없이 바로 가입·로그인되어 매끄러운 회원가입 경험을 만들 수 있어요.
* 토스에서 직접 제공하는 신뢰도 높은 사용자 정보를 제공해요.
* 재방문 시 자동/원클릭 로그인을 할 수 있어요.
* 앱 재설치나 기기 변경에도 같은 사용자로 매칭되어 CS 부담이 줄어들어요.

## 참고해 주세요

* **아래 기능**을 사용하기 위해서 **토스 로그인을 필수로 연동**해야 해요.
  * 기능성 푸시, 알림
  * 프로모션 (토스 로그인)
  * 토스페이

---

---
url: 'https://developers-apps-in-toss.toss.im/promotion/intro.md'
description: '프로모션(토스 포인트) 서비스 소개입니다. 주요 기능, 혜택, 적용 방법을 확인하세요.'
---

# 이해하기

프로모션으로, **가벼운 클릭이 자연스럽게 전환**까지 이어지도록 기획해 보세요.\
**재방문 유도, 자연스러운 바이럴**까지 퍼널 곳곳에서 성과를 낼 수 있어요.

## 프로모션이 무엇인가요?

앱인토스의 프로모션은 **사용자의 특정 행동을 기준으로 토스 포인트를 지급하는 이벤트**예요.\
프로모션은 **비즈 월렛에 충전한 예산**으로 진행할 수 있고, **혜택 탭 노출 여부를 콘솔에서 설정**할 수 있어요.

![](/assets/promotion-intro-1.DkW-fX-I.png)

::: tip 게임 미니앱이라면 꼭 확인하세요
프로모션은 유저 식별값이 필요하기 때문에 **\[토스 로그인] 구현 시에만 사용이 가능**해요.\
[토스 로그인 가이드 바로가기](/login/intro.md)

단, **미니앱 카테고리가 게임**이라면 **[게임 로그인](/game-login/develop.md) 구현을 통해 얻은 Hash 값으로 유저 식별**이 가능하여,\
**별도 서버 구축 없이도** 프로모션 사용이 가능해요.\
[게임 로그인 가이드 바로가기](/game-login/intro.md)
:::

## 프로모션을 사용하면 무엇이 좋은가요?

* 비즈 월렛 선충전과 예산 및 종료일 설정으로 초과 집행 걱정 없이 운영할 수 있어요.
* 토스 혜택 탭에 프로모션이 노출되면 많은 트래픽과 함께 더 많은 사용자가 서비스에 유입될 수 있어요.
* “가입하기”, “첫 플레이 진행하기”처럼 사용자의 행동을 간단하게 유도할 수 있어요.
* 일/주간 미션으로 서비스에 사용자가 돌아올 이유를 만들어 리텐션을 강화할 수 있어요.
* 지급과 결과 조회는 API로 할 수 있고, 테스트용 코드 `(TEST_{promotionCode})`로 실제 차감 없이 검증할 수 있어요.

## 참고해 주세요

* 앱인토스의 다양한 프로모션을 한눈에 볼 수 있는 **"새로운 서비스 써보고"** 탭은 **내부 노출 로직에 따라 일부 사용자에게만 노출**될 수 있어요.
* 조건을 한눈에 알아볼 수 있도록 표기하여 과장/오해 소지를 만들지 않아요.
* **사행성, 자사 앱 설치 유도, 법령 위반 소지의 콘텐츠로 프로모션을 진행할 수 없어요.**
* 1인 1회/일일 제한, 쿨다운, 중복 지급 차단 로직은 필수예요.
* 지급이 지연되면 PENDING 안내와 결과 확인 경로를 보여주세요.
* 프로모션을 진행하기 위해서는 검수가 필요하며, **영업일 기준으로 약 2~3일 소요**돼요.

---

---
url: 'https://developers-apps-in-toss.toss.im/push/intro.md'
description: '푸시 알림 서비스 소개입니다. 주요 기능, 혜택, 적용 방법을 확인하세요.'
---

# 이해하기

앱인토스의 푸시, 알림으로 **핵심 순간에 사용자를 불러오세요.**\
푸시, 알림을 **신규 사용자 유입,** **리텐션 향상** 등의 목적으로 활용할 수 있어요.\
마케팅 수신 동의 사용자에게 **광고성 메시지**는 물론, 주문/결제/배송과 같은 **기능성 메시지**도 보낼 수 있어요.

## 푸시, 알림이 무엇인가요?

“푸시, 알림”은 앱인토스 콘솔에서 사용자에게 메시지를 보낼 수 있는 기능이에요.\
메시지를 보내면 **푸시와 알림, 두 가지 채널**에 발송하게 돼요.

* 푸시: 푸시는 앱을 열지 않은 상태에서 받는 OS 메시지예요. 앱의 이름과 로고가 함께 노출돼요.
* 알림: 알림은 토스 앱 오른쪽 상단 > 종 아이콘을 누르면 보이는 앱 내 메시지예요.

![](/assets/push-intro-1.BBR08txD.png)

**메시지의 내용**에 따라서 **광고성,** **기능성** 메시지를 선택하여 보낼 수 있어요.

* 광고성 메시지: 할인, 이벤트, 신규 상품 안내처럼 마케팅 목적의 프로모션 메시지를 의미해요.
* 기능성 메시지: 서비스 이용 과정에서 발생하는 주문, 결제, 배송 등 필수 정보를 전달하는 메시지를 의미해요.

메시지 내용에 대한 고민이 있다면, [디자인 > UX 라이팅](/design/ux-writing.md)을 참고해 주세요.

## 푸시, 알림을 사용하면 무엇이 좋은가요?

* 기능성 메시지로 끊긴 흐름을 부드럽게 이어줄 수 있어요.
* 장바구니 방치, 미완료 가입 등을 다시 유도할 수 있어요.
* 결제 승인, 환불, 배송 변경 등 상황 알림을 자동 발송할 수 있어요.
* 템플릿·세그먼트별 열람·클릭·복귀를 추적해 개선할 수 있어요.

## 참고해 주세요

* 기능성 메시지 내에 구매 유도, 혜택 안내 등 광고 목적의 내용이 포함되는 경우, 광고성 메시지로 발송이 필요해요.
* 기능성 푸시·알림은 「정보통신망법」에 따라 **별도의 마케팅 수신 동의 없이도 발송**할 수 있어요.\
  다만, 사용자가 **알림 수신을 해제할 수 있는 기능**을 제공하고, **해제 경로를 명확히 안내**하는 것을 권장해요.\
  토스는 기능성 알림에 대해 **별도의 동의 절차**를 마련하고 있으며, 사용자가 **언제든 동의를 철회**할 수 있도록 구성되어 있어요.

![](/assets/push-intro-2.njasv2ug.png)

* 푸시, 알림을 보내기 위해서는 메시지 템플릿(문구) 검수가 필요하며, **영업일 기준으로 약 2~3일 소요**돼요.

---

---
url: 'https://developers-apps-in-toss.toss.im/reward/intro.md'
description: '공유 리워드 서비스 소개입니다. 주요 기능, 혜택, 적용 방법을 확인하세요.'
---

# 이해하기

앱인토스의 공유 리워드 기능을 도입하고,\
기존 유저의 초대 → 신규 유입 → 재방문·재공유로 이어지는 자연스러운 **바이럴 선순환 구조**를 만들어보세요.

## 공유 리워드가 무엇인가요?

**연락처 모듈**을 통해 토스를 사용하는 **유저의 연락처를 불러오고 \[기회 받기]를 통해 공유한 유저에게 리워드를 제공**하는 기능이에요.\
푸시를 통한 토스 알림으로 공유가 되며 [리워드는 콘솔에서 설정](console.md)할 수 있어요.

![](/assets/reward-intro-1.DvWjDAem.png)

공유 리워드 기능은 게임, 비게임 서비스 모두 사용이 가능하며 푸시 문구는 각각 다음과 같아요.

![](/assets/reward-intro-2.8RSNbK3v.png)

## 공유 리워드를 사용하면 무엇이 좋은가요?

* 친구 초대 시 보상을 지급함으로써 트래픽을 만들 수 있어요.
* 보상을 전제로 친구 초대를 유도해 무료 마케팅을 진행할 수 있어요.
* 서비스 내에서만 사용할 수 있는 재화를 지급하여 사용자의 재방문을 유도할 수 있어요.

## 참고해 주세요

* 과도한 팝업·강제 공유 유도는 하지말아주세요.
* 보상 지급에 대한 조건의 경우, 정확하게 유저에게 안내해 주세요.
* **현금성 또는 사행성 보상의 경우, 등록할 수 없어요.**

---

---
url: 'https://developers-apps-in-toss.toss.im/settlement/intro.md'
description: 앱인토스 정산 방법에 대한 프로세스를 소개합니다.
---

# 이해하기

앱인토스에서의 정산은 서비스 운영과 수익 관리를 위한 핵심적인 프로세스예요.

본 가이드는 정산 과정을 정확히 이해하고, 정산 정보 등록부터 수익금 수령까지의 절차를 명확히 파악할 수 있도록 돕기 위해 작성되었어요.

***

## 1. 정산을 받기 위해서는 어떤 정보를 등록해야 하나요?

정산을 위해 콘솔 > 나의 워크스페이스 > 정보 > 정산 정보를 입력해야 해요.

입력된 정산 정보로 세금계산서 발송 및 정산 대금이 지급되며, 정보 등록 시 거래 계좌 사본이 필요하니 미리 준비해 주세요.

모든 정산은 앱 단위가 아닌, **사업자 단위** 총 수익/비용을 기준으로 진행해요.

![](/assets/console_settlement.BRNA63wH.png)

## 2. 인앱 광고 수수료

### 광고송출비용 등 운영 수수료

앱인토스는 파트너사의 광고 매체에 광고를 송출하기 위해 미디에이션 플랫폼 / 토스 자체 광고 플랫폼(Toss Ads)을 활용하고 있으며, 광고송출비용 등 운영비로 시장요율에 준하는 30% 수준을 받고 있어요.

* **미디에이션 플랫폼**

외부 미디에이션 플랫폼을 통해 광고가 송출된 경우, 광고 매출에서 해당 플랫폼이 수수료를 수취한 후 광고 대금을 토스에게 지급하게 되며, 이 금액이 파트너사의 광고 수익이 돼요.

| **광고 매출** | **광고 수익** | **부가세** |
| --- | --- | --- |
| ₩10,000 | ₩7,000 | ₩700 |

\*외부 미디에이션 플랫폼의 귀책으로 인하여, 발생하는 광고 수익 일부가 각각의 광고 매체로 트랙킹되지 않을때, 해당 수익분에 대해서는 daily 수익 비중에 따라, 각 파트너사에 안분해 드리고 있어요.\
(일 별 파트너사 당 광고 매체 수익 합계 / 일 별 유실 수익 총합) \* 일별 유실 수익 총합 = 일 별 파트너사 당 유실된 광고 매체 수익

* **토스 자체 광고 플랫폼 (Toss Ads)**

Toss 광고 서비스인 Toss Ads를 통해 광고가 송출된 경우, 토스는 광고매출(부가세 포함)에서 광고송출비용 등 운영비 30%를 공제하며, 공제 후 귀속되는 광고 수익이 파트너사의 광고 수익이 돼요.

| **광고 매출** | **광고 수익** | **부가세** |
| --- | --- | --- |
| ₩11,000 | ₩7,700 | ₩770 |

### 앱인토스 수수료 (15%)

광고 대행에 대한 수수료이며, 광고송출비용 등 운영비가 선 공제된 금액(광고 수익) 에서 앱인토스 수수료를 공제해요.\
\*CBT 기간 동안 한시적으로 토스 수수료 0% 프로모션이 적용되고 있어요.

### 정산금

광고 수익에서 앱인토스 수수료(부가세 포함) 가 제외된 금액이 파트너사의 최종 정산금이에요.\
광고 수익은 파트너사의 매출로 신고 필요하며, 광고 수익에 대한 부가세는 정산금과 함께 선지급해드려요.\
{광고수익(a) + 광고 수익 부가세(b)} - {앱인토스 수수료+부가세(c+d)} = (e)

| **a. 광고 수익 (Google Admob+Toss Ads)** | **b. 광고 수익 부가세** | **c. 앱인토스 수수료** | **d. 앱인토스 수수료 부가세** | **e. 파트너사 정산금** |
| --- | --- | --- | --- | --- |
| ₩14,700 | ₩1,470 | ₩2,205 | ₩221 | ₩13,774 |

### 정산 내역

당월 수익에 대해 익월 1일에 정산 내역을 제공해요.\
앱인토스 콘솔 > 미니앱 > 좌측 수익화 메뉴 > 광고 관리 > 정산 내역에서 확인할 수 있어요.

### 정산금 지급

당월 수익에 대해 영업일 기준 익월 말에 대금을 지급하고 있어요.\
\*말일자가 휴무일 경우, 직전 영업일에 지급돼요.\
\*세금계산서가 적시에 발행되어야 지급이 원활히 진행되며, 세금계산서 미발행 시 지급 일정이 달라질 수 있어요.

### 세금계산서 발행

인앱 광고는 총 2개의 부가세가 존재하며, 각각 세금계산서가 발행돼요.

1. **광고 수익에 대한 부가세 & 세금 계산서**

   파트너사가 세금계산서를 직접 발행하여 토스에 제출해야 해요.

   * 세금계산서 작성일자: 광고 수익월의 종료일(말일)
   * 세금계산서 발행 주소: yj.jang@toss.im
   * 토스의 사업자등록증이 필요한 경우, 앱인토스 채널톡으로 문의해 주세요.

   매월 2영업일까지 토스에 세금계산서 발행을 진행해야 원활한 대금 지급이 가능해요.\
   광고 수익에 대한 부가세는 정산금 지급 시점에 함께 지급돼요.

2. **앱인토스 수수료에 대한 부가세 & 세금 계산서**

   정산금 지급 시 토스가 부가세를 선공제하고 세금계산서를 발행해드리며, 매월 3영업일까지 발행하고 있어요.

## 3. 인앱 결제 수수료

### 수수료 구조 및 정산

앱인토스는 앱마켓(구글/애플)을 통해 인앱 결제 서비스를 제공하며, 앱마켓과 앱인토스 각각 결제 수익에 대한 수수료가 발생해요.\
\*CBT 기간 동안 한시적으로 토스 수수료 0% 프로모션이 적용되고 있어요.

1. 앱마켓 수수료: 공급가 기준 15% / 30%\
   현재는 토스 앱에서 발생하는 총 수익이 앱마켓이 설정한 수수료 인하 기준에 해당하여 15%의 수수료가 발생해요.\
   추후 총 수익이 늘어남에 따라 수수료가 30%로 변경될 수 있어요.
2. 토스 수수료: 결제가 기준 5%

앱마켓이 지급한 정산금에서 토스 수수료와 부가세를 선취한 금액이 파트너사에 지급돼요.

**<애플>**

| **결제 금액 (부가세포함)** | **(-)앱마켓 수수료** | **(-)토스 수수료** | **(-)토스 수수료 부가세** | **(=)파트너사 정산금** |
| --- | --- | --- | --- | --- |
| ₩11,000 | ₩1,650 | ₩550 | ₩55 | ₩8,745 |

**<구글>**

| **결제 금액 (부가세포함)** | **(-)앱마켓 수수료** | **(-)토스 수수료** | **(-)토스 수수료 부가세** | **(=)파트너사 정산금** |
| --- | --- | --- | --- | --- |
| ₩11,000 | ₩1,500 | ₩550 | ₩55 | ₩8,895 |

### 정산 내역

당월 수익에 대해 익월 5일 내 정산 내역을 제공해요.\
앱인토스 콘솔 > 미니앱 > 좌측 수익화 메뉴 > 인앱 결제 > 정산 내역에서 확인할 수 있어요.

![](/assets/console_settlement_iap.CxufGFSh.png)

### 정산금 지급

당월 수익에 대해 영업일 기준 익월 말에 대금을 지급하고 있어요.

### 세금계산서 발행

1. **애플 수수료에 대한 부가세 & 세금계산서**\
   \*구글은 별도의 부가세가 존재하지 않아요.\
   애플은 마켓 수수료(15/30%)에 부가세가 발생해요.\
   애플이 파트너사에 직접 세금계산서를 발행할 수 없기 때문에, 토스가 대신 발행하고 있어요.\
   수수료 부가세는 애플 정산금에서 선취될 예정이며, 추후 환급 받을 수 있어요.

2. **토스 수수료에 대한 부가세 & 세금계산서**\
   정산금 지급 시 토스가 부가세를 선취하고 세금계산서를 발행해요.

::: tip 세금계산서의 공급가액/부가세가 건별 정산 내역 합계와 다른 경우

* 세금계산서 발행 시 국세청 권고사항을 기준으로 부가세를 다시 계산해요.
  * 2019년도 5월 국세청의 전자 세금계산서 시스템 개발 지침 개정안에 따라, 부가세가 공급가액의 10%가 되도록 산정돼요.
* 건별 정산 내역의 공급가액과 부가세 합계 금액으로 세금계산서를 발행할 경우, 국세청 권고사항에 맞지 않을 수 있어요.
* 따라서 월 정산 내역의 공급가액과 부가세는 국세청 권고에 맞게 금액 보정을 하고, 이 금액으로 세금계산서를 발행해 드리고 있어요.
  :::

### 현금 영수증

구글 기프트카드를 통해 발생한 결제 건에 대해서는 파트너사가 결제 5일 이내 현금 영수증을 발행해야 하는 의무가 있어요.

* 토스에서 대행 발행 예정이니, 별도로 발행하지 않아도 돼요 (2025.12.01 이후)
* 결제내역에서 주문별 기프트카드 결제 여부를 확인할 수 있으니, 결제 상태를 참고하여 현금 영수증 발급/취소를 해주세요. (결제 수단 정보는 결제 후, 1~2일 내 업데이트돼요.)
* 단, 앱마켓 직권취소 등의 사유로 정산금에 포함되지 않는 환불 건이 발생한 경우, 결제완료 건으로 취급해야 하며 현금 영수증 발급을 취소하면 안 돼요. 익월 초 제공되는 정산 리포트를 함께 참고해 주세요.

## 4. 비즈 월렛

::: tip 비즈 월렛이란?
비즈 월렛은 토스 내 프로모션 집행을 위해 미리 충전해두는 금액이에요.

* 프로모션(토스 포인트) 지급 또는 광고 푸시 발송에 사용할 수 있어요.
* 현재는 신용카드(법인카드 포함)로만 비즈 월렛을 충전할 수 있어요.
  :::

### 사용 내역 및 인보이스

1. **사용 내역**\
   당월 충전, 환불, 사용, 환급 내역 및 현재 사용 가능한 금액을 확인할 수 있으며, 실시간으로 업데이트돼요.

   * 사용 항목은 프로모션 푸시가(\*이하 마케팅) 등록된 시점에 업데이트되며, 실사용(유저 지급 완료) 내역은 인보이스에서 확인할 수 있어요.
   * 환급 항목은 마케팅이 등록될 때 추정한 예산에서 실사용된 예산의 차액을 의미하며, 마케팅 종료 후 최대 1~2일 내 환급이 완료돼요.
   * 현재 사용 가능한 금액은 `충전금 - (환불 + 사용) + 환급금`이며, 실사용 금액이 아닌 사용 금액을 기준으로 계산하므로 인보이스와 금액차가 발생할 수 있어요.

   나의 워크스페이스 > 상단 비즈 월렛 탭에서 확인할 수 있어요.

2. **인보이스**\
   당월 충전, 환불, 실사용 내역 및 기초, 기말 잔액은 익월 1일~2일 사이에 업데이트가 완료돼요.\
   나의 워크스페이스 > 상단 비즈 월렛 탭 > 인보이스 보기 버튼을 눌러 확인할 수 있어요.

## 5. 프로모션 (토스 포인트)

### 과금 구조

프로모션 등록 시 설정한 예산만큼 비즈 월렛에서 1차 차감돼요.\
프로모션 종료 시점 직후 실제 사용한 예산만큼 재계산하여 차액이 환급돼요.\
**토스 포인트는 무상머니이므로, 별도의 부가세 및 세금계산서가 존재하지 않아요.**

## 6. 광고 푸시 요금

### 과금 구조

광고 푸시 발송 비용은 푸시 등록 시점에 비즈 월렛에서 1차 차감돼요. `(예상 발송 건수 * 건당 수수료)`\
실제 발송 시점 직후 `(발송 성공 건수 * 건당 수수료)` 만큼 재계산하여 차액이 환급돼요.

| 발송건수 | 건당 수수료 | 건당 부가세 | 건당 수수료(부가세 포함) | 발송 비용 |
| --- | --- | --- | --- | --- |
| 100 | ₩9 | ₩0.9 | ₩9.9 | ₩990 |

### 세금계산서 발행

실제 발송 성공 건수를 기준으로, 매월 3영업일까지 발행하고 있어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/segment/intro.md'
---
# 이해하기

세그먼트를 생성하여 **원하는 타겟에게 메시지를 보내보세요.**\
생성한 세그먼트를 통해서 **푸시, 알림 발송**과 **토스 홈 광고를 노출**할 수 있어요.

***

## 세그먼트가 무엇인가요?

“세그먼트”는 앱인토스 콘솔에서 **특정 조건에 맞는 유저 그룹을 만들고 관리**하는 기능이에요.\
세그먼트의 카테고리 목록으로 **거래정보**, **유저정보**, **유저활동**, **유저프로파일**을 제공해요.

* 거래정보: 거래 내역 브랜드, 광고 카테고리, 토스페이 등
* 유저정보: 나이, 성별, 신용점수, 앱 버전, 통신사 등
* 유저활동: 내 서비스 최근 방문 등
* 유저프로파일: 금융 성향, 라이프사이클, 관심사 추정 정보 등

![](/assets/segment_intro_1.D-rGY45w.png)

## 세그먼트를 사용하면 무엇이 좋은가요?

* 정확한 타겟팅으로 원하는 조건의 사용자에게만 마케팅을 할 수 있어요.
* 데이터 기반 마케팅이 가능해져, 유저 행동과 특성에 따라 맞춤형 캠페인을 설계할 수 있어요.
* 유저 경험 향상을 통해 개인화된 메시지를 제공함으로써 참여율과 만족도를 높일 수 있어요.

## 참고해 주세요.

* 1개의 조건만 사용할 수 있지 않고, 여러 조건을 합쳐서 **AND 조건 또는 OR 조건을 활용**할 수 있어요.
* **타겟 샘플링**을 통해서 세그먼트의 모수를 조정할 수 있어요.
* 생성했던 세그먼트를 삭제하더라도 동일한 세그먼트 이름을 사용할 수 없어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/tosspay/intro.md'
---
# 이해하기

마찰을 줄이면 **전환율은 올라가고, 결제 실패 및 이탈은 줄어들어요.**\
토스페이를 통해 실물 상품/서비스 **결제를 빠르고 매끄럽게 진행**하세요.

***

## 토스페이가 무엇인가요?

토스페이는 **사용자들이 토스 앱에서 빠르고 안전하게 결제할 수 있도록 지원하는 간편결제 서비스**예요.\
미리 등록한 결제 정보를 활용해 비밀번호만으로 간단히 결제할 수 있는 서비스로서, 공인인증서와 같은 복잡한 인증 절차 없이 빠르고 편리하게 결제를 완료할 수 있어요.

![](/assets/tosspay-intro-1.MvGNiCEv.png)

## 토스페이를 사용하면 무엇이 좋은가요?

* 간편결제 사용자가 서비스에 만족하는 비율은 95%로, 고객 만족도를 개선할 수 있어요.
* 토스머니, 카드 등 상황에 맞는 수단을 자유롭게 선택할 수 있어요.
* 결제 과정에서 발생하는 심리적 장벽을 낮추고 결제전환에 도움을 주어 이탈을 방지할 수 있어요.

## 참고해 주세요

* 기존에 토스페이를 이용하고 있더라도, **앱인토스의 토스페이 가맹점 key를 발급 받아서 사용**해야 해요.
* 주문번호를 중복 사용 시 결제 생성이 거절돼요.
* 상품명·수량·총액·할인·환불 규정을 결제 전에 분명히 고지해야 해요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인앱
  결제/IAP.md
---

# 인앱 결제

## `IAP`

`IAP`는 인앱 결제 관련 함수를 모아둔 객체예요.

::: tip 주의하세요

토스앱 5.219.0 버전부터 지원해요. 인앱 결제를 지원하지 않는 버전에서는 `undefined`를 반환해요.

:::

### 시그니처

```typescript
IAP {
  getProductItemList: typeof getProductItemList;
  createOneTimePurchaseOrder: typeof createOneTimePurchaseOrder;
  getPendingOrders: typeof getPendingOrders;
  getCompletedOrRefundedOrders: typeof getCompletedOrRefundedOrders;
  completeProductGrant: typeof completeProductGrant;
}
```

### 프로퍼티

## `getProductItemList`

`getProductItemList` 는 인앱 결제로 구매할 수 있는 상품 목록을 담은 함수예요. 상품 목록을 화면에 표시할 때 사용해요.

### 시그니처

```typescript
function getProductItemList(): Promise<{ products: IapProductListItem[] } | undefined>;
```

### 반환값

### 프로퍼티

```typescript
interface IapProductListItem {
  sku: string;
  displayAmount: string;
  displayName: string;
  iconUrl: string;
  description: string;
}
```

### 예제

구매 가능한 인앱결제 상품목록 가져오기

::: code-group

```js [js]
import { IAP } from "@apps-in-toss/web-framework";

async function handleGetProductItemList() {
  const response = await IAP.getProductItemList();
  
  return response?.products ?? [];
}
```

```tsx [React]
import { IAP, IapProductListItem } from "@apps-in-toss/web-framework";
import { Button, List, ListRow } from "@toss/tds-mobile";
import { useEffect, useState, useCallback } from "react";

function IapProductList() {
  const [products, setProducts] = useState<IapProductListItem[]>([]);

  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
      },
      onEvent: (event) => {
        console.log(event);
        
        if(event.type === 'success') {
          cleanup();
        }
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  useEffect(() => {
    async function fetchProducts() {
      try {
        const response = await IAP.getProductItemList();
        setProducts(response?.products ?? []);
      } catch (error) {
        console.error("상품 목록을 가져오는 데 실패했어요:", error);
      }
    }

    fetchProducts();
  }, []);

  return (
    <List>
      {products.map((product) => (
        <ListRow
          key={product.sku}
          left={<ListRow.Image type="square" src={product.iconUrl} />}
          contents={
            <ListRow.Texts
              type="3RowTypeA"
              top={product.displayName}
              middle={product.description}
              bottom={product.displayAmount}
            />
          }
          right={
            <Button size="medium" onClick={() => handleBuy(product.sku)}>
              구매하기
            </Button>
          }
        />
      ))}
    </List>
  );
}

```

```tsx [React Native]
import { IAP, IapProductListItem } from "@apps-in-toss/framework";
import { Button, List, ListRow } from "@toss/tds-react-native";
import { useEffect, useState, useCallback } from "react";

function IapProductList() {
  const [products, setProducts] = useState<IapProductListItem[]>([]);

  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
      },
      onEvent: (event) => {
        console.log(event);

        if(event.type === 'success') {
          cleanup();
        }
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  useEffect(() => {
    async function fetchProducts() {
      try {
        const response = await IAP.getProductItemList();
        setProducts(response?.products ?? []);
      } catch (error) {
        console.error("상품 목록을 가져오는 데 실패했어요:", error);
      }
    }

    fetchProducts();
  }, []);

  return (
    <List>
      {products.map((product) => (
        <ListRow
          key={product.sku}
          left={<ListRow.Image type="square" source={{ uri: product.iconUrl }} />}
          right={
            <Button size="medium" onPress={() => handleBuy(product.sku)}>
              구매하기
            </Button>
          }
          contents={
            <ListRow.Texts
              type="3RowTypeA"
              top={product.displayName}
              middle={product.description}
              bottom={product.displayAmount}
            />
          }
        />
      ))}
    </List>
  );
}
```

:::

### 예제 응답

```json
{
  "products": [
    {
      "sku": "sku1",
      "displayName": "광고 제거",
      "displayAmount": "4,900원",
      "iconUrl": "https://cdn.example.com/icons/premium-monthly.png",
      "description": "광고 제거 및 프리미엄 기능 제공"
    },
    {
      "sku": "sku2",
      "displayName": "코인 100개",
      "displayAmount": "9,900원",
      "iconUrl": "https://cdn.example.com/icons/coin-100.png",
      "description": "앱 내에서 사용할 수 있는 코인 100개"
    }
  ]
}
```

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-in-app-purchase](https://github.com/toss/apps-in-toss-examples/tree/main/with-in-app-purchase) 코드를 내려받아 체험해 보세요.

## `createOneTimePurchaseOrder`

`createOneTimePurchaseOrder` 함수는 인앱 결제 결제창을 띄우고, 사용자가 결제를 진행해요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.

### 시그니처

```typescript
function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;
```

### 파라미터

```typescript

interface IapCreateOneTimePurchaseOrderOptions {
  options: {sku: string; processProductGrant: (params: { orderId: string }) => boolean | Promise<boolean> };
  onEvent: (event: SuccessEvent) => void | Promise<void>;
  onError: (error: unknown) => void | Promise<void>;
}

interface IapCreateOneTimePurchaseOrderResult {
  orderId: string;
  displayName: string;
  displayAmount: string;
  amount: number;
  currency: string;
  fraction: number;
  miniAppIconUrl: string | null;
}

interface SuccessEvent {
  type: 'success';
  data: IapCreateOneTimePurchaseOrderResult;
}
```

### 에러코드

### 반환값

### 예제

특정 인앱결제 주문서 페이지로 이동하기

::: code-group

```js [js]
import { IAP } from "@apps-in-toss/web-framework";

let cleanup; 

function handleBuyProduct(sku) {
  cleanup = IAP.createOneTimePurchaseOrder({
    options: {
      sku,
      processProductGrant: ({ orderId }) => {
        console.log('상품 지급 로직 실행:', orderId);
        return true;
      },
    },
    onEvent: (event) => {
      console.log('이벤트:', event);
      cleanup?.();
    },
    onError: (error) => {
      console.error('인앱결제에 실패했어요:', error);
      cleanup?.();
    },
  });
}

window.addEventListener('pagehide', () => {
  cleanup?.();
});
```

```tsx [React]
import { IAP } from "@apps-in-toss/web-framework";
import { Button } from "@toss/tds-mobile";
import { useCallback } from "react";
 
interface Props {
  sku: string;
}
 
function IapCreateOneTimePurchaseOrderButton({ sku }: Props) { 
  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
      },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  return <Button onClick={handleBuy}>구매하기</Button>;
}
```

```tsx [React Native]
import { IAP } from "@apps-in-toss/framework";
import { Button } from "@toss/tds-react-native";
import { useCallback } from "react";
 
interface Props {
  sku: string;
}
 
function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
  const handleClick = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
        },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, []);

  return <Button onPress={handleClick}>구매하기</Button>;
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-in-app-purchase](https://github.com/toss/apps-in-toss-examples/tree/main/with-in-app-purchase) 코드를 내려받아 체험해 보세요.

## `getPendingOrders`

`getPendingOrders` 는 **결제는 완료되었지만 상품이 아직 지급되지 않은 주문 목록**을 가져오는 함수예요.\
조회된 주문 정보를 확인하여 사용자에게 상품을 지급하세요.\
`createOneTimePurchaseOrder` 함수 호출 후 결과를 받지 못한 경우에도 해당 주문을 조회할 수 있어요.

앱 버전이 최소 지원 버전(안드로이드 5.234.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.

### 시그니처

```typescript
function getPendingOrders(): Promise<{ orders: Order[] } | undefined>;
```

### 반환값

### 반환 객체 프로퍼티

```tsx
interface Order {
  orderId: string;
  sku: string;
  paymentCompletedDate?: string;
}
```

::: tip 필드 업데이트 안내

* **SDK 1.4.2**: sku 필드가 추가되었어요.
  이 필드는 **안드로이드 5.234.0 이상, iOS 5.231.0 이상**에서만 반환돼요.
* **SDK 1.4.8**: paymentCompletedDate 필드가 추가되었어요.
  결제 완료 시점을 확인할 수 있어요.
  :::

### 예제

::: code-group

```js [js]
import { IAP } from '@apps-in-toss/web-framework';

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React]
import { IAP } from '@apps-in-toss/web-framework';

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React Native]
import { IAP } from '@apps-in-toss/framework';

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}
```

:::

## `completeProductGrant`

`completeProductGrant` 함수는 **대기 중인 주문의 상품 지급을 완료 처리하는 함수**예요.\
사용자에게 상품을 지급하고 `completeProductGrant` 함수를 호출하여 지급 상태를 완료로 변경하세요.

앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.

### 시그니처

```typescript
function completeProductGrant(params: {
  params: {
    orderId: string;
  };
}): Promise<boolean | undefined>;
```

### 파라미터

### 반환값

### 예제

::: code-group

```js [js]
import { IAP } from '@apps-in-toss/web-framework';

async function handleCompleteProductGrant(orderId) {
  try {
    await IAP.completeProductGrant({ params: { orderId } });
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React]
import { IAP } from '@apps-in-toss/web-framework';

async function handleCompleteProductGrant(orderId: string) {
  try {
    await IAP.completeProductGrant({ params: { orderId } });
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React Native]
import { IAP } from '@apps-in-toss/framework';

async function handleCompleteProductGrant(orderId: string) {
  try {
    await IAP.completeProductGrant({ params: { orderId } });
  } catch (error) {
    console.error(error);
  }
}
```

:::

## `getCompletedOrRefundedOrders`

`getCompletedOrRefundedOrders` 는 인앱결제로 구매하고 환불한 주문 목록을 가져와요.\
인앱결제 결제 및 상품 지급이 완료된 주문건와 환불된 주문건을 조회할 수 있어요.

결제는 완료되었지만 상품이 아직 지급되지 않은 주문건은 조회되지 않아요.\
[`getPendingOrders`](/bedrock/reference/framework/인앱%20결제/getPendingOrders)함수를 통해 `orderId`를 조회하여 사용자에게 상품을 지급한 후 [`completeProductGrant`](/bedrock/reference/framework/인앱%20결제/completeProductGrant)함수를 통해 상품 지급을 완료 처리하세요.

앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.

::: tip 페이지네이션

* **한 페이지당 최대 50개** 의 주문이 반환돼요.
* 다음 페이지가 있을 때는 `hasNext`가 `true`이며, 응답의 `nextKey`를 다음 호출의 `key` 파라미터로 전달해 이어서 조회하세요.
  :::

### 시그니처

```typescript
function getCompletedOrRefundedOrders(params?: {
  key?: string | null;
}): Promise<CompletedOrRefundedOrdersResult | undefined>;
```

### 반환값

### 반환 객체 프로퍼티

```tsx
interface CompletedOrRefundedOrdersResult {
  hasNext: boolean;
  nextKey?: string | null;
  orders: {
    orderId: string;
    sku: string;
    status: 'COMPLETED' | 'REFUNDED';
    date: string;
  }[];
}
```

### 예제

::: code-group

```js [js]
import { IAP } from '@apps-in-toss/web-framework';

async function fetchOrders() {
  try {
    const orders = await IAP.getCompletedOrRefundedOrders();
    return orders;
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React]
import { IAP } from '@apps-in-toss/web-framework';

async function fetchOrders() {
  try {
    const orders = await IAP.getCompletedOrRefundedOrders();
    return orders;
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React Native]
import { IAP } from '@apps-in-toss/framework';

async function fetchOrders() {
  try {
    const orders = await IAP.getCompletedOrRefundedOrders();
    return orders;
  } catch (error) {
    console.error(error);
  }
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/BannerAd.md
---
# 인앱 광고 2.0 ver2 (배너 광고)

배너 광고(List Banner)를 표시할 수 있는 광고 라이브러리예요.

## 콘솔 가이드

### 테스트 광고 ID

테스트 환경에서는 아래 ID를 사용해야 해요.

::: tip 주의하세요
실제 광고 ID로 개발·테스트할 경우 **정책 위반으로 불이익**이 발생할 수 있어요.\
반드시 테스트용 ID를 사용해주세요.
:::

* 배너 광고 : `ait-ad-test-banner-id`

### 광고 ID 발급

현재 콘솔에서 발급 기능을 준비 중이에요.
필요한 갯수와 명칭을 앱인토스 TAM에게 요청주시면 바로 발급을 도와드려요.

배너 광고 테스트는 테스트용 ID를 사용해주세요.

* 배너 광고 : `ait-ad-test-banner-id`

## 지원 버전

배너 광고 API는 토스 앱 버전에 따라 다르게 동작해요 :

| 토스 앱 버전     | 지원 여부 | 설명                    |
| ---------------- | --------- | ----------------------- |
| **5.241.0 이상** | 지원      | 배너 광고 사용 가능     |
| **5.241.0 미만** | 미지원    | 배너 광고 API 사용 불가 |

> `isSupported()` 메서드를 사용하여 현재 환경에서 배너 광고를 사용할 수 있는지 확인할 수 있어요.

::: tip 5.241.0 미만 버전에서는 예외 처리가 필요해요
토스앱 5.241.0 미만에서는 빈 화면이 노출될 수 있으니 반드시 예외 처리를 해주세요.\
[토스앱 버전 가져오기](/bedrock/reference/framework/환경%20확인/getTossAppVersion.html) 기능을 사용해 예외 처리를 해주세요.
:::

## 광고 정책

### 토스 애즈 SSP 정책

| **유형**                  | **금지 행위**                                                 | **구체적 예시**                                                                                         |                                                                            |
| ------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **UI 조작**               | 광고·콘텐츠 구분이 불명확하거나 사용자를 오인시키는 배너 변경 | “추천 서비스”, “금융 팁” 등으로 광고를 위장, CTA 문구 임의 변경                                         | 광고는 반드시 “ad” 표기 유지, 광고 타이틀·라벨 임의 수정 금지              |
| **광고 로직 변조**        | SDK 기본 클릭·노출 로직 수정, 자동 리프레시·리디렉션 추가     | web-public에서 광고 클릭 시 별도 페이지로 강제 이동 , Back 버튼 차단 / Dead-end 구조 / ATF 첫 화면 광고 | SDK 기본 이벤트(Click / Impression) 구조 변조 금지. SDK 외부 API 호출 불가 |
| **자동화 트래픽**         | 자동 클릭·자동 새로고침 등 비정상 노출 유도                   | 광고 영역을 주기적 refresh 처리, Back 버튼 차단 / Dead-end 구조 / ATF 첫 화면 광고                      | 트래픽 조작 감지 시 SSP 로그 차단 + 정산 보류                              |
| **광고 디자인 임의 수정** | 광고 색상, 배치, CTA, 크기 등 임의 변경                       | Toss Ads 가이드 외 광고 단위의 색상·글꼴 변경                                                           | 모든 광고 UI는 **web-base 표준 컴포넌트** 사용 필수                        |
| **보상·참여형 클릭**      | 클릭 시 리워드·이벤트 제공 문구 추가                          | “광고 클릭 시 포인트 지급” / “참여하면 혜택”                                                            | 클릭 보상성 문구·이벤트 연동 금지                                          |
| **광고 은닉 또는 겹침**   | 다른 요소 위에 배너를 덮거나 숨김                             | 다른 카드 UI 뒤에 광고 DOM 삽입                                                                         | 광고는 노출 상태가 명확히 확인 가능해야 함                                 |

### UX / Product Principle 운영 원칙

| **Toss Principle**             | **적용 기준**                                                   | **예시**                                  |
| ------------------------------ | --------------------------------------------------------------- | ----------------------------------------- |
| **Simplicity**                 | 광고는 명료해야 하며, 추가 설명 없이 의미를 이해할 수 있어야 함 | “지금 보기”, “광고 보기” 등 명확 CTA 사용 |
| **Clear Action**               | 광고 클릭 후 어떤 행동이 발생할지 사용자가 예측 가능해야 함     | 리디렉션·새창 이동 시 고지 문구 노출      |
| **No Deception (UX Red Rule)** | 광고가 예상치 못한 순간, 형태, 위치에서 등장하지 않아야 함      | 서비스 진입 직후 전면 배너 금지           |
| **Value First**                | 광고는 고객의 서비스 목표를 방해하지 않아야 함                  | 결제/계좌 개설 흐름 중 광고 삽입 금지     |

***

## API 개요

* `TossAds.initialize(options: TossAdsInitializeOptions): void` — 배너 광고 SDK를 초기화해요. 광고를 표시하기 전에 반드시 한 번 호출해야 해요.

* `TossAds.attach(adGroupId: string, target: string | HTMLElement, options?: TossAdsAttachOptions): void` — 특정 DOM 요소에 배너 광고를 부착해요.

* `TossAds.destroy(slotId: string): void` — 특정 배너 슬롯을 제거해요.

* `TossAds.destroyAll(): void` — 초기화된 모든 배너 슬롯을 제거해요.

각 API는 `isSupported()` 프로퍼티를 통해 현재 환경에서 해당 기능 사용 가능 여부를 확인할 수 있어요.

***

## 배너 광고 SDK 초기화

### `TossAds.initialize`

```typescript
TossAds.initialize(options: TossAdsInitializeOptions): void;
```

배너 광고 SDK를 초기화해요. 초기화 과정은 비동기로 진행되며, 완료 여부는 콜백으로 전달돼요.\
광고를 사용하기 전에 반드시 한 번 초기화해야 하고, 앱의 최상위 컴포넌트에서 한 번만 호출하는 것을 권장해요.

### 파라미터

### 프로퍼티

#### `isSupported`

```typescript
TossAds.initialize.isSupported(): boolean
```

현재 환경에서 배너 광고를 사용할 수 있는지 확인해요.

### 예제

:::code-group

```tsx[React]
import { TossAds } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';

function App() {
  const [isInitialized, setIsInitialized] = useState(false);

  useEffect(() => {
    // 지원 여부 확인
    if (!TossAds.initialize.isSupported()) {
      console.warn('배너 광고 기능을 사용할 수 없습니다.');
      return;
    }

    // SDK 초기화
    TossAds.initialize({
      callbacks: {
        onInitialized: () => {
          console.log('SDK 초기화 완료');
          setIsInitialized(true);
        },
        onInitializationFailed: (error) => {
          console.error('SDK 초기화 실패:', error);
        },
      },
    });
  }, []);

  return <div>{isInitialized ? '광고 준비 완료' : '광고 준비 중...'}</div>;
}
```

```tsx[ReactNative]
import React, { useEffect, useState } from 'react';
import { View, Text, Alert } from 'react-native';
import { TossAds } from '@apps-in-toss/framework';

export default function App() {
  const [isInitialized, setIsInitialized] = useState(false);

  useEffect(() => {
    // 지원 여부 확인
    if (!TossAds.initialize.isSupported()) {
      console.warn('배너 광고 기능을 사용할 수 없습니다.');
      return;
    }

    // SDK 초기화
    TossAds.initialize({
      callbacks: {
        onInitialized: () => {
          console.log('SDK 초기화 완료');
          setIsInitialized(true);
        },
        onInitializationFailed: (error) => {
          console.error('SDK 초기화 실패:', error);
          // 네이티브 환경에서는 Alert를 띄워 사용자/개발자에게 알릴 수 있어요
          Alert.alert('배너 광고 초기화 실패', String(error?.message ?? error));
        },
      },
    });
  }, []);

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>{isInitialized ? '광고 준비 완료' : '광고 준비 중...'}</Text>
    </View>
  );
}

```

:::

### TossAdsInitializeOptions

```typescript
interface TossAdsInitializeOptions {
  callbacks?: {
    onInitialized?: () => void;
    onInitializationFailed?: (error: Error) => void;
  };
}
```

`TossAds.initialize` 함수의 옵션 타입이에요.

***

## 배너 광고 부착

### `TossAds.attach`

```typescript
TossAds.attach(adGroupId: string, target: string | HTMLElement, options?: TossAdsAttachOptions): void;
```

특정 DOM 요소에 배너 광고를 부착해요.\
`TossAds.initialize`를 먼저 호출하여 SDK를 초기화한 후에 사용해야해요.

:::tip 광고 부착 가이드
광고를 부착하는 엘리먼트 내부는 비워둬야 해요.
:::

### 파라미터

### 프로퍼티

#### `isSupported`

```typescript
TossAds.attach.isSupported(): boolean
```

현재 환경에서 배너 광고를 사용할 수 있는지 확인해요.

### 예제

:::code-group

```tsx[React]
import { TossAds } from '@apps-in-toss/web-framework';
import { useEffect, useRef, useState } from 'react';

function BannerAdComponent({ adGroupId }: { adGroupId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [isInitialized, setIsInitialized] = useState(false);
  const slotIdRef = useRef<string | null>(null);

  useEffect(() => {
    // SDK 초기화
    if (!TossAds.initialize.isSupported()) return;

    TossAds.initialize({
      callbacks: {
        onInitialized: () => setIsInitialized(true),
        onInitializationFailed: (error) => {
          console.error('초기화 실패:', error);
        },
      },
    });
  }, []);

  useEffect(() => {
    if (!isInitialized || !containerRef.current) return;

    // 배너 부착
    TossAds.attach(adGroupId, containerRef.current, {
      padding: '20px',
      callbacks: {
        onAdRendered: (payload) => {
          console.log('광고 렌더링 완료:', payload.slotId);
          slotIdRef.current = payload.slotId;
        },
        onAdViewable: (payload) => {
          console.log('광고 노출됨:', payload.slotId);
        },
        onAdImpression: (payload) => {
          console.log('광고 노출 기록됨 (수익 발생):', payload.slotId);
        },
        onAdClicked: (payload) => {
          console.log('광고 클릭됨:', payload.slotId);
        },
        onNoFill: (payload) => {
          console.warn('표시할 광고가 없습니다:', payload.slotId);
        },
        onAdFailedToRender: (payload) => {
          console.error('광고 렌더링 실패:', payload.error.message);
        },
      },
    });

    // 클린업
    return () => {
      if (slotIdRef.current) {
        TossAds.destroy(slotIdRef.current);
      }
    };
  }, [isInitialized, adGroupId]);

  return <div ref={containerRef} style={{ minHeight: 120, width: '100%' }} />;
}
```

````tsx[React Native]
import React, { useEffect, useRef, useState } from 'react';
import { View, Text, Alert } from 'react-native';
import { TossAds } from '@apps-in-toss/framework';

function BannerAdComponent({ adGroupId }: { adGroupId: string }) {
  const [isInitialized, setIsInitialized] = useState(false);
  const slotIdRef = useRef<string | null>(null);

  useEffect(() => {
    // SDK 초기화
    if (!TossAds.initialize.isSupported()) {
      console.warn('배너 광고 기능을 사용할 수 없습니다.');
      return;
    }

    TossAds.initialize({
      callbacks: {
        onInitialized: () => setIsInitialized(true),
        onInitializationFailed: (error) => {
          console.error('초기화 실패:', error);
          Alert.alert('배너 광고 초기화 실패', String(error?.message ?? error));
        },
      },
    });
  }, []);

  useEffect(() => {
    if (!isInitialized) return;

    TossAds.attach(adGroupId, undefined, {
      padding: '20px',
      callbacks: {
        onAdRendered: (payload) => {
          console.log('광고 렌더링 완료:', payload.slotId);
          slotIdRef.current = payload.slotId;
        },
        onAdViewable: (payload) => {
          console.log('광고 노출됨:', payload.slotId);
        },
        onAdImpression: (payload) => {
          console.log('광고 노출 기록됨 (수익 발생):', payload.slotId);
        },
        onAdClicked: (payload) => {
          console.log('광고 클릭됨:', payload.slotId);
        },
        onNoFill: (payload) => {
          console.warn('표시할 광고가 없습니다:', payload.slotId);
        },
        onAdFailedToRender: (payload) => {
          console.error('광고 렌더링 실패:', payload.error.message);
        },
      },
    });

    return () => {
      if (slotIdRef.current) {
        TossAds.destroy(slotIdRef.current);
      }
    };
  }, [isInitialized, adGroupId]);

  return (
    <View style={{ minHeight: 120, width: '100%', backgroundColor: '#f2f2f2' }}>
      <Text>배너 광고 영역</Text>
    </View>
  );
}

export default BannerAdComponent;

:::


### TossAdsAttachOptions

```typescript
interface TossAdsAttachOptions {
  theme?: 'light' | 'dark';
  padding?: string;
  callbacks?: TossAdsBannerSlotCallbacks;
}
````

`TossAds.attach` 함수의 옵션 타입이에요.

### TossAdsBannerSlotCallbacks

```typescript
interface TossAdsBannerSlotCallbacks {
  onAdRendered?: (payload: TossAdsBannerSlotEventPayload) => void;
  onAdViewable?: (payload: TossAdsBannerSlotEventPayload) => void;
  onAdClicked?: (payload: TossAdsBannerSlotEventPayload) => void;
  onAdImpression?: (payload: TossAdsBannerSlotEventPayload) => void;
  onAdFailedToRender?: (payload: TossAdsBannerSlotErrorPayload) => void;
  onNoFill?: (payload: { slotId: string; adGroupId: string; adMetadata: {} }) => void;
}
```

배너 광고 이벤트 콜백이에요.

* `onAdRendered`: 광고가 렌더링되었어요. `slotId`를 여기서 받아 저장할 수 있어요.
* `onAdViewable`: 광고가 화면에 노출되었어요.
* `onAdImpression`: 광고 노출이 기록되었어요. (수익 발생 시점)
* `onAdClicked`: 사용자가 광고를 클릭했어요.
* `onAdFailedToRender`: 광고 렌더링에 실패했어요.
* `onNoFill`: 표시할 광고가 없어요.

### TossAdsBannerSlotEventPayload

```typescript
interface TossAdsBannerSlotEventPayload {
  slotId: string;
  adGroupId: string;
  adMetadata: {
    creativeId: string;
    requestId: string;
  };
}
```

배너 광고 이벤트 페이로드예요.

* `slotId`: 생성된 슬롯 ID - `TossAds.destroy`에 전달할 수 있어요.
* `adGroupId`: 광고 그룹 ID
* `adMetadata`: 광고 메타데이터 (creativeId, requestId)

### TossAdsBannerSlotErrorPayload

```typescript
interface TossAdsBannerSlotErrorPayload {
  slotId: string;
  adGroupId: string;
  adMetadata: {};
  error: {
    code: number;
    message: string;
    domain?: string;
  };
}
```

배너 광고 에러 페이로드예요.

***

## 배너 슬롯 제거

### `TossAds.destroy`

```typescript
TossAds.destroy(slotId: string): void;
```

특정 슬롯 ID의 배너를 제거해요.

### 파라미터

### 프로퍼티

#### `isSupported`

```typescript
TossAds.destroy.isSupported(): boolean
```

현재 환경에서 배너 광고를 사용할 수 있는지 확인해요.

### 예제

:::code-group

```tsx[React]
// onAdRendered에서 받은 slotId로 배너 제거
const handleRemoveBanner = () => {
  if (slotIdRef.current) {
    TossAds.destroy(slotIdRef.current);
  }
};
```

```tsx[React Native]
// onAdRendered에서 받은 slotId로 배너 제거
const handleRemoveBanner = () => {
  if (slotIdRef.current) {
    TossAds.destroy(slotIdRef.current);
  }
};
```

## :::

## 모든 배너 슬롯 제거

### `TossAds.destroyAll`

```typescript
TossAds.destroyAll(): void;
```

초기화된 모든 배너 슬롯을 제거해요.

### 프로퍼티

#### `isSupported`

```typescript
TossAds.destroyAll.isSupported(): boolean
```

현재 환경에서 배너 광고를 사용할 수 있는지 확인해요.

### 예제

:::code-group

```tsx[React]
// 페이지 이동 시 모든 배너 제거
useEffect(() => {
  return () => {
    TossAds.destroyAll();
  };
}, []);
```

```tsx[React Native]
// 페이지 이동 시 모든 배너 제거
useEffect(() => {
  return () => {
    TossAds.destroyAll();
  };
}, []);
```

:::

***

## 사용 가이드

### 초기화 타이밍

SDK는 앱 시작 시점에 한 번만 초기화하는 것이 좋아요. 다음과 같은 시점에 초기화를 권장해요 :

* 앱 최상위 컴포넌트(App.tsx) 마운트 시
* 광고를 표시할 첫 화면 진입 전

```tsx
// ✅ 좋은 예: 앱 시작 시 초기화
function App() {
  useEffect(() => {
    if (TossAds.initialize.isSupported()) {
      TossAds.initialize({
        callbacks: {
          onInitialized: () => console.log('SDK 준비 완료'),
        },
      });
    }
  }, []);

  return <Router />;
}

// ❌ 나쁜 예: 매번 컴포넌트마다 초기화
function BannerComponent() {
  useEffect(() => {
    TossAds.initialize({
      /* ... */
    }); // 중복 초기화 시도
  }, []);
}
```

### 메모리 관리

컴포넌트 언마운트 시 배너를 제거해야 메모리 누수를 방지할 수 있어요.

```tsx
useEffect(() => {
  // 배너 부착 로직...
  const slotId = /* ... */;

  return () => {
    // 클린업
    if (slotId) {
      TossAds.destroy(slotId);
    }
  };
}, []);
```

### slotId 관리

각 콜백의 `payload.slotId`를 저장해두고, 나중에 `TossAds.destroy`에 전달하여 특정 배너를 제거할 수 있어요.

```tsx
const slotIdRef = useRef<string | null>(null);

TossAds.attach(adGroupId, element, {
  callbacks: {
    onAdRendered: (payload) => {
      // slotId 저장
      slotIdRef.current = payload.slotId;
    },
  },
});

// 나중에 제거
useEffect(() => {
  return () => {
    if (slotIdRef.current) {
      TossAds.destroy(slotIdRef.current);
    }
  };
}, []);
```

### 에러 처리

항상 `onInitializationFailed`와 `onAdFailedToRender` 콜백을 제공하여 에러에 대비하세요.

```tsx
TossAds.initialize({
  callbacks: {
    onInitialized: () => {
      console.log('초기화 성공');
    },
    onInitializationFailed: (error) => {
      console.error('초기화 실패:', error);
      // 사용자에게 적절한 피드백 제공
    },
  },
});

TossAds.attach(adGroupId, element, {
  callbacks: {
    onAdFailedToRender: (payload) => {
      console.error('광고 렌더링 실패:', payload.error.message);
      // 대체 컨텐츠 표시 또는 재시도
    },
  },
});
```

### padding 설정

List Banner 광고에 여백이 필요한 경우 `padding` 옵션으로 조절할 수 있어요. CSS padding 문법을 따릅니다.

```tsx
TossAds.attach(adGroupId, element, {
  padding: '20px', // 상하좌우 20px
  // padding: '10px 20px', // 상하 10px, 좌우 20px
  // padding: '10px 20px 30px 40px', // 상 우 하 좌
});
```

> **참고**: padding은 List Banner 타입에만 적용되며, Native Image 타입에는 적용되지 않아요.

***

## 이벤트 플로우

```
TossAds.initialize 호출
  ↓
onInitialized 콜백 (초기화 완료)
  ↓
TossAds.attach 호출
  ↓
onAdRendered 이벤트 (광고 렌더링 완료, slotId 획득)
  ↓
onAdViewable 이벤트 (광고가 화면에 노출됨)
  ↓
onAdImpression 이벤트 (광고 노출 기록됨)
  ↓
onAdClicked 이벤트 (선택적 - 사용자 클릭 시)
```

***

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: ""This feature is not supported in the current environment" 에러가 발생해요",
a: \`1. 토스 앱 환경에서 실행 중인지 확인해주세요.

## 재사용 가능한 커스텀 훅

여러 화면에서 배너 광고를 사용할 때 커스텀 훅으로 분리하면 편리해요.

### 초기화 훅

앱 최상위 컴포넌트에서 한 번만 호출하세요.

```tsx
import { useEffect, useState } from 'react';
import { TossAds } from '@apps-in-toss/web-framework';

export function useInitializeBannerAd() {
  const [isInitialized, setIsInitialized] = useState(false);

  useEffect(() => {
    if (!TossAds.initialize.isSupported()) {
      console.warn('배너 광고를 사용할 수 없습니다.');
      return;
    }

    TossAds.initialize({
      callbacks: {
        onInitialized: () => setIsInitialized(true),
        onInitializationFailed: (error) => {
          console.error('배너 광고 초기화 실패:', error);
        },
      },
    });
  }, []);

  return { isInitialized };
}
```

### 배너 부착 훅

각 페이지에서 배너를 표시할 때 사용하세요.

```tsx
import { useEffect, useRef } from 'react';
import { TossAds, type TossAdsBannerSlotCallbacks } from '@apps-in-toss/web-framework';

export function useAttachBannerAd(adGroupId: string, isInitialized: boolean, callbacks?: TossAdsBannerSlotCallbacks) {
  const containerRef = useRef<HTMLDivElement>(null);
  const slotIdRef = useRef<string | null>(null);

  useEffect(() => {
    if (!isInitialized || !containerRef.current || !adGroupId) {
      return;
    }

    TossAds.attach(adGroupId, containerRef.current, {
      padding: '20px',
      callbacks: {
        onAdRendered: (payload) => {
          slotIdRef.current = payload.slotId;
          callbacks?.onAdRendered?.(payload);
        },
        onAdViewable: callbacks?.onAdViewable,
        onAdClicked: callbacks?.onAdClicked,
        onAdImpression: callbacks?.onAdImpression,
        onNoFill: callbacks?.onNoFill,
        onAdFailedToRender: callbacks?.onAdFailedToRender,
      },
    });

    return () => {
      if (slotIdRef.current) {
        TossAds.destroy(slotIdRef.current);
      }
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [isInitialized, adGroupId]);

  return { containerRef };
}
```

### 사용 예시

```tsx
function MyPage() {
  const { isInitialized } = useInitializeBannerAd();
  const { containerRef } = useAttachBannerAd('your-ad-group-id', isInitialized, {
    onAdRendered: (payload) => console.log('광고 렌더링:', payload.slotId),
    onAdImpression: () => console.log('광고 노출'),
  });

  return (
    <div>
      <h1>내 페이지</h1>
      <div ref={containerRef} style={{ minHeight: 120, width: '100%' }} />
    </div>
  );
}
```

> **참고**: `useInitializeBannerAd`는 앱 최상위에서 한 번만 호출하는 것을 권장하지만, 여러 번 호출해도 안전합니다.\
> 이미 초기화된 경우 중복 초기화를 시도하지 않습니다.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/IntegratedAd.md
---

# 인앱 광고 2.0 ver2 (전면형/보상형 광고)

인앱 광고 2.0 ver2는 **토스 애즈(Toss Ads)** 와 **구글 애드몹(Google AdMob)** 을 통합해 환경에 따라 **가장 적합한 광고를 자동으로 선택·노출하는 통합 광고 솔루션**이에요.\
토스 애즈가 우선적으로 노출되며, 지원되지 않는 환경에서는 AdMob으로 자동 fallback 하여 안정적인 수익을 보장해요.

**전면형(Interstitial)** 과 **보상형(Rewarded)** 광고 모두 동일 API(`loadFullScreenAd`, `showFullScreenAd`)를 사용하며, 광고 타입은 **광고 그룹 ID(`adGroupId`)** 를 기준으로 자동 결정돼요.

## 콘솔 가이드

### 테스트 광고 ID

테스트 환경에서는 아래 ID를 사용해야 해요.

::: tip 주의하세요
실제 광고 ID로 개발·테스트할 경우 **정책 위반으로 불이익**이 발생할 수 있어요.\
반드시 테스트용 ID를 사용해주세요.
:::

* 전면형 광고 : `ait-ad-test-interstitial-id`
* 리워드 광고 : `ait-ad-test-rewarded-id`

### 광고 ID 발급

콘솔의 **인앱 광고 2.0** 메뉴에서 광고 ID를 발급할 수 있어요.

::: tip 인앱 광고 2.0 ID를 이미 발급했어요
인앱 광고 2.0은 2가지 버전으로 개발할 수 있어요.\
[인앱 광고 연동하기(2.0)](/bedrock/reference/framework/광고/loadAppsInTossAdMob.md) 사용을 위해 이미 발급받은 ID가 있다면, **인앱 광고 2.0 ver2에서도 동일하게 사용할 수 있어요.**
:::

## 지원 버전

통합 광고 API는 토스 앱 버전에 따라 다르게 동작해요 :

| 토스 앱 버전               | 지원 기능          | 설명                            |
| -------------------------- | ------------------ | ------------------------------- |
| **5.241.0 이상**           | 인앱 광고 2.0 ver2 | 토스 애즈 우선 + AdMob fallback |
| **5.227.0 ~ 5.241.0 미만** | 인앱 광고 2.0      | AdMob 단독 지원                 |
| **5.227.0 미만**           | 미지원             | 인앱 광고 2.0 ver2 사용 불가    |

> `isSupported()` 메서드로 현재 환경에서 인앱 광고 2.0 ver2를 사용할 수 있는지 확인할 수 있어요.

## 광고 정책

### 토스 애즈 SSP 정책

| **유형**                  | **금지 행위**                                                 | **구체적 예시**                                                                                         |                                                                            |
| ------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **UI 조작**               | 광고·콘텐츠 구분이 불명확하거나 사용자를 오인시키는 배너 변경 | “추천 서비스”, “금융 팁” 등으로 광고를 위장, CTA 문구 임의 변경                                         | 광고는 반드시 “ad” 표기 유지, 광고 타이틀·라벨 임의 수정 금지              |
| **광고 로직 변조**        | SDK 기본 클릭·노출 로직 수정, 자동 리프레시·리디렉션 추가     | web-public에서 광고 클릭 시 별도 페이지로 강제 이동 , Back 버튼 차단 / Dead-end 구조 / ATF 첫 화면 광고 | SDK 기본 이벤트(Click / Impression) 구조 변조 금지. SDK 외부 API 호출 불가 |
| **자동화 트래픽**         | 자동 클릭·자동 새로고침 등 비정상 노출 유도                   | 광고 영역을 주기적 refresh 처리, Back 버튼 차단 / Dead-end 구조 / ATF 첫 화면 광고                      | 트래픽 조작 감지 시 SSP 로그 차단 + 정산 보류                              |
| **광고 디자인 임의 수정** | 광고 색상, 배치, CTA, 크기 등 임의 변경                       | Toss Ads 가이드 외 광고 단위의 색상·글꼴 변경                                                           | 모든 광고 UI는 **web-base 표준 컴포넌트** 사용 필수                        |
| **보상·참여형 클릭**      | 클릭 시 리워드·이벤트 제공 문구 추가                          | “광고 클릭 시 포인트 지급” / “참여하면 혜택”                                                            | 클릭 보상성 문구·이벤트 연동 금지                                          |
| **광고 은닉 또는 겹침**   | 다른 요소 위에 배너를 덮거나 숨김                             | 다른 카드 UI 뒤에 광고 DOM 삽입                                                                         | 광고는 노출 상태가 명확히 확인 가능해야 함                                 |

### UX / Product Principle 운영 원칙

| **Toss Principle**             | **적용 기준**                                                   | **예시**                                  |
| ------------------------------ | --------------------------------------------------------------- | ----------------------------------------- |
| **Simplicity**                 | 광고는 명료해야 하며, 추가 설명 없이 의미를 이해할 수 있어야 함 | “지금 보기”, “광고 보기” 등 명확 CTA 사용 |
| **Clear Action**               | 광고 클릭 후 어떤 행동이 발생할지 사용자가 예측 가능해야 함     | 리디렉션·새창 이동 시 고지 문구 노출      |
| **No Deception (UX Red Rule)** | 광고가 예상치 못한 순간, 형태, 위치에서 등장하지 않아야 함      | 서비스 진입 직후 전면 배너 금지           |
| **Value First**                | 광고는 고객의 서비스 목표를 방해하지 않아야 함                  | 결제/계좌 개설 흐름 중 광고 삽입 금지     |

***

## API 개요

* `loadFullScreenAd(params: LoadFullScreenAdParams): () => void` — 광고를 미리 로드해요. 반환값으로 콜백 등록 해제 함수(noop 형태)를 제공해요.
* `showFullScreenAd(params: ShowFullScreenAdParams): () => void` — 로드된 광고를 화면에 표시해요. 마찬가지로 해제 함수를 반환해요.

각 API는 `isSupported()` 프로퍼티를 통해 현재 환경에서 해당 기능 사용 가능 여부를 확인할 수 있어요.

***

## 광고 불러오기

### `loadFullScreenAd`

```typescript
function loadFullScreenAd(params: LoadFullScreenAdParams): () => void;
```

광고를 미리 로드해요. 광고를 표시하기 전에 반드시 호출해야 해요.

### 파라미터

### 프로퍼티

#### `isSupported`

```typescript
loadFullScreenAd.isSupported(): boolean
```

현재 환경에서 인앱 광고 2.0 ver2 광고를 사용할 수 있는지 확인해요.

### 예제

:::code-group

```tsx[React]
import { loadFullScreenAd } from '@apps-in-toss/web-framework';
import { useState, useEffect } from 'react';

function AdComponent() {
  const [isAdLoaded, setIsAdLoaded] = useState(false);

  useEffect(() => {
    // 지원 여부 확인
    if (!loadFullScreenAd.isSupported()) {
      console.warn('광고 기능을 사용할 수 없습니다.');
      return;
    }

    // 광고 로드
    const unregister = loadFullScreenAd({
      options: {
        adGroupId: 'ait.dev.43daa14da3ae487b',
      },
      onEvent: (event) => {
        if (event.type === 'loaded') {
          console.log('광고 로드 완료');
          setIsAdLoaded(true);
        }
      },
      onError: (error) => {
        console.error('광고 로드 실패:', error);
      },
    });

    // 클린업
    return () => unregister();
  }, []);

  return (
    <button disabled={!isAdLoaded}>
      {isAdLoaded ? '광고 보기' : '광고 로딩 중...'}
    </button>
  );
}
```

```tsx[React Native]
import { loadFullScreenAd } from '@apps-in-toss/framework';
import { useEffect, useState } from 'react';
import { Alert, Button, View } from 'react-native';

function AdComponent() {
  const [isAdLoaded, setIsAdLoaded] = useState(false);

  useEffect(() => {
    // 지원 여부 확인
    if (!loadFullScreenAd.isSupported()) {
      Alert.alert('광고 기능을 사용할 수 없습니다.');
      return;
    }

    // 광고 로드
    const unregister = loadFullScreenAd({
      options: {
        adGroupId: 'ait.dev.43daa14da3ae487b',
      },
      onEvent: (event) => {
        if (event.type === 'loaded') {
          Alert.alert('광고 로드 완료');
          setIsAdLoaded(true);
        }
      },
      onError: (error) => {
        Alert.alert('광고 로드 실패', String(error));
      },
    });

    // 클린업
    return () => unregister();
  }, []);

  return (
    <View>
      <Button
        title={isAdLoaded ? '광고 보기' : '광고 로딩 중...'}
        disabled={!isAdLoaded}
      />
    </View>
  );
}
```

:::

### `LoadFullScreenAdParams`

```typescript
interface LoadFullScreenAdParams {
  options: LoadFullScreenAdOptions;
  onEvent: (data: LoadFullScreenAdEvent) => void;
  onError: (err: unknown) => void;
}
```

`loadFullScreenAd`의 파라미터 타입이에요.

### `LoadFullScreenAdOptions`

```typescript
interface LoadFullScreenAdOptions {
  adGroupId: string;
}
```

광고 로드 옵션이에요.

### `LoadFullScreenAdEvent`

```typescript
interface LoadFullScreenAdEvent {
  type: 'loaded';
}
```

광고 로드 이벤트예요. 광고가 성공적으로 로드되면 `loaded` 타입 이벤트가 발생해요.

***

## 광고 보여주기

### `showFullScreenAd`

```typescript
function showFullScreenAd(params: ShowFullScreenAdParams): () => void;
```

로드된 광고를 화면에 표시해요. `loadFullScreenAd`로 미리 로드한 광고를 사용해주세요.

### 파라미터

### 프로퍼티

#### `isSupported`

```typescript
showFullScreenAd.isSupported(): boolean
```

현재 환경에서 통합 광고를 사용할 수 있는지 확인해요.

### 예제

:::code-group

```tsx[React]
import { loadFullScreenAd, showFullScreenAd } from '@apps-in-toss/web-framework';
import { useState, useEffect } from 'react';

function AdComponent() {
  const AD_GROUP_ID = 'ait.dev.43daa14da3ae487b';
  const [isAdLoaded, setIsAdLoaded] = useState(false);

  useEffect(() => {
    // 컴포넌트 마운트 시 광고 로드
    const unregister = loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') {
          setIsAdLoaded(true);
        }
      },
      onError: (error) => {
        console.error('광고 로드 실패:', error);
      },
    });

    return () => unregister();
  }, []);

  const handleShowAd = () => {
    showFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 표시 요청됨');
            break;
          case 'show':
            console.log('광고 화면 표시됨');
            break;
          case 'impression':
            console.log('광고 노출 기록됨 (수익 발생)');
            break;
          case 'clicked':
            console.log('광고 클릭됨');
            break;
          case 'dismissed':
            console.log('광고가 닫힘');
            setIsAdLoaded(false);
            // 다음 광고 로드
            loadNextAd();
            break;
          case 'failedToShow':
            console.error('광고 표시 실패');
            break;
          case 'userEarnedReward':
            console.log('리워드 획득:', event.data);
            // 사용자에게 리워드 지급
            grantReward(event.data.unitType, event.data.unitAmount);
            break;
        }
      },
      onError: (error) => {
        console.error('광고 표시 실패:', error);
      },
    });
  };

  const loadNextAd = () => {
    loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') setIsAdLoaded(true);
      },
      onError: console.error,
    });
  };

  const grantReward = (unitType: string, unitAmount: number) => {
    // 리워드 지급 로직
    console.log(`${unitType} ${unitAmount}개 지급`);
  };

  return (
    <button onClick={handleShowAd} disabled={!isAdLoaded}>
      광고 보기
    </button>
  );
}
```

```tsx[React Native]
import { loadFullScreenAd, showFullScreenAd } from '@apps-in-toss/framework';
import { useEffect, useState } from 'react';
import { Alert, Button, View } from 'react-native';

function AdComponent() {
  const AD_GROUP_ID = 'ait.dev.43daa14da3ae487b';
  const [isAdLoaded, setIsAdLoaded] = useState(false);

  useEffect(() => {
    // 컴포넌트 마운트 시 광고 로드
    const unregister = loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') {
          setIsAdLoaded(true);
        }
      },
      onError: (error) => {
        Alert.alert('광고 로드 실패', String(error));
      },
    });

    return () => unregister();
  }, []);

  const handleShowAd = () => {
    showFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 표시 요청됨');
            break;
          case 'show':
            console.log('광고 화면 표시됨');
            break;
          case 'impression':
            console.log('광고 노출 기록됨 (수익 발생)');
            break;
          case 'clicked':
            console.log('광고 클릭됨');
            break;
          case 'dismissed':
            setIsAdLoaded(false);
            loadNextAd();
            break;
          case 'failedToShow':
            Alert.alert('광고 표시 실패');
            break;
          case 'userEarnedReward':
            console.log('리워드 획득:', event.data);
            grantReward(event.data.unitType, event.data.unitAmount);
            break;
        }
      },
      onError: (error) => {
        Alert.alert('광고 표시 실패', String(error));
      },
    });
  };

  const loadNextAd = () => {
    loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') setIsAdLoaded(true);
      },
      onError: (error) => Alert.alert('오류', String(error)),
    });
  };

  const grantReward = (unitType: string, unitAmount: number) => {
    Alert.alert('리워드 획득', `${unitType} ${unitAmount}개가 지급되었습니다.`);
  };

  return (
    <View>
      <Button title="광고 보기" onPress={handleShowAd} disabled={!isAdLoaded} />
    </View>
  );
}
```

:::

### `ShowFullScreenAdParams`

```typescript
interface ShowFullScreenAdParams {
  options: ShowFullScreenAdOptions;
  onEvent: (data: ShowFullScreenAdEvent) => void;
  onError: (err: unknown) => void;
}
```

`showFullScreenAd`의 파라미터 타입이에요.

### `ShowFullScreenAdOptions`

```typescript
interface ShowFullScreenAdOptions {
  adGroupId: string;
}
```

광고 보여주기 옵션이에요.

### `ShowFullScreenAdEvent`

```typescript
type ShowFullScreenAdEvent =
  | { type: 'requested' }
  | { type: 'show' }
  | { type: 'impression' }
  | { type: 'clicked' }
  | { type: 'dismissed' }
  | { type: 'failedToShow' }
  | { type: 'userEarnedReward'; data: { unitType: string; unitAmount: number } };
```

광고 보여주기 이벤트예요.

#### 이벤트 설명

| 이벤트 타입        | 설명                                                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `requested`        | 광고 표시 요청이 성공했어요.                                                                                                        |
| `show`             | 광고가 화면에 표시되었어요.                                                                                                         |
| `impression`       | 광고 노출이 기록되었어요. (수익 발생 시점)                                                                                          |
| `clicked`          | 사용자가 광고를 클릭했어요.                                                                                                         |
| `dismissed`        | 사용자가 광고를 닫았어요.                                                                                                           |
| `failedToShow`     | 광고 표시에 실패했어요.                                                                                                             |
| `userEarnedReward` | 리워드 광고에서 사용자가 보상을 획득했어요.• `data.unitType`: 리워드 타입 (예: coin, point)• `data.unitAmount`: 리워드 수량 |

***

## 사용 가이드

### 광고 로드 타이밍

광고는 표시하기 전에 미리 로드하는 것을 권장합니다.

* 로드 타이밍 권장 목록
  * 컴포넌트 마운트 시
  * 이전 광고가 닫힌 직후
  * 광고를 표시할 화면으로 전환되기 전

```tsx
// ✅ 좋은 예: 화면 진입 시 미리 로드
useEffect(() => {
  loadFullScreenAd({
    /* ... */
  });
}, []);

// ❌ 나쁜 예: 버튼 클릭 시 로드 (사용자 대기 시간 발생)
const handleClick = () => {
  loadFullScreenAd({
    /* ... */
  }); // 로딩 시간 발생
  showFullScreenAd({
    /* ... */
  });
};
```

### 리워드 광고 처리

`userEarnedReward` 이벤트가 발생했을 때만 리워드를 지급하세요. `dismissed`만으로는 지급하면 안돼요.

```tsx
showFullScreenAd({
  options: { adGroupId: REWARDED_AD_ID },
  onEvent: (event) => {
    if (event.type === 'userEarnedReward') {
      // ✅ 리워드 지급
      grantReward(event.data);
    }

    if (event.type === 'dismissed') {
      // ❌ dismissed만으로는 리워드 지급하지 않음
    }
  },
  onError: console.error,
});
```

### 메모리 관리

컴포넌트 언마운트 시 콜백 등록을 해제하여 메모리 누수를 방지하세요.

```tsx
useEffect(() => {
  const unregister = loadFullScreenAd({
    /* ... */
  });

  return () => {
    unregister(); // 클린업
  };
}, []);
```

### 에러 처리

항상 `onError` 콜백을 제공하여 광고 로드/표시 실패에 대비하세요.

```tsx
loadFullScreenAd({
  options: { adGroupId: AD_GROUP_ID },
  onEvent: (event) => {
    /* ... */
  },
  onError: (error) => {
    console.error('광고 로드 실패:', error);
    // 사용자에게 적절한 피드백 제공 또는 재시도
  },
});
```

***

## 이벤트 플로우

:::code-group

```[전면 광고 (Interstitial)]
loadFullScreenAd 호출
  ↓
loaded 이벤트 발생
  ↓
showFullScreenAd 호출
  ↓
requested 이벤트 발생
  ↓
show 이벤트 발생 (광고 화면 표시)
  ↓
impression 이벤트 발생 (수익 발생)
  ↓
clicked 이벤트 (클릭 시) 또는 dismissed 이벤트 (닫기 시)
```

```[리워드 광고 (Rewarded)]
loadFullScreenAd 호출
  ↓
loaded 이벤트 발생
  ↓
showFullScreenAd 호출
  ↓
requested 이벤트 발생
  ↓
show 이벤트 발생 (광고 화면 표시)
  ↓
impression 이벤트 발생 (수익 발생)
  ↓
[사용자가 광고 시청 완료]
  ↓
userEarnedReward 이벤트 발생 (리워드 지급)
  ↓
dismissed 이벤트 발생 (광고 닫기)
```

:::

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: ""This feature is not supported in the current environment" 에러가 발생해요",
a: \`1. 토스 앱 환경에서 실행 중인지 확인해주세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/GoogleAdMob.md
---

# 인앱 광고 공통 타입·객체

## `GoogleAdMob`

`GoogleAdMob`는 Google AdMob 광고 관련 함수를 모아둔 객체예요.

### 시그니처

```typescript
GoogleAdMob: {
    /**
     * @deprecated 곧 제거될 예정이에요. 대신 `loadAppsInTossAdMob`을 사용해주세요.
     */
    loadAdMobInterstitialAd: typeof loadAdMobInterstitialAd;

    /**
     * @deprecated 곧 제거될 예정이에요. 대신 `showAppsInTossAdMob`을 사용해주세요.
     */
    showAdMobInterstitialAd: typeof showAdMobInterstitialAd;

    /**
     * @deprecated 곧 제거될 예정이에요. 대신 `loadAppsInTossAdMob`을 사용해주세요.
     */
    loadAdMobRewardedAd: typeof loadAdMobRewardedAd;

    /**
     * @deprecated 곧 제거될 예정이에요. 대신 `showAppsInTossAdMob`을 사용해주세요.
     */
    showAdMobRewardedAd: typeof showAdMobRewardedAd;

    loadAppsInTossAdMob: typeof loadAppsInTossAdMob;
    showAppsInTossAdMob: typeof showAppsInTossAdMob;
}
```

### 프로퍼티

## `AdMobFullScreenEvent`

`AdMobFullScreenEvent`는 앱 화면을 덮는 광고(예: 전면 광고, 보상형 광고)를 사용하는 경우에 발생하는 이벤트 타입이에요.

### 시그니처

```typescript
type AdMobFullScreenEvent = AdClicked | AdDismissed | AdFailedToShow | AdImpression | AdShow;
```

### 예제

광고 이벤트 처리하기

```ts
function handleEvent(event: AdMobFullScreenEvent) {
  switch (event.type) {
    case 'clicked':
      console.log('광고가 클릭됐어요.');
      break;

    case 'dismissed':
      console.log('광고가 닫혔어요.');
      break;

    case 'failedToShow':
      console.log('광고가 보여지지 않았어요.');
      break;

    case 'impression':
      console.log('광고가 노출됐어요.');
      break;

    case 'show':
      console.log('광고가 보여졌어요.');
      break;
  }
}
```

## `AdNetworkResponseInfo`

`AdNetworkResponseInfo` 는 광고 네트워크 응답 정보를 담고 있는 객체예요.

### 시그니처

```typescript
interface AdNetworkResponseInfo {
  adSourceId: string;
  adSourceName: string;
  adSourceInstanceId: string;
  adSourceInstanceName: string;
  adNetworkClassName: string | null;
}
```

### 프로퍼티

## `AdNetworkResponseInfo`

`AdNetworkResponseInfo` 는 광고 네트워크 응답 정보를 담고 있는 객체예요.

### 시그니처

```typescript
interface AdNetworkResponseInfo {
  adSourceId: string;
  adSourceName: string;
  adSourceInstanceId: string;
  adSourceInstanceName: string;
  adNetworkClassName: string | null;
}
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/loadAdMobInterstitialAd.md
---

# 인앱 광고(v1.0)

## `loadAdMobInterstitialAd`

> ⚠️ **Deprecated**\
> 이 함수는 곧 제거될 예정이에요. 대신 [`loadAppsInTossAdMob`](./loadAppsInTossAdMob.html)을 사용해주세요.

`loadAdMobInterstitialAd` 는 앱 화면 전체를 덮는 전면 광고를 미리 불러와서, 광고가 필요한 시점에 바로 보여줄 수 있도록 준비하는 함수예요.

### 시그니처

```typescript
function loadAdMobInterstitialAd(params: LoadAdMobInterstitialAdParams): typeof noop;
```

### 파라미터

### 프로퍼티

### 예제

버튼 눌러 불러온 전면 광고 보여주기

::: code-group

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useCallback, useEffect, useState } from 'react';

const AD_UNIT_ID = '<AD_UNIT_ID>';

export default function GoogleAdmobInterstitialAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
        setAdLoadStatus('failed');
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  useEffect(() => {
    const cleanup = loadAd();
    return cleanup;
  }, [loadAd]);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button size="medium" onClick={showAd} disabled={adLoadStatus !== 'loaded'}>Show Ad</Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useFocusEffect } from '@granite-js/native/@react-navigation/native';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';
import { useNavigation } from '@granite-js/react-native';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobInterstitialAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
  const navigation = useNavigation();

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            navigation.navigate('/examples/google-admob-interstitial-ad-landing');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, [navigation]);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  useFocusEffect(loadAd);

  return (
    <View>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-interstitial-ad](https://github.com/toss/apps-in-toss-examples/tree/main/with-interstitial-ad) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

## `LoadAdMobInterstitialAdParams`

`LoadAdMobInterstitialAdParams` 는 전면 광고를 불러오는 함수에 필요한 옵션 객체예요.

### 시그니처

```typescript
type LoadAdMobInterstitialAdParams = AdMobHandlerParams<LoadAdMobInterstitialAdOptions, LoadAdMobInterstitialAdEvent>;
```

## `LoadAdMobInterstitialAdEvent`

`LoadAdMobInterstitialAdEvent` 는 전면 광고를 불러오는 함수에서 발생하는 이벤트 타입이에요. `loaded` 이벤트가 발생하면 광고를 성공적으로 불러온 거예요. 이때 [InterstitialAd](/bedrock/reference/framework/광고/InterstitialAd) 객체가 함께 반환돼요.

### 시그니처

```typescript
type LoadAdMobInterstitialAdEvent = AdMobFullScreenEvent | {
  type: 'loaded';
  data: InterstitialAd;
};
```

## `InterstitialAd`

`InterstitialAd` 는 전면 광고의 ID와 응답 정보를 담고 있는 객체예요. 광고를 로드한 뒤, 관련 정보를 확인할 때 유용해요.

### 시그니처

```typescript
interface InterstitialAd {
  adUnitId: string;
  responseInfo: ResponseInfo;
}
```

### 프로퍼티

## `showAdMobInterstitialAd`

> ⚠️ **Deprecated**\
> 이 함수는 곧 제거될 예정이에요. 대신 [`showAppsInTossAdMob`](./showAppsInTossAdMob.html)을 사용해주세요.

`showAdMobInterstitialAd` 함수는 앱 화면 전체를 덮는 전면 광고를 사용자에게 노출해요. 이 함수는 `loadAdMobInterstitialAd` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.

### 시그니처

```typescript
function showAdMobInterstitialAd(params: ShowAdMobInterstitialAdParams): typeof noop;
```

### 파라미터

### 프로퍼티

### 예제

버튼 눌러 불러온 전면 광고 보여주기

::: code-group

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text, View } from '@toss/tds-mobile';
import { useCallback, useEffect, useState } from 'react';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobInterstitialAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
  const navigate = useNavigate();

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            navigate({ to: '/' });
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, [navigation]);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  useEffect(() => {
    const cleanup = loadAd();
    return cleanup;
  }, [loadAd]);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button size="medium" onClick={showAd} disabled={adLoadStatus !== 'loaded'}>Show Ad</Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useFocusEffect } from '@granite-js/native/@react-navigation/native';
import { Button, Text } from "@toss/tds-react-native";
import { useCallback, useState } from 'react';
import { View } from 'react-native';
import { useNavigation } from '@granite-js/react-native';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobInterstitialAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
  const navigation = useNavigation();

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            navigation.navigate('/examples/google-admob-interstitial-ad-landing');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, [navigation]);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobInterstitialAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobInterstitialAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  useFocusEffect(loadAd);

  return (
    <View>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button onPress={showAd} disabled={adLoadStatus !== 'loaded'}>Show Ad</Button>
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-interstitial-ad](https://github.com/toss/apps-in-toss-examples/tree/main/with-interstitial-ad) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

## `ShowAdMobInterstitialAdParams`

`ShowAdMobInterstitialAdParams`는 불러온 전면 광고를 보여주는 함수에 필요한 옵션 객체예요.

### 시그니처

```typescript
type ShowAdMobInterstitialAdParams = AdMobHandlerParams<ShowAdMobInterstitialAdOptions, ShowAdMobInterstitialAdEvent>;
```

## `ShowAdMobInterstitialAdEvent`

`ShowAdMobInterstitialAdEvent` 는 전면 광고를 보여주는 함수에서 발생하는 이벤트 타입이에요. `requested` 이벤트가 발생하면 광고 노출 요청이 Google AdMob에 성공적으로 전달된 거예요.

### 시그니처

```typescript
type ShowAdMobInterstitialAdEvent = {
  type: 'requested';
};
```

## `loadAdMobRewardedAd`

> ⚠️ **Deprecated**\
> 이 함수는 곧 제거될 예정이에요. 대신 [`loadAppsInTossAdMob`](./loadAppsInTossAdMob.html)을 사용해주세요.

`loadAdMobRewardedAd` 는 사용자가 광고를 끝까지 시청하면 리워드를 제공할 수 있는 보상형 광고를 미리 불러와서, 광고가 필요한 시점에 바로 보여줄 수 있도록 준비하는 함수예요.

### 시그니처

```typescript
function loadAdMobRewardedAd(params: LoadAdMobRewardedAdParams): typeof noop;
```

### 파라미터

### 프로퍼티

### 예제

버튼 눌러 불러온 보상형 광고 보여주기

::: code-group

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useCallback, useState } from 'react';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobRewardedAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;

          case 'userEarnedReward':
            console.log('사용자가 광고 시청을 완료했음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onClick={loadAd}>
        광고 로드
      </Button>
      <Button title="Show Ad" onClick={showAd} disabled={adLoadStatus !== 'loaded'}>
        광고 보여주기
      </Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobRewardedAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;

          case 'userEarnedReward':
            console.log('사용자가 광고 시청을 완료했음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <View>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onPress={loadAd} />
      <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-rewarded-ad](https://github.com/toss/apps-in-toss-examples/tree/main/with-rewarded-ad) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

## `LoadAdMobRewardedAdParams`

`LoadAdMobRewardedAdParams` 는 보상형 광고를 불러오는 함수에 필요한 옵션 객체예요.

### 시그니처

```typescript
type LoadAdMobRewardedAdParams = AdMobHandlerParams<LoadAdMobRewardedAdOptions, LoadAdMobRewardedAdEvent>;
```

## `LoadAdMobRewardedAdEvent`

`LoadAdMobRewardedAdEvent` 는 보상형 광고를 불러오는 함수에서 발생하는 이벤트 타입이에요. `loaded` 이벤트가 발생하면 광고를 성공적으로 불러온 거예요. 이때 [RewardedAd](/bedrock/reference/framework/광고/RewardedAd) 객체가 함께 반환돼요. `userEarnedReward` 이벤트는 사용자가 광고를 끝까지 시청해, 보상 조건을 충족했을 때 발생해요.

### 시그니처

```typescript
type LoadAdMobRewardedAdEvent = AdMobFullScreenEvent | {
  type: 'loaded';
  data: RewardedAd;
} | {
  type: 'userEarnedReward';
};
```

## `RewardedAd`

`RewardedAd` 는 보상형 광고의 ID와 응답 정보를 담고 있는 객체예요. 광고를 로드한 뒤, 관련 정보를 확인할 때 유용해요.

### 시그니처

```typescript
interface RewardedAd {
  adUnitId: string;
  responseInfo: ResponseInfo;
}
```

### 프로퍼티

## `showAdMobRewardedAd`

> ⚠️ **Deprecated**\
> 이 함수는 곧 제거될 예정이에요. 대신 [`showAppsInTossAdMob`](./showAppsInTossAdMob.html)을 사용해주세요.

`showAdMobRewardedAd` 함수는 사용자가 광고를 끝까지 보면 리워드를 받을 수 있도록, 보상형 광고를 화면에 보여줘요. 이 함수는 `loadAdMobRewardedAd` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.

### 시그니처

```typescript
function showAdMobRewardedAd(params: ShowAdMobRewardedAdParams): typeof noop;
```

### 파라미터

### 프로퍼티

### 예제

버튼 눌러 불러온 보상형 광고 보여주기

::: code-group

```tsx [React]
import { GoogleAdMob } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useCallback, useState } from 'react';

const AD_UNIT_ID = '<AD_UNIT_ID>';

export default function GoogleAdmobRewardedAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;

          case 'userEarnedReward':
            console.log('사용자가 광고 시청을 완료했음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <div>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onClick={loadAd}>
        광고 로드
      </Button>
      <Button title="Show Ad" onClick={showAd} disabled={adLoadStatus !== 'loaded'}>
        광고 보여주기
      </Button>
    </div>
  );
}
```

```tsx [React Native]
import { GoogleAdMob } from '@apps-in-toss/framework';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';

const AD_UNIT_ID = '<AD_UNIT_ID>';

function GoogleAdmobRewardedAdExample() {
  const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');

  const loadAd = useCallback(() => {
    if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    const cleanup = GoogleAdMob.loadAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        console.log(event.type);
        switch (event.type) {
          case 'loaded':
            console.log('광고 로드 성공', event.data);
            setAdLoadStatus('loaded');
            break;

          case 'clicked':
            console.log('광고 클릭');
            break;

          case 'dismissed':
            console.log('광고 닫힘');
            break;

          case 'failedToShow':
            console.log('광고 보여주기 실패');
            break;

          case 'impression':
            console.log('광고 노출');
            break;

          case 'show':
            console.log('광고 컨텐츠 보여졌음');
            break;

          case 'userEarnedReward':
            console.log('사용자가 광고 시청을 완료했음');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 불러오기 실패', error);
      },
    });

    return cleanup;
  }, []);

  const showAd = useCallback(() => {
    if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
      return;
    }

    GoogleAdMob.showAdMobRewardedAd({
      options: {
        adUnitId: AD_UNIT_ID,
      },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('광고 보여주기 요청 완료');
            setAdLoadStatus('not_loaded');
            break;
        }
      },
      onError: (error) => {
        console.error('광고 보여주기 실패', error);
      },
    });
  }, []);

  return (
    <View>
      <Text>
        {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
        {adLoadStatus === 'loaded' && '광고 로드 완료'}
        {adLoadStatus === 'failed' && '광고 로드 실패'}
      </Text>

      <Button title="Load Ad" onPress={loadAd} />
      <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-rewarded-ad](https://github.com/toss/apps-in-toss-examples/tree/main/with-rewarded-ad) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

## `ShowAdMobRewardedAdParams`

`ShowAdMobRewardedAdParams` 는 불러온 보상형 광고를 보여주는 함수에 필요한 옵션 객체예요.

### 시그니처

```typescript
type ShowAdMobRewardedAdParams = AdMobHandlerParams<ShowAdMobRewardedAdOptions, ShowAdMobRewardedAdEvent>;
```

## `ShowAdMobRewardedAdEvent`

`ShowAdMobRewardedAdEvent` 는 보상형 광고를 보여주는 함수에서 발생하는 이벤트 타입이에요. `requested` 이벤트가 발생하면 광고 노출 요청이 Google AdMob에 성공적으로 전달된 거예요.

### 시그니처

```typescript
type ShowAdMobRewardedAdEvent = {
  type: 'requested';
};
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인증/tosscertRequest.md
---

# 인증 화면 호출

본인확인 요청 API 응답에서 받은 `txId`를 포함해 `appsInTossSignTossCert`를 호출해요.

::: tip 원터치 인증 및 앱 버전 안내
**원터치 인증 방식(`USER_NONE`)** 을 사용하는 경우,\
`skipConfirmDoc`을 `true`로 설정하면 인증서 확인 문서 단계를 건너뛸 수 있어요.

* 토스 인증(requestType: USER\_PERSONAL): 토스앱 5.233.0 이상
* 토스 원터치 인증(requestType: USER\_NONE): 토스앱 5.236.0 이상

[getTossAppVersion](/bedrock/reference/framework/환경%20확인/getTossAppVersion) 함수를 사용하여 토스앱 버전을 체크해보세요.
:::

:::code-group

```js [js]
import { appsInTossSignTossCert } from '@apps-in-toss/web-framework';

/**
 * Toss 인증서 화면을 txId 기반으로 호출합니다.
 *
 * 참고:
 * response는 인증 완료 확정 용도가 아닙니다.
 * 서버에서 txId 기준으로 결과조회 API를 호출해 최종 상태를 판별하세요.
 */
async function openTossCertWithTxId({ txId, skipConfirmDoc = false }) {
  try {
    const params: AppsInTossSignTossCertParams = { txId, skipConfirmDoc };
    const response = await appsInTossSignTossCert(params);
    return response;
  } catch (error) {
    // 호출 실패 처리 (사용자 취소/앱 미설치/스킴 실패 등)
    console.error(error)
  }
}
```

```tsx [React]
import { appsInTossSignTossCert } from '@apps-in-toss/web-framework';

interface AppsInTossSignTossCertParams {
  txId: string; // 본인확인 요청 시 발급받은 txId
  skipConfirmDoc?: boolean; // 원터치 인증 시 true로 설정
}

/**
 * Toss 인증서 화면을 txId 기반으로 호출합니다.
 *
 * 참고:
 * response는 인증 완료 확정 용도가 아닙니다.
 * 서버에서 txId 기준으로 결과조회 API를 호출해 최종 상태를 판별하세요.
 */
async function openTossCertWithTxId(
  txId: string,
  skipConfirmDoc = false
): Promise<unknown> {
  try {
    const params: AppsInTossSignTossCertParams = { txId, skipConfirmDoc };
    const response = await appsInTossSignTossCert(params);
    return response;
  } catch (error: unknown) {
    // 호출 실패 처리 (사용자 취소/앱 미설치/스킴 실패 등)
    console.error(error)
  }
}

```

```tsx [React Native]
import { appsInTossSignTossCert } from '@apps-in-toss/framework';

interface AppsInTossSignTossCertParams {
  txId: string; // 본인확인 요청 시 발급받은 txId
  skipConfirmDoc?: boolean; // 원터치 인증 시 true로 설정
}

/**
 * Toss 인증서 화면을 txId 기반으로 호출합니다.
 *
 * 참고:
 * response는 인증 완료 확정 용도가 아닙니다.
 * 서버에서 txId 기준으로 결과조회 API를 호출해 최종 상태를 판별하세요.
 */
async function openTossCertWithTxId(
  txId: string,
  skipConfirmDoc = false
): Promise<unknown> {
  try {
    const params: AppsInTossSignTossCertParams = { txId, skipConfirmDoc };
    const response = await appsInTossSignTossCert(params);
    return response;
  } catch (error: unknown) {
    // 호출 실패 처리 (사용자 취소/앱 미설치/스킴 실패 등)
    console.error(error)
  }
}

```

:::

***

### 응답

* `onSuccess`
  * 파라미터 없음
* `onError`
  * `Error { code: string; message: string }` (예: 사용자 취소, 앱 미설치, 스킴 실패 등)

```ts
// 에러 타입 예시
type AppsInTossSignTossCertError = {
  code: string;
  message: string;
};

// try/catch로 onSuccess/onError 대응하기
try {
  await appsInTossSignTossCert({
    params: {
      txId: "bb8bead6-0957-4be7-b937-f554911d7a87",
      skipConfirmDoc: true, // 원터치 인증 시 설정
    },
  });
  // onSuccess: 파라미터 없음
} catch (e: any) {
  const err: AppsInTossSignTossCertError = {
    code: e?.code ?? 'UNKNOWN',
    message: e?.message ?? String(e),
  };
  // onError: 에러 처리
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/checklist/miniapp-external-link.md'
description: '앱인토스 미니앱의 자사 앱 설치 유도 및 외부 링크 이동 제한 정책입니다. 제한되는 행위, 허용되는 경우, 위반 시 조치 사항을 확인하세요.'
---

# 자사 앱 설치/외부 링크 가이드라인

앱인토스 서비스는 자사 앱 설치 유도와 외부 링크 이동에 대해 제한하고 있어요.\
아래 가이드라인을 따르지 않은 경우, 서비스 운영에 대한 제재를 받을 수 있어요.

## 1. 자사 앱 설치를 유도할 수 없어요.

‘자사 앱 설치 유도’란, 사용자가 현재 이용 중인 서비스 및 미니앱 외에 특정 모바일 애플리케이션을 설치하도록 유도하거나 권유하는 행위를 의미해요.

예를 들어, 서비스 이용을 위해 추가 앱 설치가 필요하다고 안내하거나, 앱 설치 시 혜택을 제공하겠다고 강조하는 경우가 이에 해당해요.

*\[예시]*

* “앱을 설치하시면 더 많은 기능을 이용할 수 있어요.”
* “전용 쿠폰을 받으시려면 자사 앱을 설치하세요.”
* “앱 다운로드하고 첫 구매하면 할인 받을 수 있어요.”

앱인토스 미니앱은 “앱 설치 없는 간편한 서비스 이용”을 핵심 가치로 삼는 플랫폼이에요.

미니앱은 토스 앱 내에서 모든 서비스가 원활하게 작동해야 하며, 외부 앱 설치를 유도하는 콘텐츠는 사용자 경험을 해치고 플랫폼의 일관성을 저해할 수 있어요.

또한, 외부 앱 설치를 통해 개인정보 수집, 마케팅 유도 등 토스 플랫폼 밖에서 사용자 행동을 유도하는 경우, 보안과 신뢰성 문제로 이어질 수 있기 때문에 엄격히 관리돼요.

### &#x20;이런 행위는 제한돼요.

다음과 같은 형태는 운영 가이드 위반으로 간주될 수 있으며, 콘텐츠 노출 제한 또는 서비스 이용 제재로 이어질 수 있어요.

* **앱 설치를 직접적으로 유도하는 문구**&#x20;
* **앱 설치를 유도하는 이미지 또는 배너 삽입**
* **앱 마켓 링크 삽입**
* **자사 앱 설치와 관련된 혜택 안내**
* **그 외 자사 앱 설치 유도로 판단될 수 있는 콘텐츠 및 기능**

## 2. 외부 링크는 허용되는 경우에만 사용할 수 있어요.

‘외부 링크 이동’란, 사용자가 현재 이용 중인 토스 미니앱 환경을 벗어나 외부 웹사이트나 앱 등으로 이동하게 만드는 행위를 말해요.

서비스 본질과 직접적인 관련이 없는 외부 결제창, 앱 다운로드 페이지, 자사 웹사이트, 홍보용 랜딩페이지 등으로 연결되는 경우를 모두 포함해요.

*\[예시]*

* “자세한 내용은 홈페이지에서 확인하세요.”
* “이동 후 결제를 완료해주세요.”
* “외부 웹사이트에서 가입을 진행해주세요.”

사용자가 별도 앱이나 브라우저를 통해 서비스를 이어가야 한다면, 서비스의 신뢰도와 편의성 모두 저하될 수 있어요.

또한, 외부 환경으로의 이탈은 개인정보 보호, 보안, 추적 불가한 사용 형태 등 다양한 플랫폼 통제 외 영역으로 벗어나게 되는 문제를 일으킬 수 있기 때문에, 외부 링크 이동은 필요한 경우에 한해서 제한적으로 허용돼요.

### &#x20;이런 행위는 제한돼요.

다음과 같은 경우는 운영 가이드 위반으로 간주될 수 있으며, 콘텐츠 비노출 또는 서비스 이용 제재로 이어질 수 있어요.

* **앱 내 기능으로 등록한 서비스를 미니앱 내에서 모두 경험할 수 없는 형태**
* **외부 결제창으로의 이동**
* **앱 다운로드 페이지 또는 설치를 위한 외부 페이지 연결**
* **공유하기 기능의 링크가 자사 웹사이트로 랜딩되는 상태**
* **미니앱의 주요 기능이나 흐름을 외부 링크에 의존하는 구조**
* **그 외 주요 기능이 외부 링크에서 실행되도록 설계된 경우**

### &#x20;이런 경우는 허용될 수 있어요.

* **법률상 고지 및 필수 안내 목적의 외부 링크**
* **공공기관 또는 제휴기관의 공식 페이지 연결**
* **단순 정보 확인을 위해 자사가 아닌, 타사의 웹사이트로 이동**
* **미니앱 기능 내에서 완결되지 않는 일부 특수 상황**
  * 각 제품을 소개 및 추천하고, 최저가로 구매할 수 있는 플랫폼으로 이동하는 서비스
  * 혜택을 제공하기 위해 각 쿠폰을 발급하는 플랫폼으로 이동하는 서비스

### &#x20;기존 앱 서비스의 모든 내용이 미니앱에 들어가야 하나요?

기존 앱의 모든 서비스를 앱인토스 미니앱으로 기능화하지 않아도 돼요.

기능을 최소화하더라도 콘솔에서 설정한 '앱 내 기능'의 기능을 미니앱 내에서 모두 경험할 수 있으면 돼요.

* “~ 견적내기”의 기능이라면, 미니앱 내에서 완결성 있게 견적을 낼 수 있으면 돼요.
* “~ 견적내고 결제하기”의 기능이라면, 미니앱 내에서 견적부터 결제까지 진행할 수 있어야 해요.
* “~ 견적내기”의 기능으로 먼저 출시를 하고, 추후에 “~ 견적내고 결제하기”의 기능을 업데이트 해도 무관해요.

## 3. 위반 시 서비스 운영에 대한 제재가 있을 수 있어요.

자사 앱 설치 유도와 허용되지 않는 외부 링크 이동과 관련된 운영 가이드 위반이 확인될 경우, 다음과 같은 조치가 적용될 수 있어요.

* 관련 내용 고지 및 콘텐츠 수정 요청
* 토스 앱 내 미노출 처리
* 반복 위반 시 미니앱 서비스 등록 또는 운영 제한

---

---
url: 'https://developers-apps-in-toss.toss.im/faq.md'
description: >-
  앱인토스 및 Granite 기반 미니앱 개발과 운영에 관한 자주 묻는 질문과 답변을 확인하세요. 콘솔, 디자인, 개발, API, 결제,
  마케팅 등 주요 주제별로 정리되어 있습니다.
---

# 자주 묻는 질문

앱인토스 및 Granite 기반 미니앱을 개발하고 운영하면서 자주 묻는 질문들을 한 곳에서 확인하세요.

***

## 이해하기

\<FaqAccordion :items="\[
{
q: '앱인토스(Apps in Toss)는 어떤 서비스인가요?',
a: \`앱인토스는 파트너사가 개발한 서비스를 토스 앱 안에서 ‘앱인앱(App-in-App)’ 형태로 노출할 수 있게 하는 플랫폼이에요.

## 콘솔 및 앱 등록

\<FaqAccordion :items="\[
{
q: '앱 등록 전 필요한 준비사항은 무엇인가요?',
a: \`사업자 등록 및 토스 비즈니스 회원 인증이 필요해요.

## 디자인

## Granite

\<FaqAccordion :items='\[
{
q: "Granite는 무엇인가요?",
a: \`Granite는 React Native 기반의 앱인토스 전용 개발 프레임워크예요.

## 개발 및 테스트

## API / 보안 / 로그인

## 데이터 분석

## 결제 / 수익화

## 마케팅 / 프로모션

## 정산 / 세금

## 운영 / 지원 / 보안

## 홍보 / 브랜드 가이드

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/InterstitialAd.md
---

# 전면 광고 로드 응답 객체

## `InterstitialAd`

`InterstitialAd` 는 전면 광고의 ID와 응답 정보를 담고 있는 객체예요. 광고를 로드한 뒤, 관련 정보를 확인할 때 유용해요.

## 시그니처

```typescript
interface InterstitialAd {
  adUnitId: string;
  responseInfo: ResponseInfo;
}
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/LoadAdMobInterstitialAdParams.md
---

# 전면 광고 옵션 객체

## `LoadAdMobInterstitialAdParams`

`LoadAdMobInterstitialAdParams` 는 전면 광고를 불러오는 함수에 필요한 옵션 객체예요.

## 시그니처

```typescript
type LoadAdMobInterstitialAdParams = AdMobHandlerParams<LoadAdMobInterstitialAdOptions, LoadAdMobInterstitialAdEvent>;
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/ShowAdMobInterstitialAdParams.md
---

# 전면 광고 옵션 객체

## `ShowAdMobInterstitialAdParams`

`ShowAdMobInterstitialAdParams`는 불러온 전면 광고를 보여주는 함수에 필요한 옵션 객체예요.

## 시그니처

```typescript
type ShowAdMobInterstitialAdParams = AdMobHandlerParams<ShowAdMobInterstitialAdOptions, ShowAdMobInterstitialAdEvent>;
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/LoadAdMobInterstitialAdEvent.md
---

# 전면 광고 이벤트 타입

## `LoadAdMobInterstitialAdEvent`

`LoadAdMobInterstitialAdEvent` 는 전면 광고를 불러오는 함수에서 발생하는 이벤트 타입이에요. `loaded` 이벤트가 발생하면 광고를 성공적으로 불러온 거예요. 이때 [InterstitialAd](/bedrock/reference/framework/광고/InterstitialAd) 객체가 함께 반환돼요.

## 시그니처

```typescript
type LoadAdMobInterstitialAdEvent = AdMobFullScreenEvent | {
  type: 'loaded';
  data: InterstitialAd;
};
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/광고/ShowAdMobInterstitialAdEvent.md
---

# 전면 광고 이벤트 타입

## `ShowAdMobInterstitialAdEvent`

`ShowAdMobInterstitialAdEvent` 는 전면 광고를 보여주는 함수에서 발생하는 이벤트 타입이에요. `requested` 이벤트가 발생하면 광고 노출 요청이 Google AdMob에 성공적으로 전달된 거예요.

## 시그니처

```typescript
type ShowAdMobInterstitialAdEvent = {
  type: 'requested';
};
```

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/guide/precheck.md'
---
# 전환 점검

Unity 게임을 앱인토스 미니앱으로 옮기기 전에, 게임이 어떤 기술로 만들어졌는지와 플랫폼에 잘 맞는지 살펴봐야 해요.\
이 과정을 통해 전환이 가능한지, 또 어떤 부분을 더 최적화하면 좋을지 알 수 있어요.

***

## 1. 호환성 체크 리스트

### ✅ 완전 지원 기능

#### 렌더링

* Unity 3D/2D 렌더링 파이프라인: Built-in, URP, HDRP 모두 지원
* WebGL 1.0/2.0: 자동 감지 및 대체
* 셰이더: Standard, Lit, Unlit 셰이더 완전 지원
* 텍스처 포맷: PNG, JPG, WebP, 압축 텍스처 지원
* 애니메이션: Animator, Animation Clip, Timeline 지원
* 파티클 시스템: Visual Effect Graph 포함 완전 지원

#### 스크립팅

* C# 스크립팅: .NET Standard 2.1 기반 완전 지원
* IL2CPP: 코드 최적화 및 성능 향상
* 이벤트 시스템: Unity Events, C# Events 지원
* 코루틴: 비동기 작업 완전 지원
* JSON 직렬화: JsonUtility, Newtonsoft.Json 지원

#### 물리학

* 2D/3D 물리: Box2D, PhysX 엔진 지원
* 충돌 감지: Trigger, Collision 이벤트 지원
* 관절 시스템: Joint 컴포넌트 모든 타입 지원
* Raycast: 2D/3D 레이캐스팅 완전 지원

#### UI 시스템

* uGUI (Legacy UI): Canvas, EventSystem 완전 지원
* UI Toolkit (UI Elements): 런타임 UI 지원
* Input System: 신/구 Input 시스템 모두 지원
* TextMeshPro: 고급 텍스트 렌더링 지원

### ⚠️ 제한적 지원 기능

#### 네트워킹

* UnityWebRequest ✅ — HTTP/HTTPS 완전 지원
* WebSocket ✅ — 실시간 통신 지원 (써드파티 라이브러리 필요)
* TCP/UDP Socket ❌ — 브라우저 보안상 미지원
* P2P 통신 ❌ — WebRTC 기반 솔루션 필요

#### 파일 시스템

* Resources 폴더 ✅ — 제한적 지원 (용량 고려 필요)
* StreamingAssets ✅ — CDN을 통한 동적 로딩 지원
* File I/O ❌ — 로컬 파일 시스템 접근 불가
* PlayerPrefs ✅ — 브라우저 LocalStorage 매핑

#### 멀티미디어

* 오디오 ⚠️ — 포맷 제한 있음 (WebM, OGG 권장)
* 비디오 ⚠️ — H.264, WebM 지원, 용량 제한
* 카메라 접근 ⚠️ — WebRTC API 활용 (권한 필요)
* 마이크 접근 ⚠️ — 브라우저 권한 정책 적용

#### 플랫폼 특화 기능

* ARCore/ARKit ❌ — WebXR로 대체 가능 (제한적)
* GPS/센서 ⚠️ — 브라우저 API 활용 (정확도 낮음)
* 진동 ✅ — 앱인토스 SDK 지원
* 알림 ✅ — 웹 푸시 알림 지원

### ❌ 미지원 기능

#### 네이티브 플러그인

* Native Plugin — iOS/Android 네이티브 코드
* DLL Import — 시스템 라이브러리 호출
* Platform-specific Code — 조건부 컴파일 (#if UNITY\_IOS 등)

#### 고급 시스템

* Multithreading — Job System 일부 제한
* Compute Shader — 제한적 지원
* XR (VR/AR) — WebXR 기반 제한적 지원

***

## 2. 성능 평가 기준

### 메모리 사용량

```
💚 좋음 (< 128MB)  
├── 2D 게임, 심플한 3D 게임
├── UI 중심 게임
└── 퍼즐/캐주얼 게임

🟨 보통 (128–256MB)  
├── 중간 규모 3D 게임
├── 2.5D 게임
└── 간단한 액션 게임

🔴 주의 (> 256MB)  
├── 대형 3D 게임
├── 오픈 월드 게임
└── 고화질 그래픽 게임
```

### 렌더링 복잡도

```
💚 적합 (< 100 Draw Call)
├── 2D 스프라이트 게임
├── 저폴리 3D 게임
└── UI 중심 게임

🟨 최적화 필요 (100-300 Draw Call)
├── 일반 3D 게임  
├── 이펙트가 많은 게임
└── 복잡한 UI 게임

🔴 대대적 최적화 필요 (> 300 Draw Call)
├── 고품질 3D 게임
├── 복잡한 셰이더 사용 게임
└── 많은 오브젝트가 동시 렌더링 
```

### 네트워크 의존성

```
💚 낮음
├── 오프라인 게임
├── 간단한 리더보드만 사용
└── 로컬 저장소 위주

🟨 보통
├── 실시간 멀티플레이어 (턴제)
├── 클라우드 세이브 사용
└── 소셜 기능 포함

🔴 높음
├── 실시간 액션 멀티플레이어
├── 스트리밍 콘텐츠 사용
└── 서버 의존적 게임플레이
```

***

## 3. 플랫폼별 특성 고려사항

### 모바일 환경 (iOS/Android)

```
고려사항
├── 터치 인터페이스로 UI 재설계 필요
├── 화면 크기 다양성 (4인치~7인치)
├── 성능 제약 (RAM 2-8GB)
├── 배터리 수명 고려
├── 네트워크 불안정성
└── 앱 백그라운드 전환
```

### 웹 브라우저 환경

```
고려사항
├── 브라우저별 호환성 차이
├── 웹 보안 정책 제약
├── 파일 다운로드 제한
├── 팝업 차단 정책
├── 자동재생 정책
└── 메모리 가비지 컬렉션
```

***

## 4. 게임 장르별 적합성 분석

### 🟢 매우 적합한 장르

```
✅ 퍼즐 게임
- 낮은 성능 요구사항
- 간단한 조작
- 짧은 플레이 세션

✅ 캐주얼 게임  
- 직관적 조작
- 빠른 시작
- 소셜 요소 활용

✅ 카드/보드 게임
- 정적 요소 위주
- 턴제 게임플레이
- 네트워크 지연 허용
```

### 🟡 적합한 장르 (최적화 필요)

```
⚠️ 액션 게임
- 터치 조작 최적화 필요
- 반응속도 중요
- 성능 최적화 필수

⚠️ RPG 게임
- 긴 플레이 세션
- 복잡한 시스템
- 메모리 관리 중요

⚠️ 시뮬레이션 게임
- 복잡한 로직
- 지속적인 연산
- UI 복잡도 높음
```

### 🔴 도전적인 장르

```
❗ FPS/TPS 게임
- 높은 프레임레이트 요구
- 정밀한 조작 필요
- 네트워크 지연 민감

❗ 레이싱 게임
- 높은 성능 요구
- 물리 연산 집약적
- 60FPS 필수

❗ MMO 게임
- 대용량 데이터
- 복잡한 네트워킹
- 긴 로딩 시간
```

***

## 5. 실용적 평가 도구

### 자동 평가 스크립트

```c#
using UnityEngine;
using UnityEditor;
using System.Collections.Generic;

public class AppsInTossCompatibilityChecker : EditorWindow
{
    [MenuItem("AppsInToss/Compatibility Checker")]
    public static void ShowWindow()
    {
        GetWindow<AppsInTossCompatibilityChecker>("호환성 검사");
    }
    
    void OnGUI()
    {
        GUILayout.Label("AppsInToss 호환성 검사", EditorStyles.boldLabel);
        
        if (GUILayout.Button("프로젝트 분석 시작"))
        {
            AnalyzeProject();
        }
    }
    
    void AnalyzeProject()
    {
        var textureMemory = CalculateTextureMemoryUsage();
        var meshMemory = CalculateMeshMemoryUsage();
        
        Debug.Log($"예상 텍스처 메모리: {textureMemory}MB");
        Debug.Log($"예상 메시 메모리: {meshMemory}MB");
        
        CheckIncompatibleComponents();
        SuggestOptimizations();
    }
}

```

### 성능 테스트 체크리스트

### 메모리 테스트

* 메모리 사용량 < 256MB
* 텍스처 압축 설정 확인
* 불필요한 리소스 제거
* 메모리 누수 검사

### 렌더링 테스트

* Draw Call < 200
* Batch 최적화 확인
* 셰이더 복잡도 검사
* LOD 시스템 적용

### 모바일 테스트

* 터치 입력 테스트
* 다양한 화면 비율 테스트
* 성능 프로파일링
* 배터리 소모 테스트

***

## 6. 마이그레이션 전략

### 단계별 접근법

```
1단계: 기본 포팅
├── 핵심 게임플레이 이식
├── 기본 UI 적응
└── 기본 기능 테스트

2단계: 최적화
├── 성능 병목 해결
├── 메모리 최적화
└── 로딩 시간 단축

3단계: 플랫폼 적응
├── AppsInToss SDK 연동
└── 최종 최적화
```

### 리스크 관리

```
⚠️ 높은 리스크
├── 대폭적인 아키텍처 변경 필요
├── 성능 목표 달성 불가능
└── 핵심 기능 구현 불가

🔶 중간 리스크
├── 일부 기능 재설계 필요
├── 최적화 작업 대량 필요
└── 추가 개발 시간 필요

✅ 낮은 리스크
├── 기본 포팅으로 동작
├── 최소한의 최적화 필요
└── 빠른 시장 출시 가능
```

***

## 7. 의사결정 가이드

### 전환 권장 조건

* Unity 2021.3 LTS 이상 사용
* 메모리 사용량 < 200MB
* 네이티브 플러그인 미사용
* 웹 친화적 게임 디자인
* 개발팀의 웹 기술 이해도

### 전환 비권장 조건

* 레거시 Unity 버전 (2019 이하)
* 대용량 게임 (> 500MB)
* 네이티브 의존성 높음
* 실시간 성능 크리티컬
* 짧은 개발 일정

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/위치
  정보/Accuracy.md
---

# 정확도 옵션

## `Accuracy`

`Accuracy` 는 위치 정확도 옵션이에요.

## 시그니처

```typescript
enum Accuracy {
    /**
     * 오차범위 3KM 이내
     */
    Lowest = 1,
    /**
     * 오차범위 1KM 이내
     */
    Low = 2,
    /**
     * 오차범위 몇 백미터 이내
     */
    Balanced = 3,
    /**
     * 오차범위 10M 이내
     */
    High = 4,
    /**
     * 가장 높은 정확도
     */
    Highest = 5,
    /**
     * 네비게이션을 위한 최고 정확도
     */
    BestForNavigation = 6
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/위치
  정보/LocationCoords.md
---

# 좌표 정보

## `LocationCoords`

`LocationCoords`는 세부 위치 정보를 나타내는 객체예요.

## 시그니처

```typescript
interface LocationCoords {
    /**
     * 위도
     */
    latitude: number;
    /**
     * 경도
     */
    longitude: number;
    /**
     * 높이
     */
    altitude: number;
    /**
     * 위치 정확도
     */
    accuracy: number;
    /**
     * 고도 정확도
     */
    altitudeAccuracy: number;
    /**
     * 방향
     */
    heading: number;
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인앱
  결제/getCompletedOrRefundedOrders.md
---

# 주문목록 가져오기

## `getCompletedOrRefundedOrders`

`getCompletedOrRefundedOrders` 는 인앱결제로 구매하고 환불한 주문 목록을 가져와요.\
인앱결제 결제 및 상품 지급이 완료된 주문건와 환불된 주문건을 조회할 수 있어요.

결제는 완료되었지만 상품이 아직 지급되지 않은 주문건은 조회되지 않아요.\
[`getPendingOrders`](/bedrock/reference/framework/인앱%20결제/getPendingOrders)함수를 통해 `orderId`를 조회하여 사용자에게 상품을 지급한 후 [`completeProductGrant`](/bedrock/reference/framework/인앱%20결제/completeProductGrant)함수를 통해 상품 지급을 완료 처리하세요.

앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.

## 시그니처

```typescript
function getCompletedOrRefundedOrders(params?: {
  key?: string | null;
}): Promise<CompletedOrRefundedOrdersResult | undefined>;
```

### 반환값

### 반환 객체 프로퍼티

```tsx
interface CompletedOrRefundedOrdersResult {
    hasNext: boolean;
    nextKey?: string | null;
    orders: {
        orderId: string;
        sku: string;
        status: 'COMPLETED' | 'REFUNDED';
        date: string;
    }[];
}
```

## 예제

::: code-group

```js [js]
import { IAP } from '@apps-in-toss/web-framework';

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getCompletedOrRefundedOrders();
    return response;
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React]
 import { IAP } from '@apps-in-toss/framework';
 
 async function fetchOrders() {
   try {
     const pendingOrders = await IAP.getCompletedOrRefundedOrders();
     return response;
   } catch (error) {
     console.error(error);
   }
 }
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인터렉션/HapticFeedbackOptions.md
---

# 진동 타입(옵션)

## `HapticFeedbackOptions`

`HapticFeedbackOptions` 는 `generateHapticFeedback` 함수에 전달할 햅틱진동의 타입을 나타내요. 진동타입의 종류는 다음과 같아요.

```typescript
type HapticFeedbackType =
| "tickWeak"
| "tap"
| "tickMedium"
| "softMedium"
| "basicWeak"
| "basicMedium"
| "success"
| "error"
| "wiggle"
| "confetti";
```

## 시그니처

```typescript
interface HapticFeedbackOptions {
    type: HapticFeedbackType;
}
```

### 타입 정의

#### `HapticFeedbackOptions`

*`type: HapticFeedbackType`*

#### `HapticFeedbackType`

*`"tickWeak" | "tap" | "tickMedium" | "softMedium" | "basicWeak" | "basicMedium" | "success" | "error" | "wiggle" | "confetti"`*

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/first-scene-optimization.md
---
# 첫 씬 시작 최적화 가이드

앱인토스 Unity 게임에서 첫 번째 씬의 로딩 시간을 최소화하여 즉시 플레이 가능한 경험을 제공하는 방법을 다뤄요.

## 1. 첫 씬 최적화 전략

### 첫 씬 구조 최적화

```
🚀 최적화된 첫 씬 구조
├── 핵심 게임 요소 (즉시 로딩)
│   ├── 플레이어 컨트롤러
│   ├── 기본 UI 시스템
│   ├── 입력 관리자
│   └── 게임 매니저
├── 시각적 요소 (단계적 로딩)
│   ├── 배경 이미지 (저해상도 → 고해상도)
│   ├── 캐릭터 모델 (LOD 0 → LOD 상위)
│   ├── 환경 오브젝트 (필수 → 장식)
│   └── 파티클 효과 (기본 → 고급)
├── 오디오 (지연 로딩)
│   ├── 배경 음악
│   ├── 효과음
│   └── 음성
└── 비핵심 시스템 (백그라운드 로딩)
    ├── 분석 시스템
    ├── 소셜 기능
    ├── 광고 시스템
    └── 업데이트 체크
```

### 첫 씬 최적화 매니저

```c#
using UnityEngine;
using UnityEngine.SceneManagement;
using System.Collections;
using System.Collections.Generic;

public class FirstSceneOptimizer : MonoBehaviour
{
    public static FirstSceneOptimizer Instance { get; private set; }
    
    [System.Serializable]
    public class OptimizationSettings
    {
        [Header("로딩 우선순위")]
        public GameObject[] criticalObjects;
        public GameObject[] secondaryObjects;
        public GameObject[] optionalObjects;
        
        [Header("품질 설정")]
        public int initialQualityLevel = 0;
        public bool enableProgressiveLOD = true;
        public bool enableAsyncLoading = true;
        
        [Header("시간 제한")]
        public float maxInitialLoadTime = 2f;
        public float maxSecondaryLoadTime = 5f;
    }
    
    [Header("최적화 설정")]
    public OptimizationSettings settings;
    
    // 내부 상태
    private bool isOptimizationComplete = false;
    private float optimizationStartTime;
    private List<GameObject> loadedObjects = new List<GameObject>();
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            StartFirstSceneOptimization();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void StartFirstSceneOptimization()
    {
        optimizationStartTime = Time.realtimeSinceStartup;
        
        Debug.Log("첫 씬 최적화 시작");
        
        // 초기 품질 설정
        QualitySettings.SetQualityLevel(settings.initialQualityLevel);
        
        // 단계별 로딩 시작
        StartCoroutine(OptimizedLoadingSequence());
    }
    
    IEnumerator OptimizedLoadingSequence()
    {
        // 1단계: 즉시 필요한 핵심 오브젝트 활성화
        yield return StartCoroutine(LoadCriticalObjects());
        
        // 첫 프레임 렌더링을 위해 대기
        yield return null;
        
        // 2단계: 2차 오브젝트 로딩
        StartCoroutine(LoadSecondaryObjects());
        
        // 3단계: 선택적 오브젝트 백그라운드 로딩
        StartCoroutine(LoadOptionalObjects());
        
        // 최적화 완료
        CompleteOptimization();
    }
    
    IEnumerator LoadCriticalObjects()
    {
        Debug.Log("핵심 오브젝트 로딩 시작");
        
        foreach (var obj in settings.criticalObjects)
        {
            if (obj != null)
            {
                obj.SetActive(true);
                loadedObjects.Add(obj);
                
                // 프레임 분산을 위해 대기
                yield return null;
            }
        }
        
        float loadTime = Time.realtimeSinceStartup - optimizationStartTime;
        Debug.Log($"핵심 오브젝트 로딩 완료: {loadTime:F2}초");
        
        // 게임 시작 가능 신호
        SendGameReadySignal();
    }
    
    IEnumerator LoadSecondaryObjects()
    {
        float startTime = Time.realtimeSinceStartup;
        
        foreach (var obj in settings.secondaryObjects)
        {
            // 시간 제한 체크
            if (Time.realtimeSinceStartup - startTime > settings.maxSecondaryLoadTime)
            {
                break;
            }
            
            if (obj != null)
            {
                obj.SetActive(true);
                loadedObjects.Add(obj);
                
                // 프레임 분산
                yield return null;
            }
        }
        
        Debug.Log("2차 오브젝트 로딩 완료");
    }
    
    IEnumerator LoadOptionalObjects()
    {
        // 플레이어가 활발하지 않을 때만 로딩
        while (true)
        {
            if (IsPlayerIdle())
            {
                foreach (var obj in settings.optionalObjects)
                {
                    if (obj != null && !obj.activeInHierarchy)
                    {
                        obj.SetActive(true);
                        loadedObjects.Add(obj);
                        
                        // 여러 프레임에 걸쳐 분산
                        for (int i = 0; i < 3; i++)
                        {
                            yield return null;
                        }
                        
                        // 플레이어가 다시 활성화되면 중단
                        if (!IsPlayerIdle())
                        {
                            break;
                        }
                    }
                }
            }
            
            yield return new WaitForSeconds(1f);
        }
    }
    
    bool IsPlayerIdle()
    {
        // 간단한 유휴 상태 감지 로직
        return Time.realtimeSinceStartup - Time.time > 3f;
    }
    
    void SendGameReadySignal()
    {
        float readyTime = Time.realtimeSinceStartup - optimizationStartTime;
        
        var readyData = new Dictionary<string, object>
        {
            {"ready_time", readyTime},
            {"loaded_objects", loadedObjects.Count},
            {"quality_level", QualitySettings.GetQualityLevel()}
        };
        
        AppsInToss.SendEvent("first_scene_ready", readyData);
        
        Debug.Log($"첫 씬 준비 완료: {readyTime:F2}초");
    }
    
    void CompleteOptimization()
    {
        isOptimizationComplete = true;
        
        // 점진적 품질 향상 시작
        if (settings.enableProgressiveLOD)
        {
            StartCoroutine(ProgressiveQualityImprovement());
        }
        
        float totalTime = Time.realtimeSinceStartup - optimizationStartTime;
        
        // 최적화 완료 분석 데이터
        var analyticsData = new Dictionary<string, object>
        {
            {"optimization_time", totalTime},
            {"objects_loaded", loadedObjects.Count},
            {"device_model", SystemInfo.deviceModel},
            {"memory_usage", System.GC.GetTotalMemory(false) / (1024f * 1024f)}
        };
        
        AppsInToss.SendAnalytics("first_scene_optimization", analyticsData);
    }
    
    IEnumerator ProgressiveQualityImprovement()
    {
        // 몇 초 대기 후 품질 점진적 향상
        yield return new WaitForSeconds(3f);
        
        int maxQuality = QualitySettings.names.Length - 1;
        int currentQuality = QualitySettings.GetQualityLevel();
        
        while (currentQuality < maxQuality)
        {
            // 성능 여유가 있을 때만 품질 향상
            if (Application.targetFrameRate <= 0 || Time.smoothDeltaTime * Application.targetFrameRate < 1.2f)
            {
                currentQuality++;
                QualitySettings.SetQualityLevel(currentQuality);
                
                Debug.Log($"품질 레벨 향상: {currentQuality}");
                
                // 품질 변경 후 안정화 대기
                yield return new WaitForSeconds(2f);
            }
            else
            {
                // 성능이 부족하면 대기
                yield return new WaitForSeconds(5f);
            }
        }
    }
    
    // 공개 API
    public bool IsOptimizationComplete()
    {
        return isOptimizationComplete;
    }
    
    public float GetOptimizationProgress()
    {
        if (isOptimizationComplete) return 1f;
        
        int totalObjects = settings.criticalObjects.Length + 
                          settings.secondaryObjects.Length + 
                          settings.optionalObjects.Length;
        
        return totalObjects > 0 ? (float)loadedObjects.Count / totalObjects : 0f;
    }
    
    public void ForceCompleteOptimization()
    {
        StopAllCoroutines();
        
        // 모든 오브젝트 즉시 활성화
        foreach (var obj in settings.criticalObjects)
        {
            if (obj != null) obj.SetActive(true);
        }
        foreach (var obj in settings.secondaryObjects)
        {
            if (obj != null) obj.SetActive(true);
        }
        
        CompleteOptimization();
    }
}
```

***

## 2. 성능 모니터링

### 실시간 성능 추적

```c#
public class FirstScenePerformanceMonitor : MonoBehaviour
{
    [Header("성능 임계값")]
    public float targetFPS = 30f;
    public float maxLoadTime = 3f;
    public float maxMemoryUsageMB = 200f;
    
    private float sceneStartTime;
    private List<float> frameTimes = new List<float>();
    
    void Start()
    {
        sceneStartTime = Time.realtimeSinceStartup;
        StartCoroutine(MonitorPerformance());
    }
    
    IEnumerator MonitorPerformance()
    {
        while (true)
        {
            // FPS 모니터링
            float frameTime = Time.smoothDeltaTime;
            frameTimes.Add(frameTime);
            
            if (frameTimes.Count > 60) // 2초간의 프레임 타임 유지
            {
                frameTimes.RemoveAt(0);
            }
            
            // 성능 문제 감지
            CheckPerformanceIssues();
            
            yield return null;
        }
    }
    
    void CheckPerformanceIssues()
    {
        // FPS 체크
        if (frameTimes.Count > 30)
        {
            float avgFrameTime = 0f;
            for (int i = frameTimes.Count - 30; i < frameTimes.Count; i++)
            {
                avgFrameTime += frameTimes[i];
            }
            avgFrameTime /= 30f;
            
            float currentFPS = 1f / avgFrameTime;
            
            if (currentFPS < targetFPS * 0.8f) // 20% 여유
            {
                OnPerformanceIssueDetected("Low FPS", currentFPS);
            }
        }
        
        // 메모리 사용량 체크
        float memoryUsageMB = System.GC.GetTotalMemory(false) / (1024f * 1024f);
        if (memoryUsageMB > maxMemoryUsageMB)
        {
            OnPerformanceIssueDetected("High Memory Usage", memoryUsageMB);
        }
        
        // 로딩 시간 체크
        float loadTime = Time.realtimeSinceStartup - sceneStartTime;
        if (loadTime > maxLoadTime && !FirstSceneOptimizer.Instance.IsOptimizationComplete())
        {
            OnPerformanceIssueDetected("Slow Loading", loadTime);
        }
    }
    
    void OnPerformanceIssueDetected(string issueType, float value)
    {
        Debug.LogWarning($"성능 문제 감지: {issueType} = {value:F2}");
        
        // 자동 최적화 시도
        TryAutoOptimization(issueType);
        
        // 분석 데이터 전송
        var issueData = new Dictionary<string, object>
        {
            {"issue_type", issueType},
            {"value", value},
            {"scene_time", Time.realtimeSinceStartup - sceneStartTime},
            {"device_model", SystemInfo.deviceModel}
        };
        
        AppsInToss.SendAnalytics("first_scene_performance_issue", issueData);
    }
    
    void TryAutoOptimization(string issueType)
    {
        switch (issueType)
        {
            case "Low FPS":
                // 품질 레벨 낮추기
                int currentQuality = QualitySettings.GetQualityLevel();
                if (currentQuality > 0)
                {
                    QualitySettings.SetQualityLevel(currentQuality - 1);
                    Debug.Log($"품질 레벨 자동 조정: {currentQuality - 1}");
                }
                break;
                
            case "High Memory Usage":
                // 강제 가비지 컬렉션
                System.GC.Collect();
                break;
                
            case "Slow Loading":
                // 강제 최적화 완료
                if (FirstSceneOptimizer.Instance != null)
                {
                    FirstSceneOptimizer.Instance.ForceCompleteOptimization();
                }
                break;
        }
    }
}
```

첫 씬은 사용자의 첫인상을 결정짓는 중요한 순간이에요.\
핵심 기능을 우선 로딩하고 나머지는 점진적으로 로딩하여 즉시 플레이 가능한 경험을 제공하세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/친구초대/ContactsViralOption.md
---

# 친구 초대 옵션

## `ContactsViralOption`

`ContactsViralOption`는 [연락처 공유 기능](/bedrock/reference/framework/친구초대/contactsViral.md)을 사용할 때 필요한 옵션이에요.

## 시그니처

```ts
type ContactsViralOption = {
  moduleId: string;
};
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/친구초대/ContactsViralSuccessEvent.md
---

# 친구 초대 완료 반환 이벤트

## `ContactsViralSuccessEvent`

`ContactsViralSuccessEvent` 는 연락처 공유 모듈이 정상적으로 종료됐을 때 전달되는 이벤트 객체예요. 종료 이유와 함께 리워드 상태 및 남은 친구 수 등 관련 정보를 제공해요.

## 시그니처

```ts
type ContactsViralSuccessEvent = {
  type: 'close';
  data: {
    closeReason: 'clickBackButton' | 'noReward';
    sentRewardAmount?: number;
    sendableRewardsCount?: number;
    sentRewardsCount: number;
    rewardUnit?: string;
  };
};
```

### 프로퍼티

## 예제

### 모듈 종료 이벤트 처리하기

```ts
contactsViral({
  options: { moduleId: 'your-module-id' },
  onEvent: (event) => {
    if (event.type === 'close') {
      console.log('종료 사유:', event.data.closeReason);
      console.log('공유 완료한 친구 수:', event.data.sentRewardsCount);
    }
  },
  onError: (error) => {
    console.error('에러 발생:', error);
  },
});
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/친구초대/ContactsViralParams.md
---

# 친구 초대 파라미터

## `ContactsViralParams`

`ContactsViralParams` 는 `contactsViral` 함수를 실행할 때 사용하는 파라미터 타입이에요. 옵션을 설정하고, 이벤트 및 에러 처리 콜백을 지정할 수 있어요.

## 시그니처

```ts
interface ContactsViralParams {
  options: ContactsViralOption;
  onEvent: (event: ContactsViralEvent) => void;
  onError: (error: unknown) => void;
}
```

### 프로퍼티

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/카메라/openCamera.md
---

# 카메라로 사진 촬영하기

## `openCamera`

카메라를 실행해서 촬영된 이미지를 반환하는 함수예요.

## 시그니처

```typescript
function openCamera(options: {
  base64: boolean;
  maxWidth: number;
}): Promise<ImageResponse>;
```

### 파라미터

### 프로퍼티

### 반환 값

촬영된 이미지 정보를 포함한 객체를 반환해요. 반환 객체의 구성은 다음과 같아요:

* `id`: 이미지의 고유 식별자예요.
* `dataUri`: 이미지 데이터를 표현하는 데이터 URI예요.

## OpenCameraPermissionError

카메라 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof OpenCameraPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class OpenCameraPermissionError extends PermissionError {
    constructor();
}
```

## 예제

### 카메라 실행 후 촬영된 사진 가져오기

카메라로 사진을 찍고 결과를 가져오는 예제예요.
이 과정에서 현재 카메라 권한 상태를 확인할 수 있고, 권한이 없으면 권한을 요청해요.
사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`OpenCameraPermissionError`](./OpenCameraPermissionError)를 반환해요.

::: code-group

```js [js]
import { openCamera, OpenCameraPermissionError } from '@apps-in-toss/web-framework';

const base64 = true;

async function handleOpenCamera() {
  try {
    const response = await openCamera({ base64 });
    const imageUri = base64 ? 'data:image/jpeg;base64,' + response.dataUri : response.dataUri;
    console.log('사진 촬영 성공:', imageUri);
  } catch (error) {
    if (error instanceof OpenCameraPermissionError) {
      console.log('권한 에러');
    }
    console.error('사진을 가져오는 데 실패했어요:', error);
  }
}

async function handleGetPermissionForOpenCamera() {
  const permission = await openCamera.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForOpenCamera() {
  const permission = await openCamera.openPermissionDialog();
  return permission;
}
```

```tsx [React]
import { ImageResponse, openCamera, OpenCameraPermissionError } from '@apps-in-toss/web-framework';
import { useState } from 'react';

const base64 = true;

// 카메라를 실행하고 촬영된 이미지를 화면에 표시하는 컴포넌트
function Camera() {
  const [image, setImage] = useState<ImageResponse | null>(null);

  const handlePress = async () => {
    try {
      const response = await openCamera({ base64 });
      setImage(response);
    } catch (error) {
      if (error instanceof OpenCameraPermissionError) {
        console.log('권한 에러');
      }

      console.error('사진을 가져오는 데 실패했어요:', error);
    }
  };

  // base64 형식으로 반환된 이미지를 표시하려면 데이터 URL 스키마 Prefix를 붙여야해요.
  const imageUri = base64 ? 'data:image/jpeg;base64,' + image?.dataUri : image?.dataUri;

  return (
    <div>
      {image ? <Image source={{ uri: imageUri }} style={{ width: 200, height: 200 }} /> : <span>사진이 없어요</span>}
      <input type="button" value="사진 촬영하기" onClick={handlePress} />
      <input type="button"
        value="권한 확인하기"
        onClick={async () => {
          const permission = await openCamera.getPermission();
          Alert.alert(permission);
        }}
      />

      <input type="button"
        value="권한 요청하기"
        onClick={async () => {
          const currentPermission = await openCamera.openPermissionDialog();
          Alert.alert(currentPermission);
        }}
      />
    </div>
  );
}
```

```tsx [React Native]
import { ImageResponse, openCamera, OpenCameraPermissionError } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Image, Text, View } from 'react-native';

const base64 = true;

// 카메라를 실행하고 촬영된 이미지를 화면에 표시하는 컴포넌트
function Camera() {
  const [image, setImage] = useState<ImageResponse | null>(null);

  const handlePress = async () => {
    try {
      const response = await openCamera({ base64 });
      setImage(response);
    } catch (error) {
      if (error instanceof OpenCameraPermissionError) {
        console.log('권한 에러');
      }

      console.error('사진을 가져오는 데 실패했어요:', error);
    }
  };

  // base64 형식으로 반환된 이미지를 표시하려면 데이터 URL 스키마 Prefix를 붙여야해요.
  const imageUri = base64 ? 'data:image/jpeg;base64,' + image?.dataUri : image?.dataUri;

  return (
    <View>
      {image ? <Image source={{ uri: imageUri }} style={{ width: 200, height: 200 }} /> : <Text>사진이 없어요</Text>}
      <Button title="사진 촬영하기" onPress={handlePress} />
      <Button
        title="권한 확인하기"
        onPress={async () => {
          const permission = await openCamera.getPermission();
          Alert.alert(permission);
        }}
      />

      <Button
        title="권한 요청하기"
        onPress={async () => {
          const currentPermission = await openCamera.openPermissionDialog();
          Alert.alert(currentPermission);
        }}
      />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-camera](https://github.com/toss/apps-in-toss-examples/tree/main/with-camera) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/unity/optimization/start/custom-loading.md
---
# 커스텀 로딩 화면

앱인토스 Unity 게임에서 브랜드에 맞는 커스텀 로딩 화면을 구현하여 사용자 경험을 향상시키는 방법을 다뤄요.

## 1. 커스텀 로딩 시스템 개요

### 로딩 화면 구성 요소

```
🎨 앱인토스 로딩 화면 구조
├── 브랜드 영역
│   ├── 게임 로고
│   └── 브랜딩 배경
├── 진행률 표시
│   ├── 프로그레스 바
│   ├── 퍼센트 텍스트
│   └── 로딩 메시지
├── 인터랙션 요소
│   ├── 애니메이션 효과
│   ├── 터치 힌트
│   └── 스킵 버튼 (선택적)
└── 시스템 정보
    ├── 네트워크 상태
    ├── 에러 메시지
    └── 재시도 버튼
```

### 커스텀 로딩 매니저

```c#
using UnityEngine;
using UnityEngine.UI;
using System.Collections;
using System.Collections.Generic;
using TMPro;

public class AppsInTossLoadingManager : MonoBehaviour
{
    public static AppsInTossLoadingManager Instance { get; private set; }
    
    [System.Serializable]
    public class LoadingConfig
    {
        [Header("브랜딩 설정")]
        public Sprite tossLogo;
        public Sprite gameLogo;
        public Color primaryColor = Color.blue;
        public Color secondaryColor = Color.white;
        public Gradient backgroundGradient;
        
        [Header("애니메이션 설정")]
        public float logoAnimationDuration = 2f;
        public AnimationCurve logoScaleCurve = AnimationCurve.EaseInOut(0, 0.8f, 1, 1f);
        public bool enableParticleEffect = true;
        public ParticleSystem backgroundParticles;
        
        [Header("진행률 설정")]
        public bool showProgressBar = true;
        public bool showPercentage = true;
        public bool showLoadingTips = true;
        public string[] loadingTips;
        
        [Header("터치 인터랙션")]
        public bool enableTouchToSkip = false;
        public float skipAfterSeconds = 3f;
        public string skipHintText = "화면을 탭하여 건너뛰기";
    }
    
    [Header("로딩 설정")]
    public LoadingConfig config;
    
    [Header("UI 컴포넌트")]
    public Canvas loadingCanvas;
    public Image backgroundImage;
    public Image tossLogoImage;
    public Image gameLogoImage;
    public Slider progressSlider;
    public TextMeshProUGUI progressText;
    public TextMeshProUGUI statusText;
    public TextMeshProUGUI tipText;
    public Button skipButton;
    public GameObject errorPanel;
    public TextMeshProUGUI errorText;
    public Button retryButton;
    
    [Header("애니메이션 컴포넌트")]
    public Animator loadingAnimator;
    public ParticleSystem[] particleSystems;
    
    // 내부 상태
    private float currentProgress = 0f;
    private string currentStatus = "";
    private bool isLoadingComplete = false;
    private bool canSkip = false;
    private int currentTipIndex = 0;
    private Coroutine tipRotationCoroutine;
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeLoadingScreen();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeLoadingScreen()
    {
        // 브랜딩 적용
        ApplyBrandingSettings();
        
        // 초기 UI 설정
        SetupInitialUI();
        
        // 애니메이션 시작
        StartLoadingAnimations();
        
        // 이벤트 리스너 등록
        RegisterEventListeners();
        
        Debug.Log("AppsInToss 커스텀 로딩 화면 초기화 완료");
    }
    
    void ApplyBrandingSettings()
    {
        // 로고 설정
        if (config.tossLogo != null)
            tossLogoImage.sprite = config.tossLogo;
        if (config.gameLogo != null)
            gameLogoImage.sprite = config.gameLogo;
        
        // 색상 테마 적용
        progressSlider.fillRect.GetComponent<Image>().color = config.primaryColor;
        
        // 배경 그라디언트 적용
        if (config.backgroundGradient != null)
        {
            ApplyGradientBackground();
        }
        
        // 파티클 효과 설정
        if (config.enableParticleEffect && particleSystems.Length > 0)
        {
            SetupParticleEffects();
        }
    }
    
    void ApplyGradientBackground()
    {
        // 그라디언트 머티리얼 생성 및 적용
        var gradientMaterial = new Material(Shader.Find("UI/Gradient"));
        gradientMaterial.SetColor("_TopColor", config.backgroundGradient.Evaluate(0f));
        gradientMaterial.SetColor("_BottomColor", config.backgroundGradient.Evaluate(1f));
        backgroundImage.material = gradientMaterial;
    }
    
    void SetupParticleEffects()
    {
        foreach (var particles in particleSystems)
        {
            if (particles != null)
            {
                var main = particles.main;
                main.startColor = config.primaryColor;
                particles.Play();
            }
        }
    }
    
    void SetupInitialUI()
    {
        // 진행률 초기화
        progressSlider.value = 0f;
        progressSlider.gameObject.SetActive(config.showProgressBar);
        
        // 텍스트 초기화
        progressText.gameObject.SetActive(config.showPercentage);
        tipText.gameObject.SetActive(config.showLoadingTips);
        
        // 스킵 버튼 설정
        skipButton.gameObject.SetActive(false);
        skipButton.onClick.AddListener(OnSkipButtonClicked);
        
        // 재시도 버튼 설정
        retryButton.onClick.AddListener(OnRetryButtonClicked);
        errorPanel.SetActive(false);
        
        // 초기 상태 설정
        UpdateStatus("게임을 준비하고 있습니다...");
    }
    
    void StartLoadingAnimations()
    {
        // 로고 등장 애니메이션
        StartCoroutine(AnimateLogoEntrance());
        
        // 로딩 팁 순환 시작
        if (config.showLoadingTips && config.loadingTips.Length > 0)
        {
            tipRotationCoroutine = StartCoroutine(RotateLoadingTips());
        }
        
        // 스킵 가능 시점 설정
        if (config.enableTouchToSkip)
        {
            StartCoroutine(EnableSkipAfterDelay());
        }
    }
    
    IEnumerator AnimateLogoEntrance()
    {
        // 토스 로고 애니메이션
        tossLogoImage.transform.localScale = Vector3.one * 0.8f;
        gameLogoImage.transform.localScale = Vector3.one * 0.8f;
        
        float elapsedTime = 0f;
        while (elapsedTime < config.logoAnimationDuration)
        {
            elapsedTime += Time.deltaTime;
            float progress = elapsedTime / config.logoAnimationDuration;
            float scaleValue = config.logoScaleCurve.Evaluate(progress);
            
            tossLogoImage.transform.localScale = Vector3.one * scaleValue;
            gameLogoImage.transform.localScale = Vector3.one * scaleValue;
            
            yield return null;
        }
        
        // 최종 스케일 설정
        tossLogoImage.transform.localScale = Vector3.one;
        gameLogoImage.transform.localScale = Vector3.one;
        
        // 로고 펄스 애니메이션 시작
        if (loadingAnimator != null)
        {
            loadingAnimator.SetTrigger("StartPulse");
        }
    }
    
    IEnumerator RotateLoadingTips()
    {
        while (!isLoadingComplete)
        {
            if (config.loadingTips.Length > 0)
            {
                tipText.text = config.loadingTips[currentTipIndex];
                currentTipIndex = (currentTipIndex + 1) % config.loadingTips.Length;
            }
            
            yield return new WaitForSeconds(3f);
        }
    }
    
    IEnumerator EnableSkipAfterDelay()
    {
        yield return new WaitForSeconds(config.skipAfterSeconds);
        
        if (!isLoadingComplete)
        {
            canSkip = true;
            skipButton.gameObject.SetActive(true);
            
            // 스킵 힌트 표시
            StartCoroutine(ShowSkipHint());
        }
    }
    
    IEnumerator ShowSkipHint()
    {
        var hintText = skipButton.GetComponentInChildren<TextMeshProUGUI>();
        hintText.text = config.skipHintText;
        
        // 깜박임 효과
        while (canSkip && !isLoadingComplete)
        {
            hintText.color = new Color(hintText.color.r, hintText.color.g, hintText.color.b, 0.5f);
            yield return new WaitForSeconds(0.5f);
            hintText.color = new Color(hintText.color.r, hintText.color.g, hintText.color.b, 1f);
            yield return new WaitForSeconds(0.5f);
        }
    }
    
    void RegisterEventListeners()
    {
        AppsInToss.OnEvent += HandleAppsInTossEvent;
        AppsInToss.OnError += HandleAppsInTossError;
    }
    
    void HandleAppsInTossEvent(string eventName, Dictionary<string, object> data)
    {
        switch (eventName)
        {
            case "loading_progress":
                float progress = (float)data["progress"];
                string status = data["status"] as string;
                UpdateProgress(progress, status);
                break;
                
            case "loading_complete":
                CompleteLoading();
                break;
                
            case "asset_loaded":
                string assetName = data["asset_name"] as string;
                UpdateStatus($"{assetName} 로딩 완료");
                break;
        }
    }
    
    void HandleAppsInTossError(string errorType, string errorMessage)
    {
        ShowError(errorMessage);
    }
    
    public void UpdateProgress(float progress, string status = null)
    {
        currentProgress = Mathf.Clamp01(progress);
        
        // UI 업데이트
        if (config.showProgressBar)
        {
            progressSlider.value = currentProgress;
        }
        
        if (config.showPercentage)
        {
            progressText.text = $"{currentProgress * 100f:F0}%";
        }
        
        if (!string.IsNullOrEmpty(status))
        {
            UpdateStatus(status);
        }
        
        // 완료 체크
        if (currentProgress >= 1f)
        {
            CompleteLoading();
        }
    }
    
    public void UpdateStatus(string status)
    {
        currentStatus = status;
        statusText.text = status;
        
        Debug.Log($"로딩 상태 업데이트: {status}");
    }
    
    public void ShowError(string errorMessage)
    {
        errorText.text = errorMessage;
        errorPanel.SetActive(true);
        
        // 로딩 애니메이션 일시 정지
        if (loadingAnimator != null)
        {
            loadingAnimator.speed = 0f;
        }
        
        Debug.LogError($"로딩 에러: {errorMessage}");
    }
    
    public void CompleteLoading()
    {
        if (isLoadingComplete) return;
        
        isLoadingComplete = true;
        canSkip = false;
        
        // 팁 순환 중지
        if (tipRotationCoroutine != null)
        {
            StopCoroutine(tipRotationCoroutine);
        }
        
        // 완료 애니메이션 시작
        StartCoroutine(PlayCompletionAnimation());
    }
    
    IEnumerator PlayCompletionAnimation()
    {
        UpdateStatus("게임 시작 준비 완료!");
        
        // 진행률 100% 표시
        if (config.showProgressBar)
        {
            progressSlider.value = 1f;
        }
        if (config.showPercentage)
        {
            progressText.text = "100%";
        }
        
        // 완료 애니메이션
        if (loadingAnimator != null)
        {
            loadingAnimator.SetTrigger("Complete");
        }
        
        // 완료 효과
        PlayCompletionEffects();
        
        yield return new WaitForSeconds(1f);
        
        // 로딩 화면 페이드 아웃
        yield return StartCoroutine(FadeOutLoadingScreen());
        
        // 게임 씬 로드
        LoadGameScene();
    }
    
    void PlayCompletionEffects()
    {
        // 파티클 효과 강화
        foreach (var particles in particleSystems)
        {
            if (particles != null)
            {
                var emission = particles.emission;
                emission.rateOverTime = emission.rateOverTime.constant * 3f;
            }
        }
        
        // 로고 펄스 효과
        StartCoroutine(PulseLogo(tossLogoImage.transform));
        StartCoroutine(PulseLogo(gameLogoImage.transform));
    }
    
    IEnumerator PulseLogo(Transform logoTransform)
    {
        Vector3 originalScale = logoTransform.localScale;
        Vector3 targetScale = originalScale * 1.1f;
        
        // 확대
        float duration = 0.3f;
        float elapsedTime = 0f;
        
        while (elapsedTime < duration)
        {
            elapsedTime += Time.deltaTime;
            float progress = elapsedTime / duration;
            logoTransform.localScale = Vector3.Lerp(originalScale, targetScale, progress);
            yield return null;
        }
        
        // 축소
        elapsedTime = 0f;
        while (elapsedTime < duration)
        {
            elapsedTime += Time.deltaTime;
            float progress = elapsedTime / duration;
            logoTransform.localScale = Vector3.Lerp(targetScale, originalScale, progress);
            yield return null;
        }
        
        logoTransform.localScale = originalScale;
    }
    
    IEnumerator FadeOutLoadingScreen()
    {
        CanvasGroup canvasGroup = loadingCanvas.GetComponent<CanvasGroup>();
        if (canvasGroup == null)
        {
            canvasGroup = loadingCanvas.gameObject.AddComponent<CanvasGroup>();
        }
        
        float fadeTime = 1f;
        float elapsedTime = 0f;
        
        while (elapsedTime < fadeTime)
        {
            elapsedTime += Time.deltaTime;
            canvasGroup.alpha = 1f - (elapsedTime / fadeTime);
            yield return null;
        }
        
        canvasGroup.alpha = 0f;
        loadingCanvas.gameObject.SetActive(false);
    }
    
    void LoadGameScene()
    {
        // 게임 씬 로드
        UnityEngine.SceneManagement.SceneManager.LoadScene("GameScene");
        
        // 분석 데이터 전송
        SendLoadingAnalytics();
    }
    
    void SendLoadingAnalytics()
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"loading_completed", true},
            {"final_progress", currentProgress},
            {"last_status", currentStatus},
            {"skip_used", false},
            {"completion_time", Time.time},
            {"device_model", SystemInfo.deviceModel},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("custom_loading_complete", analyticsData);
    }
    
    void OnSkipButtonClicked()
    {
        if (canSkip && !isLoadingComplete)
        {
            Debug.Log("사용자가 로딩을 건너뛰었습니다");
            
            // 스킵 분석 데이터
            var skipData = new Dictionary<string, object>
            {
                {"skip_time", Time.time},
                {"progress_at_skip", currentProgress},
                {"status_at_skip", currentStatus}
            };
            
            AppsInToss.SendAnalytics("loading_skipped", skipData);
            
            // 강제 완료
            CompleteLoading();
        }
    }
    
    void OnRetryButtonClicked()
    {
        // 에러 패널 숨기기
        errorPanel.SetActive(false);
        
        // 로딩 재시작
        currentProgress = 0f;
        isLoadingComplete = false;
        
        if (loadingAnimator != null)
        {
            loadingAnimator.speed = 1f;
        }
        
        UpdateStatus("다시 시도하는 중...");
        
        // 재시도 이벤트 발생
        AppsInToss.SendEvent("loading_retry", new Dictionary<string, object>());
    }
    
    // 터치 입력 처리
    void Update()
    {
        if (config.enableTouchToSkip && canSkip && !isLoadingComplete)
        {
            if (Input.touchCount > 0 && Input.GetTouch(0).phase == TouchPhase.Began)
            {
                OnSkipButtonClicked();
            }
            
            // 마우스 클릭도 지원 (에디터 테스트용)
            if (Input.GetMouseButtonDown(0))
            {
                OnSkipButtonClicked();
            }
        }
    }
    
    // 공개 API
    public bool IsLoadingComplete()
    {
        return isLoadingComplete;
    }
    
    public float GetCurrentProgress()
    {
        return currentProgress;
    }
    
    public string GetCurrentStatus()
    {
        return currentStatus;
    }
    
    public void SetCustomTip(string tip)
    {
        if (tipText != null)
        {
            tipText.text = tip;
        }
    }
    
    void OnDestroy()
    {
        AppsInToss.OnEvent -= HandleAppsInTossEvent;
        AppsInToss.OnError -= HandleAppsInTossError;
    }
}
```

***

## 2. 로딩 화면 템플릿

### 기본 템플릿

```c#
public class BasicLoadingTemplate : MonoBehaviour
{
    [Header("기본 설정")]
    public Image backgroundImage;
    public Image logoImage;
    public Slider progressBar;
    public Text statusText;
    
    public void SetupBasicTemplate(Color brandColor, Sprite logo)
    {
        // 브랜드 색상 적용
        progressBar.fillRect.GetComponent<Image>().color = brandColor;
        
        // 로고 설정
        logoImage.sprite = logo;
        
        // 단순한 배경색
        backgroundImage.color = new Color(brandColor.r, brandColor.g, brandColor.b, 0.1f);
    }
}
```

### 고급 템플릿

```c#
public class AdvancedLoadingTemplate : MonoBehaviour
{
    [Header("고급 설정")]
    public ParticleSystem backgroundParticles;
    public Animator logoAnimator;
    public Image[] decorativeElements;
    public TextMeshProUGUI[] animatedTexts;
    
    [Header("애니메이션 설정")]
    public AnimationCurve fadeInCurve;
    public AnimationCurve scaleCurve;
    public float animationDuration = 2f;
    
    public void SetupAdvancedTemplate(AppsInTossLoadingManager.LoadingConfig config)
    {
        // 파티클 시스템 설정
        SetupParticles(config);
        
        // 로고 애니메이션 설정
        SetupLogoAnimation(config);
        
        // 장식 요소 애니메이션
        SetupDecorativeAnimations(config);
        
        // 텍스트 애니메이션
        SetupTextAnimations(config);
    }
    
    void SetupParticles(AppsInTossLoadingManager.LoadingConfig config)
    {
        if (backgroundParticles != null)
        {
            var main = backgroundParticles.main;
            main.startColor = config.primaryColor;
            main.startSize = 0.1f;
            
            var emission = backgroundParticles.emission;
            emission.rateOverTime = 50;
            
            var shape = backgroundParticles.shape;
            shape.shapeType = ParticleSystemShapeType.Rectangle;
            
            backgroundParticles.Play();
        }
    }
    
    void SetupLogoAnimation(AppsInTossLoadingManager.LoadingConfig config)
    {
        if (logoAnimator != null)
        {
            logoAnimator.SetFloat("Duration", config.logoAnimationDuration);
            logoAnimator.SetTrigger("StartAnimation");
        }
    }
    
    void SetupDecorativeAnimations(AppsInTossLoadingManager.LoadingConfig config)
    {
        for (int i = 0; i < decorativeElements.Length; i++)
        {
            StartCoroutine(AnimateDecorativeElement(decorativeElements[i], i * 0.2f));
        }
    }
    
    IEnumerator AnimateDecorativeElement(Image element, float delay)
    {
        yield return new WaitForSeconds(delay);
        
        element.color = new Color(element.color.r, element.color.g, element.color.b, 0f);
        
        float elapsedTime = 0f;
        while (elapsedTime < animationDuration)
        {
            elapsedTime += Time.deltaTime;
            float progress = fadeInCurve.Evaluate(elapsedTime / animationDuration);
            
            element.color = new Color(element.color.r, element.color.g, element.color.b, progress);
            element.transform.localScale = Vector3.one * scaleCurve.Evaluate(progress);
            
            yield return null;
        }
    }
    
    void SetupTextAnimations(AppsInTossLoadingManager.LoadingConfig config)
    {
        foreach (var text in animatedTexts)
        {
            StartCoroutine(AnimateText(text));
        }
    }
    
    IEnumerator AnimateText(TextMeshProUGUI text)
    {
        string originalText = text.text;
        text.text = "";
        
        for (int i = 0; i <= originalText.Length; i++)
        {
            text.text = originalText.Substring(0, i);
            yield return new WaitForSeconds(0.05f);
        }
    }
}
```

***

## 3. 에디터 도구

### 로딩 화면 프리뷰어

```c#
#if UNITY_EDITOR
using UnityEngine;
using UnityEditor;

[CustomEditor(typeof(AppsInTossLoadingManager))]
public class LoadingManagerEditor : Editor
{
    private float previewProgress = 0f;
    private bool isPreviewMode = false;
    
    public override void OnInspectorGUI()
    {
        DrawDefaultInspector();
        
        EditorGUILayout.Space();
        EditorGUILayout.LabelField("프리뷰 도구", EditorStyles.boldLabel);
        
        AppsInTossLoadingManager manager = target as AppsInTossLoadingManager;
        
        // 프리뷰 모드 토글
        isPreviewMode = EditorGUILayout.Toggle("프리뷰 모드", isPreviewMode);
        
        if (isPreviewMode)
        {
            // 진행률 슬라이더
            previewProgress = EditorGUILayout.Slider("진행률", previewProgress, 0f, 1f);
            
            if (Application.isPlaying && manager != null)
            {
                manager.UpdateProgress(previewProgress, $"테스트 진행률: {previewProgress * 100f:F0}%");
            }
            
            EditorGUILayout.Space();
            
            // 테스트 버튼들
            EditorGUILayout.BeginHorizontal();
            
            if (GUILayout.Button("에러 테스트"))
            {
                if (Application.isPlaying && manager != null)
                {
                    manager.ShowError("테스트 에러 메시지입니다.");
                }
            }
            
            if (GUILayout.Button("완료 테스트"))
            {
                if (Application.isPlaying && manager != null)
                {
                    manager.CompleteLoading();
                }
            }
            
            EditorGUILayout.EndHorizontal();
        }
        
        EditorGUILayout.Space();
        
        // 설정 검증 버튼
        if (GUILayout.Button("설정 검증"))
        {
            ValidateLoadingConfig(manager);
        }
        
        // 브랜딩 가이드라인 버튼
        if (GUILayout.Button("브랜딩 가이드라인 확인"))
        {
            ShowBrandingGuidelines();
        }
    }
    
    void ValidateLoadingConfig(AppsInTossLoadingManager manager)
    {
        var issues = new List<string>();
        
        // 필수 컴포넌트 체크
        if (manager.tossLogoImage == null)
            issues.Add("토스 로고 이미지가 설정되지 않았습니다.");
        
        if (manager.progressSlider == null && manager.config.showProgressBar)
            issues.Add("진행률 바가 활성화되었지만 Slider 컴포넌트가 없습니다.");
        
        // 브랜딩 체크
        if (manager.config.tossLogo == null)
            issues.Add("토스 로고 스프라이트가 설정되지 않았습니다.");
        
        // 결과 표시
        if (issues.Count == 0)
        {
            EditorUtility.DisplayDialog("검증 완료", "로딩 설정이 올바릅니다.", "확인");
        }
        else
        {
            string message = "다음 문제들을 해결해주세요:\n\n" + string.Join("\n", issues);
            EditorUtility.DisplayDialog("검증 실패", message, "확인");
        }
    }
    
    void ShowBrandingGuidelines()
    {
        string guidelines = @"AppsInToss 브랜딩 가이드라인:

1. 로고 사용
   - 토스 로고는 항상 게임 로고와 함께 표시
   - 최소 크기: 64x64 픽셀
   - 명확한 여백 확보

2. 색상 사용
   - 주 색상: 토스 블루 (#3182F7)
   - 보조 색상: 화이트 (#FFFFFF)
   - 배경: 그라디언트 권장

3. 애니메이션
   - 부드러운 전환 효과 사용
   - 과도한 움직임 피하기
   - 2초 이내 완료 권장

4. 텍스트
   - 한글: 본고딕 또는 시스템 기본
   - 영문: Roboto 또는 시스템 기본
   - 가독성 우선";
        
        EditorUtility.DisplayDialog("브랜딩 가이드라인", guidelines, "확인");
    }
}
#endif
```

***

## 4. 성능 최적화

### 로딩 성능 모니터

```c#
public class LoadingPerformanceMonitor : MonoBehaviour
{
    private float loadingStartTime;
    private Dictionary<string, float> phaseTimings = new Dictionary<string, float>();
    
    void Start()
    {
        loadingStartTime = Time.realtimeSinceStartup;
        AppsInToss.OnEvent += TrackLoadingPhases;
    }
    
    void TrackLoadingPhases(string eventName, Dictionary<string, object> data)
    {
        if (eventName.StartsWith("loading_"))
        {
            float currentTime = Time.realtimeSinceStartup - loadingStartTime;
            phaseTimings[eventName] = currentTime;
            
            Debug.Log($"로딩 단계: {eventName} - {currentTime:F2}초");
        }
        
        if (eventName == "loading_complete")
        {
            GeneratePerformanceReport();
        }
    }
    
    void GeneratePerformanceReport()
    {
        float totalTime = Time.realtimeSinceStartup - loadingStartTime;
        
        var report = new Dictionary<string, object>
        {
            {"total_loading_time", totalTime},
            {"phase_timings", phaseTimings},
            {"device_model", SystemInfo.deviceModel},
            {"device_memory", SystemInfo.systemMemorySize},
            {"graphics_device", SystemInfo.graphicsDeviceName}
        };
        
        AppsInToss.SendAnalytics("loading_performance", report);
        
        Debug.Log($"로딩 성능 보고서: 총 {totalTime:F2}초 소요");
    }
    
    void OnDestroy()
    {
        AppsInToss.OnEvent -= TrackLoadingPhases;
    }
}
```

브랜드 일관성을 유지하면서도 사용자가 기다리는 시간을 즐겁게 만드는 로딩 화면을 설계하세요.\
진행률과 상태를 명확히 표시하여 사용자 불안감을 해소하는 것이 중요해요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/ImpressionArea.md
---

# 컴포넌트 노출 감지하기

## `ImpressionArea`

`ImpressionArea` 는 특정 컴포넌트가 화면에 보이는지 여부를 감지해서 외부에 알려주는 컴포넌트예요. 이 컴포넌트를 사용해서 화면에 특정 컴포넌트가 보이면 로그를 수집하거나 애니메이션을 실행하는 구현을 쉽게 할 수 있어요.
화면에 보이는지 여부는 `useVisibility`의 반환값과 뷰포트(Viewport) 내에 표시되었는 지 알려주는 `IOScrollView`와 `InView` 컴포넌트로 감지해요. React에서 `ScrollView`를 사용하면 뷰가 화면에 보이지 않더라도, `ImpressionArea`를 사용하면 해당 뷰가 실제로 화면에 보일때만 이벤트를 발생시킬 수 있어요.

::: tip 유의하세요

`ImpressionArea`는 반드시 `IOScrollView` 안에서 사용해야 해요. 만약 `IOScrollView` 외부에서 사용해야 한다면, `UNSAFE__impressFallbackOnMount` 속성을 `true`로 설정해서 컴포넌트가 마운트될 때를 기준으로 감지할 수 있어요. 이 속성이 `false`로 설정된 상태에서 `IOScrollView` 외부에서 사용하면 `IOProviderMissingError`가 발생해요.

:::

## 시그니처

```typescript
function ImpressionArea(props: Props): ReactElement;
```

### 파라미터

값은 0부터 1 사이의 숫자로 설정하며, 0으로 설정하면 컴포넌트의 1px이라도 보일 때 이벤트가 발생해요. 반대로, 1로 설정하면 컴포넌트가 100% 화면에 노출될 때만 이벤트가 호출돼요.`IOScrollView`를 사용하지 않는 상황에서, 컴포넌트가 뷰포트(Viewport) 안에 있는지 판단할 수 없을 떼 유용해요. 예를 들어, `IOScrollView` 밖에 위치한 컴포넌트는 `true`로 설정하면 마운트 시점에 보여졌다고 판단해요.

### 반환 값

## 예제

### 기본 사용 예시

```tsx
import { useState } from 'react';
import { Button, Dimensions, Text, View } from 'react-native';
import { ImpressionArea, IOScrollView } from '@granite-js/react-native';

function ImpressionAreaExample() {
 const [isImpressionStart, setIsImpressionStart] = useState(false);

 return (
   <>
     <Text>{isImpressionStart ? 'Impression Start' : 'Impression End'}</Text>
       <IOScrollView
         style={{
           flex: 1,
           margin: 16,
           backgroundColor: 'white',
         }}
       >
       <View
         style={{
           height: Dimensions.get('screen').height,
           borderWidth: 1,
           borderColor: 'black',
         }}
       >
         <Text>Scroll to here</Text>
       </View>

       <ImpressionArea
         onImpressionStart={() => setIsImpressionStart(true)}
         onImpressionEnd={() => setIsImpressionStart(false)}
       >
         <Button title="Button" />
       </ImpressionArea>
     </IOScrollView>
   </>
 );
}
```

### 마운트 시점에 감지하는 예시

`ImpressionArea`가 `IOScrollView`와 같은 컴포넌트 내부에 위치하지 않을 때, `UNSAFE__impressFallbackOnMount`를 `true`로 설정하면 컴포넌트가 마운트될 때 화면에 보여진 것으로 간주해요.

```tsx
import { useState } from 'react';
import { Button, Dimensions, ScrollView, Text, View } from 'react-native';
import { ImpressionArea } from '@granite-js/react-native';

function ImpressionArea2Example() {
 const [isImpressionStart, setIsImpressionStart] = useState(false);

 return (
   <>
     <Text>{isImpressionStart ? 'Impression Start' : 'Impression End'}</Text>
     <ScrollView
       style={{
         flex: 1,
         margin: 16,
         backgroundColor: 'white',
       }}
     >
       <View
         style={{
           height: Dimensions.get('screen').height,
           borderWidth: 1,
           borderColor: 'black',
         }}
       >
         <Text>Scroll to here</Text>
       </View>

       <ImpressionArea
         UNSAFE__impressFallbackOnMount={true}
         onImpressionStart={() => setIsImpressionStart(true)}
         onImpressionEnd={() => setIsImpressionStart(false)}
       >
         <Button title="Button" />
       </ImpressionArea>
     </ScrollView>
   </>
 );
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/분석/LoggingImpression.md
---

# 컴포넌트 노출 기록하기

## `LoggingImpression`

`LoggingImpression` 는 요소가 뷰포트에 표시되었는지 판단하고 로그를 남기는 컴포넌트예요. 예를 들어, 스크롤 아래에 있는 요소가 뷰포트에 표시되었을 때를 감지해 로그를 남겨요.

## 시그니처

```typescript
function LoggingImpression({ enabled, impression: impressionType, ...props }: LoggingImpressionProps): import("react/jsx-runtime").JSX.Element;
```

## 예제

### 컴포넌트의 노출 정보를 자동으로 수집하는 예시

```tsx
import { Analytics } from '@apps-in-toss/framework';

// 영역 안의 노출 정보를 자동으로 수집해요.
function TrackElements() {
  return (
    <Analytics.Impression>
      <Text>Hello</Text>
    </Analytics.Impression>
  );
}
```

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/start/wasm-split.md'
---
# 코드 분할 도구 사용 가이드

AppsInToss Unity 게임에서 WebAssembly 코드 분할을 통해 초기 로딩 속도를 개선하고 메모리 사용량을 최적화하는 방법을 다뤄요.

***

## 1. WASM 코드 분할 개념

### 코드 분할 전략

```
📦 WASM 코드 분할 구조
├── Core Module (핵심 모듈)
│   ├── 게임 엔진 핵심
│   ├── 렌더링 시스템
│   ├── 입력 관리
│   └── 기본 물리 연산
├── Feature Modules (기능별 모듈)
│   ├── AI 시스템
│   ├── 네트워킹
│   ├── 오디오 처리
│   └── 고급 물리 연산
├── Content Modules (콘텐츠 모듈)
│   ├── 레벨별 로직
│   ├── 캐릭터 시스템
│   ├── 스킬 시스템
│   └── UI 시스템
└── Platform Modules (플랫폼별)
    ├── AppsInToss 통합
    ├── 소셜 기능
    ├── 결제 시스템
    └── 광고 시스템
```

### WASM 분할 매니저

```c#
using UnityEngine;
using System.Collections;
using System.Collections.Generic;
using System.Runtime.InteropServices;

public class WasmSplitManager : MonoBehaviour
{
    public static WasmSplitManager Instance { get; private set; }
    
    [System.Serializable]
    public class WasmModule
    {
        public string moduleName;
        public string moduleUrl;
        public ModulePriority priority;
        public string[] dependencies;
        public bool preload = false;
        public float estimatedSizeMB;
        public ModuleState state = ModuleState.NotLoaded;
    }
    
    public enum ModulePriority
    {
        Critical = 0,  // 게임 시작 전 필수
        High = 1,      // 초기 로딩 시 필요
        Medium = 2,    // 기능 사용 시 로딩
        Low = 3,       // 선택적 로딩
        OnDemand = 4   // 요청 시에만 로딩
    }
    
    public enum ModuleState
    {
        NotLoaded,
        Loading,
        Loaded,
        Failed
    }
    
    [Header("WASM 모듈 설정")]
    public WasmModule[] wasmModules;
    
    [Header("로딩 설정")]
    public bool enableAsyncLoading = true;
    public int maxConcurrentLoads = 2;
    public float loadTimeoutSeconds = 30f;
    
    // 내부 상태
    private Dictionary<string, WasmModule> moduleMap = new Dictionary<string, WasmModule>();
    private HashSet<string> loadingModules = new HashSet<string>();
    private Queue<WasmModule> loadQueue = new Queue<WasmModule>();
    private int activeLoads = 0;
    
    void Awake()
    {
        if (Instance == null)
        {
            Instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeWasmSplit();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    void InitializeWasmSplit()
    {
        // 모듈 맵 생성
        foreach (var module in wasmModules)
        {
            moduleMap[module.moduleName] = module;
        }
        
        // Critical 모듈들 즉시 로딩 시작
        LoadCriticalModules();
        
        // 백그라운드 로딩 시작
        StartCoroutine(ProcessLoadQueue());
        
        Debug.Log("WASM 코드 분할 시스템 초기화 완료");
    }
    
    void LoadCriticalModules()
    {
        var criticalModules = System.Array.FindAll(wasmModules, 
            m => m.priority == ModulePriority.Critical);
        
        foreach (var module in criticalModules)
        {
            QueueModuleLoad(module.moduleName);
        }
        
        Debug.Log($"Critical 모듈 로딩 시작: {criticalModules.Length}개");
    }
    
    public void QueueModuleLoad(string moduleName)
    {
        if (moduleMap.ContainsKey(moduleName) && 
            moduleMap[moduleName].state == ModuleState.NotLoaded &&
            !loadingModules.Contains(moduleName))
        {
            loadQueue.Enqueue(moduleMap[moduleName]);
        }
    }
    
    IEnumerator ProcessLoadQueue()
    {
        while (true)
        {
            while (loadQueue.Count > 0 && activeLoads < maxConcurrentLoads)
            {
                var module = loadQueue.Dequeue();
                StartCoroutine(LoadWasmModule(module));
            }
            
            yield return new WaitForSeconds(0.1f);
        }
    }
    
    IEnumerator LoadWasmModule(WasmModule module)
    {
        loadingModules.Add(module.moduleName);
        module.state = ModuleState.Loading;
        activeLoads++;
        
        Debug.Log($"WASM 모듈 로딩 시작: {module.moduleName}");
        float startTime = Time.realtimeSinceStartup;
        
        // 의존성 체크
        yield return StartCoroutine(EnsureDependencies(module));
        
        // 실제 모듈 로딩
        bool loadSuccess = false;
        
#if UNITY_WEBGL && !UNITY_EDITOR
        // WebGL에서 실제 WASM 모듈 로딩
        loadSuccess = yield return StartCoroutine(LoadWasmModuleWebGL(module));
#else
        // 에디터/다른 플랫폼에서는 시뮬레이션
        yield return new WaitForSeconds(0.5f); // 로딩 시뮬레이션
        loadSuccess = true;
#endif
        
        // 로딩 결과 처리
        float loadTime = Time.realtimeSinceStartup - startTime;
        
        if (loadSuccess)
        {
            module.state = ModuleState.Loaded;
            OnModuleLoadSuccess(module, loadTime);
        }
        else
        {
            module.state = ModuleState.Failed;
            OnModuleLoadFailed(module, loadTime);
        }
        
        loadingModules.Remove(module.moduleName);
        activeLoads--;
    }
    
    IEnumerator EnsureDependencies(WasmModule module)
    {
        foreach (var dependency in module.dependencies)
        {
            if (moduleMap.ContainsKey(dependency))
            {
                var depModule = moduleMap[dependency];
                
                if (depModule.state == ModuleState.NotLoaded)
                {
                    // 의존성 모듈을 먼저 로딩
                    yield return StartCoroutine(LoadWasmModule(depModule));
                }
                else if (depModule.state == ModuleState.Loading)
                {
                    // 의존성 모듈 로딩 완료 대기
                    while (depModule.state == ModuleState.Loading)
                    {
                        yield return new WaitForSeconds(0.1f);
                    }
                }
                
                if (depModule.state == ModuleState.Failed)
                {
                    Debug.LogError($"의존성 모듈 로딩 실패: {dependency}");
                    yield break;
                }
            }
        }
    }
    
#if UNITY_WEBGL && !UNITY_EDITOR
    IEnumerator LoadWasmModuleWebGL(WasmModule module)
    {
        // JavaScript와 상호작용하여 WASM 모듈 로딩
        string loadCommand = $"loadWasmModule('{module.moduleName}', '{module.moduleUrl}')";
        
        // JS 함수 호출
        Application.ExternalCall("eval", loadCommand);
        
        // 로딩 완료 대기
        float timeout = Time.realtimeSinceStartup + loadTimeoutSeconds;
        
        while (Time.realtimeSinceStartup < timeout)
        {
            // JS에서 로딩 상태 확인
            string status = GetWasmModuleStatus(module.moduleName);
            
            if (status == "loaded")
            {
                yield return true;
            }
            else if (status == "failed")
            {
                yield return false;
            }
            
            yield return new WaitForSeconds(0.1f);
        }
        
        // 타임아웃
        Debug.LogError($"WASM 모듈 로딩 타임아웃: {module.moduleName}");
        yield return false;
    }
    
    [DllImport("__Internal")]
    private static extern string GetWasmModuleStatus(string moduleName);
#endif
    
    void OnModuleLoadSuccess(WasmModule module, float loadTime)
    {
        Debug.Log($"WASM 모듈 로딩 성공: {module.moduleName} ({loadTime:F2}초)");
        
        // 성공 이벤트 발송
        AppsInToss.SendEvent("wasm_module_loaded", new Dictionary<string, object>
        {
            {"module_name", module.moduleName},
            {"load_time", loadTime},
            {"estimated_size_mb", module.estimatedSizeMB}
        });
        
        // 분석 데이터 전송
        SendModuleAnalytics(module, true, loadTime);
        
        // High 우선순위 모듈들 자동 로딩
        TriggerHighPriorityLoading();
    }
    
    void OnModuleLoadFailed(WasmModule module, float loadTime)
    {
        Debug.LogError($"WASM 모듈 로딩 실패: {module.moduleName}");
        
        // 실패 이벤트 발송
        AppsInToss.SendEvent("wasm_module_failed", new Dictionary<string, object>
        {
            {"module_name", module.moduleName},
            {"load_time", loadTime}
        });
        
        // 분석 데이터 전송
        SendModuleAnalytics(module, false, loadTime);
        
        // 재시도 로직 (중요한 모듈만)
        if (module.priority <= ModulePriority.High)
        {
            StartCoroutine(RetryModuleLoad(module, 5f));
        }
    }
    
    void TriggerHighPriorityLoading()
    {
        var highPriorityModules = System.Array.FindAll(wasmModules,
            m => m.priority == ModulePriority.High && 
                 m.state == ModuleState.NotLoaded);
        
        foreach (var module in highPriorityModules)
        {
            QueueModuleLoad(module.moduleName);
        }
    }
    
    IEnumerator RetryModuleLoad(WasmModule module, float delay)
    {
        yield return new WaitForSeconds(delay);
        
        module.state = ModuleState.NotLoaded;
        QueueModuleLoad(module.moduleName);
        
        Debug.Log($"WASM 모듈 재시도: {module.moduleName}");
    }
    
    void SendModuleAnalytics(WasmModule module, bool success, float loadTime)
    {
        var analyticsData = new Dictionary<string, object>
        {
            {"module_name", module.moduleName},
            {"priority", module.priority.ToString()},
            {"estimated_size_mb", module.estimatedSizeMB},
            {"success", success},
            {"load_time", loadTime},
            {"device_model", SystemInfo.deviceModel},
            {"browser_info", GetBrowserInfo()},
            {"timestamp", System.DateTime.UtcNow.ToString("o")}
        };
        
        AppsInToss.SendAnalytics("wasm_module_load", analyticsData);
    }
    
    string GetBrowserInfo()
    {
#if UNITY_WEBGL && !UNITY_EDITOR
        return Application.ExternalEval("navigator.userAgent");
#else
        return "Editor";
#endif
    }
    
    // 공개 API
    public bool IsModuleLoaded(string moduleName)
    {
        return moduleMap.ContainsKey(moduleName) && 
               moduleMap[moduleName].state == ModuleState.Loaded;
    }
    
    public bool IsModuleLoading(string moduleName)
    {
        return loadingModules.Contains(moduleName);
    }
    
    public ModuleState GetModuleState(string moduleName)
    {
        return moduleMap.ContainsKey(moduleName) ? 
               moduleMap[moduleName].state : 
               ModuleState.NotLoaded;
    }
    
    public void RequestModuleLoad(string moduleName)
    {
        if (moduleMap.ContainsKey(moduleName))
        {
            var module = moduleMap[moduleName];
            if (module.priority >= ModulePriority.Medium)
            {
                QueueModuleLoad(moduleName);
            }
        }
    }
    
    public float GetTotalLoadProgress()
    {
        int totalModules = wasmModules.Length;
        int loadedModules = 0;
        
        foreach (var module in wasmModules)
        {
            if (module.state == ModuleState.Loaded)
            {
                loadedModules++;
            }
        }
        
        return totalModules > 0 ? (float)loadedModules / totalModules : 1f;
    }
    
    public string[] GetLoadedModules()
    {
        var loadedModules = new List<string>();
        
        foreach (var kvp in moduleMap)
        {
            if (kvp.Value.state == ModuleState.Loaded)
            {
                loadedModules.Add(kvp.Key);
            }
        }
        
        return loadedModules.ToArray();
    }
}
```

***

## 2. JavaScript 통합

### WASM 로더 JavaScript

```javascript
// wasm-loader.js
class WasmModuleLoader {
    constructor() {
        this.loadedModules = new Map();
        this.loadingModules = new Map();
    }
    
    async loadWasmModule(moduleName, moduleUrl) {
        if (this.loadedModules.has(moduleName)) {
            return true;
        }
        
        if (this.loadingModules.has(moduleName)) {
            return await this.loadingModules.get(moduleName);
        }
        
        console.log(`Loading WASM module: ${moduleName}`);
        
        const loadPromise = this.doLoadModule(moduleName, moduleUrl);
        this.loadingModules.set(moduleName, loadPromise);
        
        try {
            const result = await loadPromise;
            this.loadedModules.set(moduleName, result);
            this.loadingModules.delete(moduleName);
            
            console.log(`WASM module loaded successfully: ${moduleName}`);
            return true;
        } catch (error) {
            console.error(`Failed to load WASM module: ${moduleName}`, error);
            this.loadingModules.delete(moduleName);
            return false;
        }
    }
    
    async doLoadModule(moduleName, moduleUrl) {
        const response = await fetch(moduleUrl);
        
        if (!response.ok) {
            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        
        const arrayBuffer = await response.arrayBuffer();
        const wasmModule = await WebAssembly.compile(arrayBuffer);
        const wasmInstance = await WebAssembly.instantiate(wasmModule);
        
        // Unity WebGL 런타임에 모듈 등록
        if (window.unityInstance && window.unityInstance.Module) {
            window.unityInstance.Module.wasmModules = window.unityInstance.Module.wasmModules || {};
            window.unityInstance.Module.wasmModules[moduleName] = wasmInstance;
        }
        
        return wasmInstance;
    }
    
    getModuleStatus(moduleName) {
        if (this.loadedModules.has(moduleName)) {
            return 'loaded';
        } else if (this.loadingModules.has(moduleName)) {
            return 'loading';
        } else {
            return 'not_loaded';
        }
    }
    
    isModuleLoaded(moduleName) {
        return this.loadedModules.has(moduleName);
    }
    
    getModule(moduleName) {
        return this.loadedModules.get(moduleName);
    }
}

// 전역 인스턴스
const wasmLoader = new WasmModuleLoader();

// Unity에서 호출할 함수들
window.loadWasmModule = (moduleName, moduleUrl) => {
    wasmLoader.loadWasmModule(moduleName, moduleUrl);
};

window.getWasmModuleStatus = (moduleName) => {
    return wasmLoader.getModuleStatus(moduleName);
};

window.isWasmModuleLoaded = (moduleName) => {
    return wasmLoader.isModuleLoaded(moduleName);
};
```

***

## 3. 에디터 도구

### WASM 분할 분석기

```c#
#if UNITY_EDITOR
using UnityEngine;
using UnityEditor;
using System.IO;
using System.Collections.Generic;

public class WasmSplitAnalyzer : EditorWindow
{
    private WasmSplitManager splitManager;
    private Vector2 scrollPosition;
    private bool showAnalysis = true;
    
    [MenuItem("AppsInToss/WASM 분할 분석기")]
    public static void ShowWindow()
    {
        GetWindow<WasmSplitAnalyzer>("WASM 분할 분석기");
    }
    
    void OnGUI()
    {
        GUILayout.Label("WASM 코드 분할 분석", EditorStyles.boldLabel);
        
        splitManager = EditorGUILayout.ObjectField(
            "WASM Split Manager", 
            splitManager, 
            typeof(WasmSplitManager), 
            true
        ) as WasmSplitManager;
        
        if (splitManager == null)
        {
            EditorGUILayout.HelpBox("WasmSplitManager를 선택해주세요.", MessageType.Warning);
            return;
        }
        
        EditorGUILayout.Space();
        
        if (GUILayout.Button("모듈 분석 실행"))
        {
            AnalyzeModules();
        }
        
        if (GUILayout.Button("최적화 제안 생성"))
        {
            GenerateOptimizationSuggestions();
        }
        
        EditorGUILayout.Space();
        
        showAnalysis = EditorGUILayout.Foldout(showAnalysis, "분석 결과");
        
        if (showAnalysis)
        {
            scrollPosition = EditorGUILayout.BeginScrollView(scrollPosition);
            DrawModuleAnalysis();
            EditorGUILayout.EndScrollView();
        }
    }
    
    void AnalyzeModules()
    {
        Debug.Log("=== WASM 모듈 분석 시작 ===");
        
        float totalSizeMB = 0f;
        var priorityGroups = new Dictionary<WasmSplitManager.ModulePriority, List<WasmSplitManager.WasmModule>>();
        
        foreach (var module in splitManager.wasmModules)
        {
            totalSizeMB += module.estimatedSizeMB;
            
            if (!priorityGroups.ContainsKey(module.priority))
            {
                priorityGroups[module.priority] = new List<WasmSplitManager.WasmModule>();
            }
            priorityGroups[module.priority].Add(module);
        }
        
        Debug.Log($"총 모듈 수: {splitManager.wasmModules.Length}");
        Debug.Log($"총 예상 크기: {totalSizeMB:F2}MB");
        
        foreach (var group in priorityGroups)
        {
            float groupSize = 0f;
            foreach (var module in group.Value)
            {
                groupSize += module.estimatedSizeMB;
            }
            
            Debug.Log($"{group.Key} 우선순위: {group.Value.Count}개 모듈, {groupSize:F2}MB");
        }
        
        AnalyzeDependencies();
    }
    
    void AnalyzeDependencies()
    {
        Debug.Log("\n=== 의존성 분석 ===");
        
        var dependencyCount = new Dictionary<string, int>();
        
        foreach (var module in splitManager.wasmModules)
        {
            foreach (var dependency in module.dependencies)
            {
                dependencyCount[dependency] = dependencyCount.ContainsKey(dependency) ? 
                                              dependencyCount[dependency] + 1 : 1;
            }
        }
        
        foreach (var kvp in dependencyCount)
        {
            if (kvp.Value > 1)
            {
                Debug.Log($"공통 의존성: {kvp.Key} ({kvp.Value}개 모듈에서 참조)");
            }
        }
    }
    
    void GenerateOptimizationSuggestions()
    {
        var suggestions = new List<string>();
        
        // 크기 기반 제안
        foreach (var module in splitManager.wasmModules)
        {
            if (module.estimatedSizeMB > 5f && module.priority == WasmSplitManager.ModulePriority.Critical)
            {
                suggestions.Add($"{module.moduleName}: 크기가 큰 Critical 모듈입니다. 우선순위를 낮추거나 분할을 고려하세요.");
            }
            
            if (module.dependencies.Length > 3)
            {
                suggestions.Add($"{module.moduleName}: 의존성이 많습니다. 구조 개선을 고려하세요.");
            }
        }
        
        // 결과 표시
        if (suggestions.Count > 0)
        {
            string message = "최적화 제안:\n\n" + string.Join("\n\n", suggestions);
            EditorUtility.DisplayDialog("최적화 제안", message, "확인");
        }
        else
        {
            EditorUtility.DisplayDialog("최적화 분석", "현재 구조가 잘 최적화되어 있습니다.", "확인");
        }
    }
    
    void DrawModuleAnalysis()
    {
        if (splitManager.wasmModules == null) return;
        
        foreach (var module in splitManager.wasmModules)
        {
            EditorGUILayout.BeginVertical("box");
            
            EditorGUILayout.LabelField(module.moduleName, EditorStyles.boldLabel);
            EditorGUILayout.LabelField($"우선순위: {module.priority}");
            EditorGUILayout.LabelField($"예상 크기: {module.estimatedSizeMB:F2}MB");
            EditorGUILayout.LabelField($"의존성: {module.dependencies.Length}개");
            
            if (Application.isPlaying && WasmSplitManager.Instance != null)
            {
                var state = WasmSplitManager.Instance.GetModuleState(module.moduleName);
                EditorGUILayout.LabelField($"상태: {state}");
            }
            
            EditorGUILayout.EndVertical();
        }
    }
}
#endif
```

WASM 코드 분할을 통해 초기 로딩 시간을 단축하고 필요한 기능만 점진적으로 로딩하여 메모리 효율성을 높이세요.\
의존성 관계를 명확히 하고 우선순위에 따른 로딩 전략을 수립하는 것이 중요해요.

---

---
url: 'https://developers-apps-in-toss.toss.im/ads/console.md'
description: '인앱 광고 콘솔 사용 가이드입니다. 설정, 관리, 모니터링 방법을 확인하세요.'
---

# 콘솔 가이드

::: tip  새로운 광고 구조 (인앱광고 2.0)가 오픈 되었어요.

* 기존의 unitID 를 사용하는 파트너사의 경우 2025년 11월 말까지 순차적으로 마이그레이션을 진행해 주세요.
* 기존(채널톡 발급 등) 에 사용하던 unitID 와 1 : 1 로 매칭하여 변경이 필요하며, 발급한 모든 광고를 빠짐없이 활용해 주셔야 해요.
  :::

인앱광고(In App Ads) 연동을 위해서는 **약관동의 → 정산 정보 입력 → 광고 그룹 생성** 절차가 필요해요.\
이 중 **정산 정보 입력**은 **앱인토스팀 검토**가 필요하며, **영업일 기준 2~3일**이 소요돼요.

![](/assets/ads_flow_0.LhT_Rt7A.png)

## 1. 약관 동의

인앱광고 연동을 위해서는 **약관 동의가** 필요해요.\
약관동의는 앱인토스 콘솔에서 진행이 가능하며, **대표관리자로 지정된 분**의 계정에서만 가능해요.

* **약관 동의 방법**
  * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 ‘인앱광고’ 선택 후 ‘약관 확인하기’ 를 클릭 하여 아래 화면에서 약관 동의 진행

![](/assets/ads_console_1.ScWu-JEC.png)

## **2. 정산 정보 입력하기**

인앱광고를 연동하게 될 경우 수익화가 진행 되기 때문에 정산 받을 정보를 입력해야 해요.\
워크스페이스의 **정보** 탭에서 정산 정보를 등록 후 **검토 요청**이 필요하고, **영업일 기준 평균 2~3일** 소요돼요.

* **정산 정보 메뉴 접속 방법**
  * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 상단 메뉴 중 ‘정보’ 선택 후 정산 정보 메뉴 내 ‘등록하기’ 진행

![](/assets/ads_console_2.DISVd74s.png)

![](/assets/ads_console_3.CxHTgRen.png)

::: tip 예금주명은 통장 사본에 기재된 이름과 모두 똑같이 입력해 주세요.
:::

## 3. 광고 그룹 생성하기

대표 관리자의 인앱광고 약관 동의와 정산 정보 검토가 모두 완료되었다면 ‘광고 그룹’을 생성할 수 있어요.\
앱인토스에서 제공하는 인앱광고는 **‘구글 애드몹 광고 정책’** 을 따르고 있으며, 관련 정책을 꼭 준수를 해주세요.

* **접속 방법**
  * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 ‘인앱광고’ 선택 → 우측 상단 **‘+ 광고 그룹 생성하기’** 선택

![](/assets/ads_console_4.CLxsdWYa.png)

### ① 광고 그룹 이름

광고 그룹 이름은 어떤 유형의 광고인지, 광고의 위치 등을 고려하여 관리가 용이하게 설정하시는 것을 권장 드려요.

### ② 광고 유형

* **전면 광고**
  * 화면 전체에 노출 되는 광고예요.
  * 별도의 리워드를 설정은 하지 않아도 돼요.
* **리워드 광고**
  * 광고를 시청한 유저에게 리워드를 제공할 수 있어요.\
    예) 아이템, 게임 이어하기 등

### ③ 보상 설정

* 리워드 광고를 선택한 경우에만 입력해 주세요.
* 유저가 받는 보상의 이름과 보상의 수량 설정이 필요해요.\
  (예시)\
  \*서비스 내 보상 단위 : 게임 이어하기\
  \*수량 및 금액 : 1

### ④ 미디에이션 설정

* 카테고리 및 하위 카테고리는 ‘앱 정보’ 상의 등록해 주신 카테고리로 자동 세팅돼요.
  * 원하실 경우 다른 카테고리로 수정할 수 있지만 앱 정보의 카테고리가 연동되어 변경되지는 않고 광고 그룹 생성에만 활용돼요.
* 카테고리에 맞게 광고 네트워크가 설정되며 이를 확인할 수 있어요.
  * 광고 네트워크 및 폭포식은 별도 설정이 불가하며 설정된 값을 확인할 수만 있어요.

![](/assets/ads_console_5.CWS2_L0k.png)

::: tip  꼭 확인해 주세요

* 광고 그룹 ID는 구글에 등록되기 까지 최대 2시간까지 소요될 수 있어요.
* 광고 그룹 생성 후 제공되는 광고 그룹 ID를 활용하여 개발을 진행해 주세요.\
  → [**개발하기 보러 가기**](/ads/develop.md)
  :::

## 4. 광고 성과 및 정산 내역

개발을 완료한 인앱광고 (IAA) 의 성과를 확인할 수 있어요.

**접속 방법**

* 성과 : 앱인토스 콘솔 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 ‘인앱광고 2.0’ → 상단 탭 중 ‘성과’
* 정산 내역 : 성과 : 앱인토스 콘솔 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 ‘인앱광고 2.0’ → 상단 탭 중 ‘정산 내역’

### **광고 성과**

* 광고 성과는 기간 및 OS를 설정해서 총 광고 노출 수, eCPM, 총 예상 수익을 확인할 수 있어요.
* 성과는 **매주 월요일 16시 이후 순차적으로 업데이트**가 되고 있어요.

::: tip  eCPM 이란?

* 광고가 노출되는 1,000회당 발생되는 수익을 뜻해요.
* 예를 들어 ‘총 노출 수’ 가 300이고, eCPM 이 60,000원이라면 예상 수익은 18,000원이에요.
* 1,000회 노출되었을 때 수익이 60,000원으로 예상되는 노출 1회 당 수익이 60원이며, 실제 노출된 수치는 300이기 때문이에요.
  :::

### 정산 내역

* 정산 내역은 1일~말일까지의 수익을 익월 1일에 업데이트가 되고 있어요.
* 익월 1일에 업데이트된 수익금은 해당 월 말일에 입금이 되고 있어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/iap/console.md'
---
# 콘솔 가이드

::: tip 인앱결제를 진행하기 위해서는 다음과 같은 준비가 필요해요

* 대표 관리자의 인앱결제에 대한 약관 동의
* KYC 진행 및 검토 (영업일 기준 3~4일 소요)
* 토스 로그인 기능 연동 필요
  :::

![](/assets/iap_flow_0.Dczzs6U6.png)

## 1. 약관 동의

인앱 상품 등록을 위해서는 **약관 동의가** 필요해요.\
약관  동의는 앱인토스 콘솔에서 진행할 수 있으며, **대표 관리자로 지정된 분**의 계정에서만 가능해요.

* **약관 동의 방법**
  * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 ‘인앱결제’ 선택 후 ‘약관 확인하기’를 클릭하여 아래 화면에서 약관 동의 진행

![](/assets/iap_contract_1.BkRhCmUZ.png)

## 2. KYC 진행하기

인앱결제 사용을 하시는 경우 특정금융정보법에 따라 **본인확인제도(Know Your Customer)** 절차가 필수로 필요해요.\
‘**`+ 등록하기`**’ 를 눌러서 안내에 따라 작성 후 **검토를 요청**하면, **영업일 기준 3~4일** 내에 승인되고 이후에 상품을 등록할 수 있어요.
![](/assets/iap_kyc.BT9vO9Hg.png)

## 3. 상품 등록하기

KYC 검토가 모두 완료된 이후 **`+ 등록하기`** 로 인앱결제 **상품을 등록**해 주세요.
![](/assets/iap_product_reg_1.CsumbO7j.png)

![](/assets/iap_product_reg_2.B_huYsv_.png)

상품 등록 시 사용자에게 정확한 구매 정보를 전달하고 원활한 운영을 위해 아래의 내용을 준수하여 입력해 주세요.

### 상품 유형

* 소모품 : 사용하면 소진이 되는 품목으로 다시 사용하려면 재구매가 필요해요. (예: 게임 아이템, 내부 재화 충전, 1회 이용권 등)
* 비소모품 : 한 번 구매하면 영구적으로 사용할 수 있어요. (예: 광고 제거, 소장형 콘텐츠 등)
* 단, 현금성/환가성/토스 포인트를 결합해서 제공하는 상품은 판매할 수 없어요.

### 상품명

* 사용자가 얻게 되는 기능·조건과 일치해야 해요.
* 과장하거나 기만하는 표현을 쓰면 안 돼요. (예: 제공 기간이 있음에도 “무제한”)

### 상품 설명 (유저 미노출 영역)

* 상품의 제공 조건(시점, 기간, 횟수)을 정확히 적어야 해요.
* 상품의 제공 범위(예: 광고 제거의 경우 어떤 광고가 제거되는지)를 명확히 표시해야 해요.
* 상품 사용 시 유저가 얻게 되는 효용을 설명해야 해요.

### 공급가

* VAT가 제외된 공급 기준 금액이에요.
* 최소 400원 ~ 최대 1,400,000원까지 설정할 수 있어요.
* 10원 단위로만 입력이 가능해요.
* 공급가를 입력하면 판매가는 자동으로 설정돼요.
  * 반대로 판매가 입력 시 공급가가 설정 되는 것은 현재 지원하지 않아요.

### 판매가

* 사용자가 앱에서 실제로 결제하는 최종 금액이며, 공급가에 VAT가 더해진 가격이에요.

### 상품 이미지

* 상품 식별을 위한 텍스트(“30일 이용권”, “100코인”)를 넣을 수 있어요.
* 광고성·이벤트성 문구를 사용할 경우, 이벤트 진행 기간을 함께 표시해야 해요.
* 해상도는 1024×1024px로 등록해야 해요.
* 저작권 문제가 없는 이미지만 사용해야 해요. (파트너사에서 확보해야 해요.)
* 그 외 선정적이거나 폭력적이거나 불쾌감을 주는 등의 이미지는 사용할 수 없어요.

### 노출 여부

* 심사 승인 후 바로 상품을 노출하려면 체크박스를 선택해주세요. 선택하지 않아도 나중에 직접 노출을 시작할 수 있어요.

등록이 모두 완료 되었다면, 실제 판매가 시작된 이후 해당 상품을 기준으로 주문 내역과 정산 내역을 확인할 수 있어요.

![](/assets/iap_product_reg_3.BSgLTFiv.png)

## 4. 환불하기

::: tip 애플과 구글의 환불 정책
**애플**

* 모든 환불은 **Apple이 직접 판단/승인**해요(파트너사 권한 없음).
* 애플은 환불 요청 자체가 불가하며, 결제 상태 조회 API만 제공돼요.

**구글**

* 사용자가 토스 앱에서 직접 환불 요청을 할 수 있고, 파트너사에서는 앱인토스 콘솔에서 환불 신청 내역을 확인 후 처리할 수 있어요.
* 단, 최종 승인 및 거절은 구글이 결정해요.
  :::

인앱결제로 결제한 사용자는 토스 앱에서 ‘환불받기’ 버튼으로 사유를 선택해 환불을 요청할 수 있어요.\
파트너사는 앱인토스 콘솔에서 **환불 내역**에서 요청을 **승인/반려**할 수 있습니다.

* **토스 앱에서 환불받기 접속 방법**
  * 토스 앱 → 오른쪽 아래 ‘전체’ 또는 ‘찾기’ → ‘게임’ 선택 → 상단의 게임 프로필 ‘닉네임’ 선택 → 구매 내역 → 환불 원하는 결제 내역 선택 → ‘환불받기’ 선택 후 접수

### \[안드로이드 환불 방법]

![환불 방법 관련 (안드로이드).png](/assets/iap_refund_1.DSxUEtlz.png)

### \[iOS 환불 방법]

![환불 방법 관련 (iOS).png](/assets/iap_refund_2.C91PbCFF.png)

**안드로이드 OS** 사용자가 앱에서 환불 요청을 한 경우 아래 화면과 같이 요청 내역을 앱인토스 콘솔에서 확인할 수 있어요.

* 결과 사용자에게 **푸시 알림**으로 발송되며, 사용자 **주문 상세**에서도 확인돼요.
* 파트너사 또는 Google Play가 **환불 거절**한 경우에도 알림이 발송돼요.

iOS 사용자의 경우 환불은 애플에 권한이 있기 때문에 결제 조회만 가능해요.

### \[인앱결제 - 결제 내역]

유저가 미니앱에서 결제한 상품 내역이에요.

![](/assets/iap_console_1.Dck5mDlW.png)

### \[인앱결제 환불 내역 - 환불 요청]

유저가 환불을 요청한 내역이에요. 환불 요청사유를 확인하고 **`요청 반려`** 및 **`요청 승인`** 을 할 수 있어요.

![](/assets/iap_console_2.qX4hWGjk.png)

### \[인앱결제 환불 내역 - 요청 승인]

파트너사가 환불 요청을 승인한 내역이에요. 요청을 승인하면, 앱마켓에 심사가 요청돼요.

![](/assets/iap_console_3.CmJkGvYI.png)

### \[인앱결제 환불 내역 - 환불 반려]

파트너사가 환불 요청을 반려하건, 앱마켓에서 환불을 반려한 내역이에요.

![](/assets/iap_console_4.CRZ2WVgp.png)

### \[인앱결제 환불 내역 - 환불 완료]

앱마켓에서 환불이 완료된 내역이에요.

![](/assets/iap_console_5.YgH3glRE.png)

## 5. 성과

개발∙연동이 완료된 인앱결제(IAP)의 **성과 지표를 한눈에 확인**할 수 있어요.\
매출 흐름과 유저의 결제 행동을 파악해 상품 운영에 활용해 보세요.

* 매출 데이터와 결제 유저 데이터를 확인할 수 있어요.
  * 총 결제 금액, 총 매출, 결제자당 평균 매출, 결제 유저당 매출
  * 활성 유저 수, 결제 유저 수, 신규 결제 유저 수, 재결제 유저 수, 결제율, 최종 전환율
* 성과 데이터는 D+1 오전 8시 이후부터 순차적으로 업데이트돼요.

:::: tabs

::: tab "DEFAULT"
![](/assets/iap_console_6.kp3oKiRo.png)
:::

::: tab "OS별로 보기"
![](/assets/iap_console_7.C5AnSPHZ.png)
:::

## ::::

## **자주 묻는 질문**

### **Q. 인앱결제 수수료는 어떻게 되나요?**

* 인앱결제 수수료는 앱마켓 수수료 15% (향후 매출에 따라 변동 가능) + 토스 수수료 5%가 적용돼요. 자세한 내용은 정산 이해하기 메뉴의 **[‘인앱결제’](/settlement/intro.html#_3-인앱-결제-수수료)** 항목을 확인해 주세요.

### Q. 인앱결제 테스트를 하고 싶어요.

* 인앱결제 테스트 환경은 추후 제공이 될 예정이에요. 제공될 경우 콘솔 및 개발자 커뮤니티의 ‘공지 사항’ 을 통해 안내해 드릴게요.

### Q. 사용자가 환불을 희망할 경우 어떻게 해야 하나요?

* iOS 사용자의 경우 애플 고객센터로 안내해 주세요. (애플에 모든 권한이 있어요.)
* 안드로이드 사용자의 경우 **[가이드](/iap/console.html#안드로이드-환불-방법)처럼** 토스 앱 내에서 환불 신청을 할 수 있게 안내해 주세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/intelli/console.md'
description: 토스 홈 광고 서비스를 콘솔에서 사용하는 가이드를 담고 있습니다.
---

# 콘솔 가이드

::: tip 토스 홈 광고에서 사용되는 개념이에요.

* **캠페인** : 하나의 목적을 갖지만, 각각 다른 세그먼트를 가진 소재 그룹들의 집합이에요.
  * 1개의 캠페인 안에는 N개의 소재 그룹을 등록할 수 있어요.
  * 동일한 목적의 토스 홈 광고라면 1개의 캠페인 안에 다양한 소재 그룹을 생성해서 사용해 주세요.
* **소재 그룹** : 캠페인에 속하는 하위 개념이에요.
  * 1개의 소재 그룹에는 1개의 타겟 세그먼트를 설정할 수 있어요.
  * 1개의 소재 그룹에는 N개의 소재를 등록할 수 있어요.
* **소재** : 소재 그룹에 속하는 하위 개념이에요.
  * 각 소재는 문구(상단 및 하단 문구), 아이콘(이미지) URL, 사용자가 접속하게 되는 랜딩 URL로 구성돼요.
    :::

## 1. 캠페인 생성

토스 홈 광고 사용을 위해서 가장 먼저 캠페인을 생성해주세요.\
생성된 캠페인은 '수정'만 가능하며 삭제할 수 없어요.

* **접속 방법 : 앱인토스 콘솔 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 ‘토스 홈 광고’ 선택 → ‘+등록하기’ 선택**

![](/assets/intelli_console_1.Bzs_HgEG.png)

캠페인 생성 시, 캠페인 제목과 기간을 설정해 주세요.

* 캠페인 제목은 용이한 관리를 위해 목적이 드러나도록 설정하는 것을 권장드려요.
* 기간은 자유롭게 설정해 주세요.
  * 토스 홈 광고의 경우 기간만 설정할 수 있으며, 노출 시간은 따로 설정하지 않아도 돼요.

![](/assets/intelli_console_2.C7tQLa7l.png)

## 2. 소재 그룹 생성

세그먼트를 활용하여 1개의 소재 그룹 이름과 사용자가 접속하게 될 `intoss://` 링크를 입력해 주세요.

* 소재 그룹 이름은 다른 그룹과 구분할 수 있도록 작성해 주세요.
* 세그먼트 클릭 시 '새로운 세그먼트 만들기' 를 통해 신규로 구성도 가능하며, 앱인토스 콘솔 내 '세그먼트' 메뉴에서 설정도 가능해요.
  * 여러 개의 조건을 조합하여 1개의 세그먼트를 만들어서 사용해 보세요.
* 랜딩 URL은 사용자가 소재를 클릭하게 될 경우 이동할 화면 주소예요.
  * 따로 설정하지 않을 경우 `intoss://{appName}`으로 설정되어 있어서, 미니앱의 홈화면으로 이동해요.

![](/assets/intelli_console_3.Dy8WSLtQ.png)

## 3. 소재 추가

소재 그룹에서 설정한 세그먼트에 노출할 수 있도록 여러 개의 소재를 등록할 수 있어요.

* \[소재] 영역의 `'+'`를 누르면 소재 추가가 가능해요.
* 토스에서 CTR이 높았던 샘플 소재를 바로 활용할 수 있어요.
  * 샘플 소재 선택 후 수정은 가능하지만, 최대한 서비스에 맞는 템플릿을 활용하는 방법을 추천드려요.
    ![](/assets/intelli_console_4.CKzt_TBB.png)
* 토스 홈 광고의 소재는 **상단 문구, 하단 문구, 아이콘**으로 구성되어 있어요.
  * 상단 문구는 토스 홈 광고에 윗줄에 들어가는 문구예요. '정답은 무엇일까요?', '작성 중인 리뷰' 와 같이 '명사형', '의문형', '문장형' 으로 작성해 주세요.
  * 하단 문구는 사용자로 하여금 액션을 유도하는 문구예요. '확인하기', '보러가기'와 같이 간결하게 작성해 주세요.
  * 아이콘은 토스 리소스 센터에서 제공하는 2D 아이콘만 사용할 수 있어요. 이미지 가공은 불가해요.
* 아래 '**토스 홈 광고 작성 가이드**'를 참고하면 소재 문구를 더욱 쉽게 작성할 수 있어요.
* 소재는 A안, B안, C안, D안 등 `'+'`를 눌러서 1개의 소재 그룹에 여러개의 소재를 등록할 수 있어요.
  * 1개의 소재 그룹에는 1개의 세그먼트만 설정할 수 있기 때문에 파트너사 판단 하에 동일한 소재로 여러 세그먼트에 노출 시켜야 한다면 소재 그룹을 여러개 만들어야 해요.

## 4. 소재 작성 가이드

::: tip 기본 규칙

* **하단 문구는 '보러가기', '확인하기', '신청하기'** 와 같이 **'~하기'** 로 작성해 주세요.
  * 단, 글자 수가 부족할 때는 **'명사형'** 으로 작성해 주세요.
* 상단 문구는 '~하기'가 아닌 다른 형태로 작성해 주세요.
  * 하단 문구와 연계하여 작성하는 형태로 작성하면 좋아요.
* 상단 문구와 하단 문구에는 **앱 이름(서비스명)이 작성되지 않도록** 해주세요.
  * 토스 홈 광고 배너에 서비스명과 카테고리가 자동으로 노출돼요.
* **느낌표, 괄호는 쓸 수 없어요.**
* 이외에도 [토스 UX 라이팅 가이드](/design/ux-writing.md)를 따르고 있어요.

**작성 규칙**

* **자극적인 광고적 표현은 사용하지 않아요.**
* 사용자가 홈 광고를 눌렀을 때 어떤 화면이 나올지 예측할 수 있어야 해요.
* 토스 홈 광고의 소재가 어떤 가치가 있는지 명확하게 보여져야 해요.
* 사용자가 부담할 코스트(비용)을 숨기면 안돼요.
* 꼭 받아야 할 세그먼트에게만 보내야 해요.
  :::

### 📌 기본 규칙

***

### ✍️ 맥락 없는 사용자도 내 앱을 이해할 수 있게 써요

사용자는 토스를 기본적으로 금융앱으로 인식해요. 내 서비스를 이미 알고 들어오는 사람이 아니라, 금융앱을 이용하다가 우연히 발견하게 돼요. 문구를 쓸 때는 '처음 보는 사람에게 내 앱을 소개한다면 어떻게 말할까?'를 한 번 더 떠올려주세요.

#### 1. 서비스의 핵심 키워드가 있나요?

게임이면 *게임*, 운세면 *운세*처럼, 사용자가 문구만 보고도 서비스를 파악할 수 있는 단어를 꼭 포함해주세요.

![](/assets/intelli_6.k3HW-VVM.png)

*운세 서비스라는 핵심이 나와있지 않아\
다음 페이지를 예상할 수 없어요.*

![](/assets/intelli_7.DQi8FlJf.png)

*문구만 봐서는 어떤 게임인지 알 수 없어요.\
보조설명에 ‘게임’이 있어도,\
문장 안에서 앱의 성격이 드러나야  바로 이해할 수 있어요.*

#### 2. 처음보는 사람도 이해할 수 있나요?

![](/assets/intelli_8.CvakOgeL.png)

*어떤 서비스인지 짐작하기 어렵고,\
“내 보상이 왜 쌓였지?” 하는 의심이 생길 수 있어요.*

![](/assets/intelli_9.CHa3QYql.png)

*서비스명을 모르면 무슨 기능인지 알 수 없어요.*

![](/assets/intelli_10.DeK7AvOQ.png)

*‘반납대신 현금화’는 써본 사람만\
이해할 수 있는 표현이에요.*

#### 3. 최대한 쉽게 풀어썼나요?

토스에는 다양한 배경의 사용자가 있어요. 자주 쓰는 유행어나 줄임말도 일부 사용자에게는 낯설 수 있어요.
더 많은 사용자에게 가치를 전달할 수 있도록, 복잡한 표현보다 쉽고 익숙한 단어로 풀어쓰세요.

![](/assets/intelli_11.DpCxGgYn.png)

![](/assets/intelli_12.BNAjVdVj.png)

#### 4. 행동을 숨기거나 혜택을 과장하지는 않았나요?

![](/assets/intelli_13.B4ZYHxJo.png)

*바로 쿠폰을 받을 수 있을 것처럼 느껴져요.\
혜택을 받기 위해 해야하는 행동을 꼭 써주세요.*

![](/assets/intelli_14.dS5KGq8w.png)

*무조건 2,000원을 받는 것처럼 느껴져요.*

### ❌ 이런 표현은 무조건 반려돼요

#### 전형적인 광고성 표현

![](/assets/intelli_15.CfjM5rPS.png)

* 깜짝, 초특가, 파격세일, 긴급 ...

#### 사용자를 불안하게 만드는 표현

![](/assets/intelli_16.CRzgh_bh.png)

![](/assets/intelli_17.CqY631J2.png)

* 놓친, 곧 사라져요...

#### 비표준어

![](/assets/intelli_18.D0zopbrL.png)

#### 맥락에 맞지 않는 아이콘

## 🟢 토스에서 효율이 좋았던 TOP 10% 문구만 모아놨어요

CTR 높은 문구 기반으로 콘솔에서 템플릿을 제작해놨으니, 적극 활용해주세요

| 종류       | 📎 | 상단 문구                              | 하단 문구                         |
|-----------|----|-----------------------------------------|-----------------------------------|
| 보상지급형 |  | 이기면 5,000원 받아요 | 결제창 게임 시작하기 |
| 보상지급형 |  | 보험료 확인 미션 도착 | 포인트 받기 |
| 보상지급형 |  | 케이크 쌓기 미션 성공하고 | 10,000원 쿠폰 받기 |
| 일반형 |  | 어렵진 김토스님의 모습 | 확인하기 |
| 일반형 |  | 토스 Apple Hub가 나왔어요 | 보러가기 |
| 보상지급형 |  | 토스가 10살이 되었어요 | 축하해주고 선물 받기 |
| 일반형 |  | 김토스님이 제일 갖고 싶은 상품 | 1개 찍기 |
| 보상지급형 |  | 계좌 OX 퀴즈 풀고 | 포도알 1개 받기 |
| 보상지급형 |  | 오늘의 방문미션 | 24원 포인트 받기 |
| 보상지급형 |  | 8월 금융 미션 풀고 | 최소 60원 받기 |
| 보상지급형 |  | 토스 카카오 채널 추가하고 | 10원 받기 |
| 일반형 |  | 간편 로그인 미션이 나왔어요 | 버튼 눌러 완수하기 |
| 보상지급형 |  | 페이스페이 | 미션 수행하고 상금 받기 |
| 보상지급형 |  | 3원 짜리 토스페이 미션 도착 | 버튼 눌러 완수하기 |
| 보상지급형 |  | 토스로 85원 결제 마무리하고 | 300원 받기 |
| 보상지급형 |  | 5원 받는 토스페이 이벤트 | 확인하기 |
| 보상지급형 |  | 김토스님, 작년에 가게 세금 | 잘 냈는지 보고 10원 받기 |
| 일반형 |  | 얼굴 놀이터가 열렸어요 | 놀러가기 |
| 보상지급형 |  | 토스에서 피는 물건 | 구경하고 4원 받기 |
| 보상지급형 |  | 새로 나온 편의점 혜택이 있어요 | 10원 받고 확인하기 |
| 보상지급형 |  | 매주 140등까지 상금 받아요 | 서포터즈 10원 받고 시작하기 |
| 일반형 |  | 김토스님 요금제 테스트 | 5개 문제에 답하기 |
| 보상지급형 |  | 근처에서 받을 수 있는 혜택 | 알림 받고 1원 받기 |
| 보상지급형 |  | 버튼 눌러 핸드폰 소식 받아보고 | 5원 받기 |
| 보상지급형 |  | 새로 나온 결제수단 쏠 준비하고 | 3원 받기 |
| 보상지급형 |  | 토스쇼핑 가을 이벤트 | 공유 1번에 1원씩 받기 |
| 일반형 |  | 카드 미션 4개가 새로 나왔어요 | 확인하기 |
| 보상지급형 |  | 5원 받는 11번가 이벤트 | 확인하기 |
| 보상지급형 |  | 김토스님이 등록한 현금영수증 | 내역 보기 |

---

---
url: 'https://developers-apps-in-toss.toss.im/login/console.md'
description: '토스 로그인 콘솔 사용 가이드입니다. 설정, 관리, 모니터링 방법을 확인하세요.'
---

# 콘솔 가이드

토스 로그인을 원활히 사용하려면 **콘솔에서 계약 → 설정** 순서로 진행해 주세요.

## 1. 약관 동의

토스 로그인 사용을 위해서는 **약관에 동의해야 해요.**\
약관동의는 앱인토스 콘솔에서 진행이 가능하며, **대표관리자로 지정된 분**의 계정에서만 가능해요.

* 약관 동의 방법
  * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 ‘토스 로그인’ 선택 후 ‘약관 확인하기’ 를 클릭 하여 아래 화면에서 약관 동의 진행

![](/assets/login_contract.Du9QUk58.png)

## 2. 설정하기

로그인 연동을 위해 콘솔에서 **사전 설정**을 완료해 주세요.\
입력한 정보를 기반으로 **사용자 약관 동의 화면**이 자동으로 구성됩니다.

![](/assets/login_1._FWDtovF.png)

### ① 연동할 서비스 : 기존 로그인과 연동하기

이미 토스 로그인을 사용 중인 서비스가 있을 경우 노출되는 영역이에요.\
기존 서비스의 회원 식별자(`userKey`)를 **앱인토스 토스 로그인과 동일하게 설정**할 수 있어요.\
목록에서 서비스 이름을 선택하면, 선택한 서비스의 `userKey` 값이 **동일하게 매핑돼요.**

::: tip 회원을 관리해보세요
토스 로그인을 연동하면 회원 정보를 쉽게 조회할 수 있어요.\
[사용자 정보 받기 API](/login/develop.md#_4-사용자-정보-받기)를 통해 사용자 식별자 `userKey`를 전달받을 수 있으며, `userKey`는 회원별 유니크한 값으로 **통합 회원 관리**에 유용해요.\
단, 미니앱(서비스)마다 `userKey`는 다를 수 있어요.
:::

### ② 동의 항목 : 사용자 권한 범위 설정

토스 로그인을 통해 수집할 **사용자 권한(스코프)** 을 선택해 주세요.

::: tip 꼭 확인해 주세요
이름, 이메일, 성별 외의 항목을 선택한 경우, **연결 끊기 콜백 정보**를 반드시 입력해야 해요.
:::

|항목|설명|
|---|----|
|이름 (USER\_NAME)|사용자의 이름이에요.|
|이메일 (USER\_EMAIL)|사용자의 이메일이에요. (토스 가입 시 필수가 아니어서 값이 없을 수 있고, 이 경우 null로 전달돼요.)|
|성별 (USER\_GENDER)|사용자의 성별이에요.|
|생일 (USER\_BIRTHDAY)|사용자의 생년월일이에요.|
|국적 (USER\_NATIONALITY)|사용자의 국적이에요.|
|전화번호 (USER\_PHONE)|사용자의 전화번호예요.|
|CI (USER\_CI)|사용자를 식별하는 고유한 KEY 값이에요. (Connection Information)|

::: tip CI란?
CI(Connection Information)는 본인인증 기관에서 발급하는 **고유 식별값**이에요.\
동일한 사용자가 여러 서비스에 가입하더라도, **같은 본인으로 식별할 수 있도록 생성되는 불변값**이에요.\
CI는 사용자 실명 인증이 필요한 서비스에서 **중복가입 방지나 본인 식별** 목적으로 자주 활용돼요.\
개인정보보호법상 **개인식별정보(PII)** 에 해당하므로, 저장하거나 사용할 때 반드시 **암호화 및 최소 수집 원칙**을 지켜야 해요.
:::

### ③ 약관 등록

::: tip 주의해 주세요
이 영역은 **법적 요건을 충족해야 하는 부분**이에요.\
서비스 성격에 따라 내용이 달라질 수 있으니 **최신 법령과 가이드라인을 확인하고, 법률 자문을 받는 것**을 권장해요.
:::

앱인토스에서 서비스를 운영하려면 약관을 등록해야 해요.\
**토스 로그인 필수 약관(서비스 약관 / 개인정보 제3자 제공 동의)** 은 자동으로 포함되며,\
**파트너사 서비스 약관 / 개인정보 수집·이용 동의 / 마케팅 정보 수신 동의(선택)** 등은 직접 등록해야 해요.\
서비스 목적에 맞는 **정확한 약관 링크**를 첨부해 주세요.

약관 유형은 기본 제공 예시 중에서 선택하거나 직접 입력할 수 있어요.\
약관을 구분해서 관리하고 싶다면 직접 입력하는 걸 추천드려요.

**등록 가능한 약관 예시**

* **(1) 서비스 이용약관**: 권리·의무, 책임 범위, 중단/종료, 분쟁 해결, 약관 변경 고지, (유료 시) 결제/환불 규정
* **(2) 개인정보 수집·이용 동의**: 수집 항목, 이용 목적, 보유·이용 기간, 동의 거부 시 불이익
* **(3) 마케팅 정보 수신 동의(선택)**: 수집 항목, 이용 목적, 보유 기간, 거부 시 불이익, 전자적 전송매체 광고 수신 동의
* **(4) 야간 혜택 수신 동의(선택)**: 야간(21:00~08:00) 발송 여부 명시

모든 약관 링크가 **정확히 연결**되고, 화면에 **명확하게 노출**되는지 확인해 주세요.

### ④ 연결 끊기 콜백 정보

사용자가 토스앱에서 **로그인 연결을 해제**하면, 등록한 **콜백 URL**로 이벤트를 받을 수 있어요.

::: tip 참고하세요
사용자가 연결 해제를 하면 토스는 **동의 약관·로그인 정보**를 모두 삭제해요.\
서비스에서도 세션이나 토큰 정리 등 후처리를 꼭 해 주세요.

또한, 사용자가 토스앱에서 로그인 연결을 해제하면 서비스에서도 **자동 로그아웃 처리** 또는 **재로그인 요청 안내**를 제공하는 걸 권장해요.\
예를 들어, "토스 연결이 해제되어 로그인이 필요합니다." 같은 문구를 노출해 주세요.
:::

|항목|설명|
|---|----|
|콜백 URL|사용자가 로그인연결을 해제했을 때 호출할 URL이에요.|
|HTTP 메서드|`GET` 또는 `POST` 중 하나를 선택해 주세요.|
|Basic Auth 헤더|호출 시 base64로 인코딩돼요. 디코딩 후 콘솔에 입력한 값과 일치하는지 검증해 주세요.|

#### 연결 끊기 이벤트 경로

사용자가 토스앱에서 로그인 연결을 해제하는 경로는 총 **3가지**예요.\
콜백 요청 시 `referrer`값으로 구분할 수 있어요.

|referrer|설명|
|--------|---|
|`UNLINK`|사용자가 **앱에서 직접 연결을 끊었을 때** 호출돼요. 미니앱에서는 이 이벤트를 받으면 **로그아웃 처리**를 해 주세요. (경로: 토스 앱 > 설정 > 인증 및 보안 > 토스로 로그인한 서비스 > '연결 끊기')|
|`WITHDRAWAL_TERMS`|사용자가 **로그인 서비스 약관을 철회할 때** 호출돼요. (경로: 토스 앱 > 설정 > 법적 정보 및 기타 > 약관 및 개인정보 처리 동의 > 서비스별 동의 내용 : "토스 로그인" > '동의 철회하기')|
|`WITHDRAWAL_TOSS`|사용자가 **토스 회원을 탈퇴할 때** 호출돼요.|

## 복호화 키 확인하기

![](/assets/login_4.D76OHLbx.png)

토스 로그인 정보 등록이 완료되면 **복호화 키**를 확인할 수 있어요.\
이 키는 토스 로그인 응답 데이터를 복호화할 때 사용돼요.\
**‘이메일로 복호화 키 받기’** 버튼을 눌러 안전하게 받아보세요.

::: tip 유의사항
복호화 키는 **민감한 보안 정보**예요.

* 절대 외부에 노출하지 마세요.
* 안전한 내부 비밀 저장소(Secret Manager 등)에 보관해 주세요.
* 재발급이 필요한 경우, 채널톡으로 문의해 주세요.
  :::

---

---
url: 'https://developers-apps-in-toss.toss.im/promotion/console.md'
description: '프로모션(토스 포인트) 콘솔 사용 가이드입니다. 설정, 관리, 모니터링 방법을 확인하세요.'
---

# 콘솔 가이드

:::info  프로모션을 진행하기 위해서는 다음과 같은 준비가 필요해요.

* 대표 관리자의 프로모션 기능 약관 동의 및 비즈 월렛 약관 동의
* 정산 정보 입력 및 검토 (영업일 기준 2~3일 소요)
* 토스 로그인 기능 연동 필요
  :::

![](/assets/promotion_console_0.BBFJk9b8.png)

## 1. 약관 동의

프로모션 진행을 위해서는 **약관 동의가** 필요해요.\
약관동의는 앱인토스 콘솔에서 진행이 가능하며, **대표관리자로 지정된 분**의 계정에서만 가능해요.

* **약관 동의 방법**
  * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 ‘프로모션’ 선택 후 ‘약관 확인하기’를 클릭하여 아래 화면에서 약관 동의 진행

![](/assets/promotion_console_1.D6z01PHz.png)

![](../resources/promotion/promotion_console_2.png)

## **2. 정산 정보 입력하기**

비즈 월렛 및 프로모션을 사용하기 위해서는 정산 정보를 입력해야 해요.\
워크스페이스의 **정보** 탭에서 정산 정보를 등록 후 **검토 요청**이 필요하고, **영업일 기준 평균 2~3일** 소요돼요.

* **정산 정보 메뉴 접속 방법**
  * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 상단 메뉴 중 ‘정보’ 선택 후 정산 정보 메뉴 내 ‘등록하기’ 진행

![](/assets/promotion_console_3.CdTTKN4j.png)

![](/assets/promotion_console_4.DyDaAOcb.png)

:::info  참고하세요

* 예금주명은 통장 사본에 기재된 이름과 모두 똑같이 입력해 주세요.
* 업태와 업종은 숫자가 아닌 텍스트로 입력해 주세요.
  예) ‘소프트웨어 개발업’ 인 경우 ‘소프트웨어’ 로 검색
  :::

## **3. 비즈 월렛 사용을 위한 약관 동의**

프로모션 예산은 비즈월렛에서 충전해요. 비즈월렛을 사용하려면 대표관리자가 약관에 동의해야 해요.

* **비즈 월렛 메뉴 접속 방법**
  * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 상단 메뉴 중 ‘비즈 월렛’ 선택

![](/assets/promotion_console_5.BmWYuVCl.png)

## **4. 비즈 월렛 충전**

대표 관리자의 비즈 월렛 약관 동의 이후 **‘+ 충전하기’** 를 통해 예산을 충전할 수 있어요.

![](/assets/promotion_console_6.D0bS0qVj.png)

금액은 **최소 30만 원 부터 최대 3,000만 원까지 충전** 할 수 있어요.\
단, 현재로서는 신용카드 결제만 가능해요. 결제 카드에 따라 결제 제한은 아래와 같으니 참고해 주세요.

* **인증결제 (viva\_appin)**: 전 카드사 결제 제한 **없음**
* **비인증결제 (viva\_appinkvp)**: 하나카드 1일 100만원 결제 제한, 이외 카드사 결제 제한 없음
  * 비인증 결제는 카드 번호를 직접 입력해서 결제하는 방식이에요.

![](/assets/promotion_console_7.D7y2qzVn.png)

충전이 정상적으로 모두 완료되면 아래 화면과 같이 **‘충전’** 으로 표기가 되고, 실제 충전 요청한 금액이 반영돼요.

![](/assets/promotion_console_8.Buu-eNnT.png)

## **5. 프로모션 등록하기**

프로모션 약관 동의, 정산 정보 검토, 비즈 월렛까지 모두 충전이 되었다면 프로모션 등록을 할 수 있어요.

* 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 ‘프로모션’ 선택

위 메뉴를 통해 접속 후 **‘+등록하기’** 를 눌러서 프로모션을 등록해 주세요.

![](/assets/promotion_console_9.DCz5_CYT.png)

:::info  **진행이 가능한 프로모션은 다음과 같아요.**

* 회원가입에 따른 프로모션
* 거래/구매 유도형 프로모션
* 이벤트 참여형
* 친구 초대 프로모션
  :::

자세한 내용은 제일 아래에 [**8. 프로모션 검토 가이드라인**](/promotion/console.html#_8-프로모션-검토-가이드라인)을 참고해 주세요.

![](/assets/promotion_console_10.Bb2ulhJy.png)

### **1) 프로모션 이름**

* 유저가 어떤 조건을 충족하는 경우 포인트를 받게 되는지 상세하게 입력해 주세요.\
  예) 서비스 로그인 시 10포인트 지급 / 튜토리얼 진행 완료 시 20포인트 지급

### **2) 프로모션 종료일**

* 희망하시는 프로모션 종료 일정을 세팅해 주세요.\
  단, 예산이 소진 될 경우 희망하시는 일정보다 먼저 종료될 수 있어요.

### **3) 혜택 탭 노출 여부**

* 혜택 탭을 노출로 할 경우 토스 앱 → 혜택 → ‘새로운 서비스 써보고’ 메뉴에 함께 노출 돼요.
* 혜택 탭에 노출 하지 않을 경우 미니앱을 통해 유저가 직접 접속하는 경우에 프로모션 진행이 가능해요.\
  단, 혜택 탭 노출을 하지 않고 프로모션을 진행 한 뒤 다시 혜택 탭 노출 희망하는 경우 새로운 프로모션으로 등록이 필요해요. (프로모션 수정 기능으로는 혜택 탭 노출 여부 수정 불가)

### **3-1) 미션 이름**

* 혜택 탭에 노출하기로 한 경우에만 적어주세요.
* 미션 이름은 ‘~하기’ 와 같이 끝나야해요.\
  예) 튜토리얼 하기, 로그인 하기, 리뷰 남기기 등

### **3-2) 지급 방식**

* 혜택 탭에 노출하기로 한 경우에만 적어주세요.
* 고정 금액 : 정해진 금액이 지급 되는 방식이에요.
* 최대 금액 : 1인이 프로모션 1회 참여 시 받을 수 있는 최대 지급 가능 금액이에요.\
  예) 최대 100원 : 100원 내에서 랜덤으로 지급돼요.

### **3-3) 이동 URL**

* 혜택 탭에 노출하기로 한 경우에만 적어주세요.
* 혜택 탭을 통해 접속하게 되는 프로모션 관련 페이지를 입력해 주세요.\
  intoss://{{appName}}/ScreenName 으로 구성돼요.

### **4) 예산 정보**

* 비즈 월렛의 잔액 보다 큰 예산은 설정할 수 없어요.
* 예산 증액이 필요한 경우 프로모션 진행 중에도 비즈 월렛 충전 후 증액을 할 수 있어요.

프로모션과 관련된 정보를 입력한 후 프로모션 검토 요청을 하면 아래와 같은 화면을 확인할 수 있어요.\
이후 아래 [**6. 테스트 진행하기**](/promotion/console.html#_6-테스트-진행하기) 를 해주세요.

테스트 진행이 완료 된 후 평균적으로 영업일 기준 1~2일 내에 프로모션 검토가 완료되고, 메일로도 안내 받을 수 있어요.

![](/assets/promotion_console_11.BnC9c8Fw.png)

:::info  참고하세요

* 프로모션 예산이 소진 되지 않도록 관리해 주세요.
* 프로모션 예산이 소진 되는 경우 혜택탭에는 더이상 노출 되지 않아요.
* 내부 정책에 따라 진행이 불가한 프로모션의 경우 반려 될 수 있어요. 꼭 진행이 가능한 프로모션 확인을 해주세요.
  :::

## **6. 테스트 진행하기**

:::info  참고하세요
최소 1번의 포인트 지급 API 테스트가 진행 되어야, 프로모션 검토 완료 및 실제 프로모션 진행이 가능해요.\
프로모션으로 여러 개를 진행하는 경우에도 각각의 프로모션마다 테스트가 진행 되어야 해요.
:::

프로모션 최종 검수 및 프로모션 진행을 위해서는 테스트를 먼저 진행해 주세요.\
추가 및 검토 요청한 프로모션 이름을 선택하시면 ‘테스트 프로모션 코드’ 확인이 가능해요.

* 테스트 프로모션 코드는 실제 프로모션 코드 앞에 ‘**`TEST_`**’ 가 붙어 있어요.
* 테스트 진행 시에는 프로모션 머니가 차감 되지 않아요. 실제 토스 포인트도 지급되지 않아요.
* 포인트 지급 API 호출 시 **`resultType`** 이 **`SUCCESS`** 로 응답이 오는지 확인해 주세요.

## 7. 프로모션 진행하기

프로모션 테스트와 프로모션 검토가 모두 완료 되었다면 ‘상태’ 칼럼이 ‘승인됨’ 으로 변경돼요.\
‘예산’ 은 **실제 소진 된 금액 / 총 예산** 으로 확인이 가능하고 예산 소진율과 함께 확인해 주세요.

![](/assets/promotion_console_12.CEzUeMf3.png)

승인된 캠페인 이름을 누르면, 프로모션 상세 정보 확인이 가능해요.\
우측 상단의 ‘**프로모션 시작하기**’ 버튼을 눌러 프로모션을 라이브 할 수 있어요.

![](/assets/promotion_console_13.BlRI3lCD.png)

진행 중인 프로모션을 수정하거나 종료, 일시정지를 할 수 있어요.

* 프로모션 수정은 예산을 증액할 때 사용해요.
* 프로모션 종료를 할 경우 남은 예산만큼 비즈 월렛으로 환급돼요.

![](/assets/promotion_console_14.FvMJq6ag.png)

## **8. 프로모션 검토 가이드라인**

앱인토스에서 프로모션을 운영 할 때 반드시 지켜야 할 가이드라인을 꼭 확인해 주세요.\
본 가이드라인의 경우 **이용자 보호, 법적 리스크 예방, 토스 브랜드 신뢰성 유지**를 위해 마련되었어요.

### 1) 허용되는 프로모션 유형

다음 유형은 명확한 조건과 고지를 충족할 경우 운영이 가능하며, 모든 유형에서의 **1인 당 지급 포인트는 5천 포인트 이내로 제한**돼요.

**① 회원가입/접속에 대한 보상**

* 최초 가입 또는 본인 인증 완료, 접속을 하면 포인트 주는 프로모션 이에요.
  * 예시: “신규 가입 시 2,000 포인트 지급” , “튜토리얼 완료 시 300포인트 지급” , “~~ 접속시 10포인트 지급”

**② 거래/구매 유도형**

* 특정 결제 또는 거래 완료 시 포인트를 지급 할 수 있는 유형이에요.
* 어떤 조건의 구매 혹은 거래가 이루어져야 하는지 조건 고지가 반드시 되어야 하고 또한 해당 하지 않은 사항에 대해서도 반드시 고지 필요해요.
  * 예시: “5천 원 이상 결제 시 500포인트 지급”

**③ 이벤트 참여형**

* 설문, 퀴즈, 간단 미션 완료 후 포인트 지급하는 유형을 말해요.
* 단, **과도한 시간·노동 요구 불가해요.**

**④ 친구 초대/바이럴형**

* 초대한 사람과 초대 받은 사람이 포인트를 받을 수 있는 프로모션 유형이에요.
  * 예시: “친구 초대 시 각각 500포인트 지급”
* **단, 중복 참여 방지 등 어뷰징을 방지 하기 위한 로직이 필수로 적용 되어야 해요.**

### 2) 불가한 프로모션 유형

다음 유형은 법령 및 내부 정책에 따라 운영이 불가 해요.

* **확률형/랜덤 보상**
  * 룰렛, 뽑기, 확률형 미션 + 포인트 결합
* **게임 결과 기반 보상**
  * 점수·승패·등수 등에 따른 차등 지급
* **재화 환전형 리워드**
  * 기프티콘·상품권·게임 아이템 → 토스 포인트 전환
* **현금 보장형/유사 수신행위**
  * “입금 시 + N% 보장” 등 투자성/사행성 성격
* **과도한 보상**
  * 1인 당 5천 포인트 초과 되는 프로모션 (추첨형은 별도 검토 필요)

### 3) 사용자 안내 필수 항목

프로모션 진행 시 반드시 다음을 고지해 주세요.

* 지급 시점 (즉시 지급 등)
* 지급 조건 (최초 결제, 5천원 이상 결제 등)
* 지급 제한 (탈퇴, 환불, 부정 참여 시 지급 불가)
* “본 프로모션은 사전 고지 없이 중단될 수 있습니다” 문구 필수
* 랜덤 지급 불가 (고정 지급만 가능)

### 4) 정산 및 운영 원칙

* **정산 방식**
  * 프로모션은 비즈 월렛을 충전한 뒤 프로모션 예산을 설정하고 해당 예산이 소진 되는 형태에요.
  * 단, 프로모션을 중단하면 잔여 예산이 있을 경우에 한하여 비즈 월렛으로 반환 돼요.
* **리스크 관리**
  * 중복 참여 및 어뷰징 방지에 대한 로직은 필수로 적용해 주세요.
  * 클레임 발생 시 → 참여 기록 확인 후 파트너사에서 확인이 필요해요.

### 5) 프로모션 사전 점검 체크리스트

아래 항목을 모두 충족해야 프로모션 집행이 가능해요.

* 제공 되는 포인트가 **1인당 5천포인트 이하**인가요?
* 지급 조건, 지급 시점, 지급 제한 사항 등을 명확히 고지했나요??
* 참여 방식이 단순하고 과도한 시간 또는 노동 요구는 없나요?
* 룰렛, 뽑기 등 확률형 요소와 결합되지 않았나요?
* 제공 되는 포인트가 게임의 결과 또는 등수 기반으로 산정 되는 것은 아닌가요?
* 유저가 보유한 재화를 토스포인트로 교환/전환 해주는 형태의 프로모션은 아닌가요??
* 진행 되는 프로모션의 조기 종료 혹은 중단 가능성을 사전 고지했나요?
* 중복 참여 방지 로직을 적용했나요?
* 사행성 또는 과장된 프로모션은 아닌가요?

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: "모든 프로모션에 1인당 5천 포인트 제한이 있나요?",
a: `네. 맞아요. <br> 가입/거래/이벤트/친구 초대 등 <strong>모든 프로모션 유형은 원칙적으로 1인당 최대 5천 포인트 미만 까지만 지급</strong> 가능해요.`
},
{
q: "추첨이나 랜덤 지급 이벤트는 가능한가요?",
a: `불가해요. <br> 확률형·룰렛·랜덤 뽑기 방식은 <strong>사행행위로 해석될 위험</strong>이 있어 허용되지 않고 있어요.<br> <strong>고정형 지급</strong>만 허용됩니다. (예: "첫 가입 시 500 포인트 지급")`
},
{
q: "기프티콘·상품권을 토스 포인트로 교환해줄 수 있나요?",
a: \`불가해요.

---

---
url: 'https://developers-apps-in-toss.toss.im/push/console.md'
description: '푸시 알림 콘솔 사용 가이드입니다. 설정, 관리, 모니터링 방법을 확인하세요.'
---

# 콘솔 가이드

푸시, 알림을 발송을 위해서는 콘솔에서 메시지 템플릿 등록이 필요해요.

## 1. 캠페인 생성

푸시, 알림 발송을 위해서 캠페인을 생성해주세요.

* 접속 방법: 앱인토스 콘솔 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 ‘푸시, 알림’ 선택 → ‘+생성하기’ 선택

캠페인의 목적이 드러나도록 제목을 설정하는 것을 권장드려요.

![](/assets/push_1.BhsKDAqG.png)

## 2. 발송 방법 및 대상

세그먼트를 선택해서 발송할지, API로 자동 발송할지 선택해 주세요.

* 세그먼트로 발송하기: 특정 유저에게 푸시, 알림을 보낼 수 있어요.
* API로 자동 발송하기: 특정 시점에 API를 통해 자동으로 발송할 수 있어요.

### 기능성 메시지와 광고성 메시지

### ① 기능성 메시지

기능성 메시지는 서비스 이용에 직접적으로 필요한 정보를 제공하기 위한 메시지로, 서비스 운영과 관련된 필수적인 기능을 의미해요.\
광고 목적이 포함되지 않아야 하며, 수신자가 요청한 정보이거나 서비스 이행을 위한 필수 메시지이어야 해요.\
기능성 메시지는 사용자가 앱인토스 앱에서 알림을 OFF(끔) 할 수 있어야 해요.\
해당 기능이 없을 경우, 광고성으로 간주되어 반려될 수 있어요.

### ② 광고성 메시지

광고성 메시지는 고객의 구매를 유도하거나 마케팅 목적을 가지고 발송되는 메시지로, 상품, 서비스, 이벤트 등을 홍보하기 위한 기능을 의미해요.\
고객이 반드시 사전에 수신 동의한 경우에만 보낼 수 있기 때문에 ‘마케팅 수신 동의’ 유저에게만 발송돼요.

* 본문이 “(광고) 본문 ({미니앱 이름} 알림)”의 형태로 작성돼요.
* 오전 8시부터 오후 9시까지만 발송할 수 있어요.

## 3. 푸시, 알림 내용

‘+템플릿 선택하기’ 버튼을 눌러 푸시, 알림 템플릿을 활용해주세요.\
소개, 신규, 혜택, 업데이트, 리텐션 등 주제에 맞는 문구를 선택하고 수정할 수 있어요.\
문구를 수정할 때는 [푸시, 알림 작성 규칙](/push/console.md#%E1%84%91%E1%85%AE%E1%84%89%E1%85%B5-%E1%84%8B%E1%85%A1%E1%86%AF%E1%84%85%E1%85%B5%E1%86%B7-%E1%84%8C%E1%85%A1%E1%86%A8%E1%84%89%E1%85%A5%E1%86%BC-%E1%84%80%E1%85%B2%E1%84%8E%E1%85%B5%E1%86%A8)을 참고해 주세요.\
‘+A/B 테스트’ 버튼을 눌러 다양한 실험안을 추가할 수 있어요.

![](/assets/push_2.BdXfLTup.png)

푸시, 알림 내용 작성 후 검토를 요청해 주세요.\
메시지 템플릿 승인까지는 최대 2~3 영업일이 소요돼요.\
따라서, 모든 템플릿들은 승인을 고려하여 필요일 2~3영업일 이전에 템플릿 저장 및 검수 요청을 완료해주세요.

![](/assets/push_3.C3w3QjH_.png)

## 4. 발송하기

푸시, 알림 내용 승인 후 발송을 예약할 수 있어요.

* 예약 발송하기: 원하는 일시에 발송할 수 있어요.
* 최적 시간에 자동 발송하기: 사용자별로 가장 활발한 시간에 맞춰 보낼 수 있어요.
* 즉시 발송하기

전체 발송 전, 일부에게 먼저 보내 반응을 확인할 수도 있어요.

![](/assets/push_4.B8-zHKdw.png)

## 푸시, 알림 작성 규칙

토스를 쓰는 모든 사용자에게 내 앱을 처음 소개한다는 마음으로 작성해주세요. 사용자는 이 푸시를 ‘토스’라는 금융앱의 맥락 안에서 받아들여요. 메시지가 토스답게 보이고, 자연스럽게 이해될 수 있도록 써주세요.

### 1. 푸시 타이틀 최대 13자, 본문은 20자까지 써요

### 2. 알림 내용은 해요체로 써요

![](/assets/push_5.DTLjwdie.png)

### 3. ‘토스’를 꼭 포함해요

사용자는 미니앱을 토스 안의 서비스로 인식해요. 토스의 이름으로 나가는 만큼, 문장 속에서도 토스라는 맥락이 자연스럽게 드러나야 해요.

![](/assets/push_6.99DuNLcd.png)

### 4. 서비스를 처음 보는 사람도 이해할 수 있게 써요

푸시를 받는 사용자는 미니앱에 대한 이해가 없는 사용자예요. 처음 보는 사람에게 내 서비스를 소개한다고 생각하고 최대한 친절하게 작성해주세요.

![](/assets/push_7.DFNa58at.png)

*선물을 추천해주는 서비스라는 맥락이 필요해요.*

![](/assets/push_8.BzDCmiDn.png)

*AI 사진관이라는 핵심 키워드가 없어\
어떤 서비스인지 예상이 안가요.*

### 5. 짧고 쉽게 써요

문장이 짧을수록 CTR이 높아요.

![](/assets/push_9.BK07GwSd.png)

![](/assets/push_10.DneNjTvY.png)

::: details ⚡️ **짧게 쓰는 팁**

**이런 단어를 지워봐요**

□ 지금, 당장, 즉시\
□ 이름 변수\
□ 극존칭 (~하시고)\
□ 타이틀과 중복되는 키워드

:::

## ❌ 이렇게 쓰면 반려돼요

### 유행어, 명대사, 밈, 특정인물의 이름

![](/assets/push_11.Ddw9JwN3.png)

![](/assets/push_12.DbZ6vA3y.png)

### 특정 그룹만 이해할 수 있는 은어

![](/assets/push_13.C5MUIdfA.png)

### 전형적인 광고성 표현 (이모지, 느낌표 포함)

![](/assets/push_14.BXLteCDz.png)

![](/assets/push_15.DCVJhL9s.png)

### 사용자의 기분을 상하게 할 수 있는 소재

놓치면 후회한다는 뉘앙스나, 사용자를 과도하게 불안하게 하는 단어는 쓰지 않아요. 상황만 차분히 전달해주세요.

![](/assets/push_19.DR2WWttM.png)

## 🟢 토스에서 효율이 좋았던 문구만 모아놨어요

CTR 높은 문구 기반으로 콘솔에서 템플릿을 제작해놨으니, 적극 활용해주세요

### 1. 참여를 이끌고 싶을 때

#### 이벤트 / 미션 / 게임

### 2. 이어서 하게 하고 싶을 때

#### 재방문

### 3. 새로운 서비스를 알리고 싶을 때

#### 기능 / 정보 / 안내 / 업데이트

### 4. 유용한 팁이나 정보를 전달할 때

#### 아티클 / 커뮤니티

### 5. 축하와 기쁨을 나누고 싶을 때

#### 해피모먼트

---

---
url: 'https://developers-apps-in-toss.toss.im/reward/console.md'
description: '공유 리워드 콘솔 사용 가이드입니다. 설정, 관리, 모니터링 방법을 확인하세요.'
---

# 콘솔 가이드

기능 사용을 위해서는 콘솔에 사전 셋팅이 필요해요.

![](/assets/reward_1.YJKtbKAt.png)

![](/assets/reward_2.DfHjR_Yp.png)

리워드 정보를 입력해 주세요.\
등록한 정보 기준으로 사용자에게 보여질 공유 리워드 화면을 구성합니다.

* 리워드 : 리워드 단위를 입력해 주세요. `'하트'`, `'보석'` 등을 입력해 주세요.
* 수량 및 금액 : 지급할 리워드 수량이에요. 지급하고 싶은 수량 및 금액을 입력해 주세요.

등록하기 버튼을 누르면 등록한 공유 리워드를 볼 수 있어요.

![](/assets/reward_3.DPGqYnG5.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/segment/console.md'
description: '세그먼트 콘솔 사용 가이드입니다. 설정, 관리, 모니터링 방법을 확인하세요.'
---

# 콘솔 가이드

::: tip 확인해 주세요

* 푸시, 알림 기능과 토스 홈 광고에 세그먼트를 사용하기 위해서는 '세그먼트' 메뉴에서 원하는 유저 그룹을 구성해 주세요.
* 1개 조건만 사용할 수 있는 것은 아니에요.
  * 여러 조건을 합쳐서 **AND 조건 또는 OR 조건**으로 설정해서 사용할 수 있어요.
* 한번 설정한 세그먼트명은 삭제하더라도 동일한 이름으로는 사용할 수 없어요.
  :::

## 1. 세그먼트 생성하기

세그먼트 메뉴로 접속해서 `'+생성하기'` 버튼으로 진행해 주세요.

* 접속 방법 : 앱인토스 콘솔 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 '세그먼트' 선택

세그먼트는 먼저 거래정보, 유저정보, 유저활동, 유저프로파일 카테고리 중 1개를 선택해서 설정할 수 있어요.\
각각의 카테고리는 다음과 같은 내용을 확인할 수 있어요.

* **거래정보** : 토스페이 사용 여부, 브랜드, 광고 카테고리 등
* **유저정보** : 나이, 성별, 앱 버전, 통신사 등
* **유저활동** : 최근 미니앱을 방문한 유저에 대한 세그먼트를 설정할 수 있어요.
  * 미니앱 로그인 기준이 아닌 접속 기준으로만 설정 가능해요.
* **유저프로파일** : 금융 성향, 관심사에 대한 추정 정보 등을 기반으로 설정할 수 있어요.

![](/assets/segment_console_1.CalURf1F.png)

![](/assets/segment_console_2.sZ2_SKOQ.png)

## 2. 카테고리 및 조건 설정

원하는 카테고리를 1개 선택해 주세요.

* 유저 정보를 선택할 경우 유저 정보에 해당하는 내/외국인, 성별, 통신사 등을 확인할 수 있어요

원하는 하위 카테고리를 선택하고 `'추가하기'`를 누르면 **'선택한 세그먼트'** 라는 우측 화면에 노출돼요.

* 이때, 1개의 카테고리만 사용하고 싶을 경우 '저장하기'를 눌러 저장할 수 있어요.
* 다만 여러 조건을 합쳐서 사용하고 싶을 때는, 원하는 세그먼트를 모두 `'추가하기'`를 한 다음 **'AND'** 또는 **'OR'** 조건을 설정해서 사용할 수 있어요.
* 일부 예측이 필요한 세그먼트의 경우 정확도 설정이 필요해요.
  * 예측된 세그먼트의 **정확도를 높일 경우 전체 세그먼트의 크기(모수)가 줄어들 수** 있어요.
  * 일반적인 경우라면 50% 이상을 설정해 주세요.
  * **세그먼트의 크기(모수)가 중요하다면 정확도를 낮춰서 사용**할 수 있어요.
    * 다만, 정확도를 낮춰서 푸시/알림을 발송하거나 토스 홈 광고를 세팅할 경우 타겟팅이 정확하지 않을 수 있기 때문에 해당 소재가 이해되지 않는 유저가 있을 수 있어요 ([푸시/알림 콘솔 가이드 보러가기](/push/console.md))

::: tip 예를 들어, '서울특별시'에 거주하면서 '자가를 보유한 것 같은 사람' 에게 푸시/알림을 보내고 싶다면?

* 유저정보 → 지역 → 서울특별시 선택 후 ‘추가하기’
  * ‘홈’ 을 눌러서 처음 카테고리 목록으로 이동
* 유저프로파일 → 자가보유\_전체 → 정확도 설정 후 ‘추가하기’
* 우측의 ‘선택한 세그먼트’ 확인 후 AND / OR 중 **‘AND’** 선택
  * 만약 서울특별시에 거주하거나, 자가를 보유한 것 같은 사람에게 타겟팅을 하고 싶다면 ‘OR’ 조건 선택
    :::

![](/assets/segment_console_3.BrQxnt-X.png)

![](/assets/segment_console_4.B6gf2uXj.png)

![](/assets/segment_console_5.CT0unPxk.png)

원하는 세그먼트 카테고리 및 종류를 모두 추가한 다음 AND 또는 OR 조건을 누르면 1개의 세그먼트로 합쳐지고, 설정한 세그먼트에 해당하는 인원으로 변경돼요.

* **되돌리기**를 누를 경우 위 이미지와 같이 다시 각각의 세그먼트로 분리돼요.
* **저장하기**를 누를 경우 조건이 합쳐진 세그먼트로 저장을 할 수 있어요.

![](/assets/segment_console_6.DCWKYuIk.png)

## 3. 저장하기

저장하기를 누를 경우 세그먼트명과 세그먼트 설명, 즐겨찾기 및 고정 여부를 설정할 수 있어요.

![](/assets/segment_console_7.BoR7i0a-.png)

* **세그먼트명**은 기본적으로 추가한 세그먼트들이 모두 나열돼 있어요. 원하실 경우 자유롭게 변경할 수 있어요.
  * 단, 해당 세그먼트를 저장한 뒤 삭제하게 될 경우 그 이름은 다시 사용할 수 없어요.
* **세그먼트 설명**은 해당 세그먼트를 어떤 사유로 구성하였는지 적어주시거나 관리가 용이하게 작성해 주세요.
* **즐겨찾기**를 할 경우 저장한 세그먼트를 푸시, 알림과 토스 홈 광고에서 바로 사용할 수 있어요.
* **고정된 모수로 저장**할 경우 저장 시점의 모수를 변동 없이 고정해서 사용할 수 있어요.
  * 이 경우, 처음 저장한 시점의 모수가 변동되지 않지만, 최신화가 되지 않아요.
  * 고정된 모수로 저장하지 않는다면 구성한 세그먼트는 최신화가 되어 반영되지만, 처음 저장한 시점의 모수와 달라질 수 있어요.
  * 파트너사에서 필요한 상황에 맞게 적절하게 사용해 주세요.
* 저장 버튼을 누르면 저장이 완료되고, 세그먼트 메뉴에서 확인할 수 있어요.
  * 해당 세그먼트는 푸시, 알림과 토스 홈 광고에서도 확인할 수 있고 사용할 수 있어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/tosspay/console.md'
description: '토스페이 콘솔 사용 가이드입니다. 설정, 관리, 모니터링 방법을 확인하세요.'
---

# 콘솔 가이드

## 1. 계약하기

토스페이 사용을 위해 **사전 서류 준비 및 서면(지류) 계약**이 필요해요.

* [채널톡](https://apps-in-toss.channel.io/workflows/767697)으로 정보를 입력해 주시면 입력된 정보를 기반으로 토스페이팀에서 1차적으로 검토를 진행해요.
* 이후 추가 확인이 필요한 경우 청약 담당자 메일로 안내 드려요.
* 청약 서류 작성 및 제출을 해주시면 **내부 검수**를 거쳐 **토스페이 키값**을 발급받게 되며, 보통 **영업일 기준 7~14일** 소요돼요.

## 2. 설정하기

계약 완료 후 메일로 받은 토스페이 키값을 콘솔에 등록해 주세요.

* **워크스페이스 → 연동 키 → 등록** 버튼에서 **가맹점 키**를 입력할 수 있어요.\
  ※ **기존에 사용하던 토스페이 키값이 아닌 앱인토스 전용 토스페이 키값을 입력해 주세요.**
* 테스트용 API 키: `sk_test_w5lNQylNqa5lNQe013Nq`\
  ※ 테스트 키는 **결제 생성까지만 가능**하며, **승인 처리는 불가**합니다.

![](/assets/pay_register.D8K3NMy_.png)

![](/assets/pay_register_2.8dO95iPe.png)

---

---
url: 'https://developers-apps-in-toss.toss.im/prepare/console-workspace.md'
description: >-
  앱인토스 콘솔에서 미니앱을 등록하는 과정을 안내합니다. 회원가입, 워크스페이스 설정, 멤버 초대, 미니앱 등록하는 과정을 확인하세요.
  미니앱을 등록할 때에는 앱 로고, 앱 이름, appName, 사용 연령, 고객센터 이메일/연락처/채팅 상담 주소 등을 안내하고 게임/비게임
  별 카테고리 및 검색을 등록하는 방법을 안내해요. 특히 게임의 경우, 게임 등급분류 관련 내용을 상세히 안내해요.
---

# 콘솔에서 앱 등록하기

![](/assets/console_reg_flow.DeUk5WuF.png)

::: tip 사업자가 없는 경우 확인해 주세요

* 사업자가 없는 개인 개발자인 경우에는 사업자 등록을 하지 않아도 돼요.
* 단, 수익화와 관련된 기능 및 토스 로그인은 사용할 수 없어요.
* 사업자 등록을 원하시는 경우, [국세청 홈택스](https://hometax.go.kr/websquare/websquare.html?w2xPath=/ui/pp/index_pp.xml\&menuCd=index3)에서 간편하게 신청할 수 있고, 보통 3일 안에 발급돼요.
  * 접속 경로: 홈택스 → 전체메뉴 → 증명•등록•신청 → 사업자등록증신청
* 자세한 내용은 [비사업자 가이드](/prepare/console-workspace.html#_2-%E1%84%87%E1%85%A9%E1%86%AB-%E1%84%80%E1%85%A8%E1%84%8B%E1%85%A3%E1%86%A8-%E1%84%92%E1%85%AA%E1%84%86%E1%85%A7%E1%86%AB)를 참고해 주세요.
  :::

앱인토스 콘솔은 미니앱을 개발하고 운영할 때 사용하는 관리자 페이지예요.\
콘솔에서 앱을 등록하고, 결제나 로그인 같은 기능을 설정할 수 있고, 앱을 출시할 수 있어요.

## 1. 회원가입하기

앱인토스를 이용하기 위해서는 먼저 콘솔에 가입해야 해요.\
[앱인토스 콘솔](https://apps-in-toss.toss.im/)에 접속해서 회원가입을 해주세요. 앱인토스 콘솔은 토스 비즈니스 회원을 기반으로 가입이 진행돼요.\
앱인토스 콘솔 가입을 위해서는 **만 19세 이상**이어야하고, **본인 명의로 로그인된 토스앱**이 필요해요.

## 2. 워크스페이스 설정하기

워크스페이스는 팀원들이 함께 프로젝트를 관리할 수 있는 공간이에요.\
사업자당 1개의 워크스페이스만 사용할 수 있고, 이름은 중복으로 설정할 수 없어요.\
팀이나 프로젝트 이름처럼 쉽게 알아볼 수 있는 이름을 붙여 주시고, 나중에 수정할 수 있어요.

![](/assets/console.dwvY4tCS.png)

## 3. 멤버 초대하기

워크스페이스를 만든 사람에게 **자동으로 '대표관리자' 권한**이 부여돼요. 대표관리자는 멤버 초대 및 권한을 설정할 수 있어요.

::: tip 대표 관리자의 역할은 무엇인가요?

* 대표 관리자는 워크스페이스 운영을 책임지고, 서비스 약관에 동의할 수 있는 권한이 있어요.
* 대표 관리자는 관리자 중에서만 신청할 수 있어요. 구성원은 신청할 수 없어요.
* 테스트 앱은 사업자 인증 없이도 만들 수 있어요. 단, 사업자 인증(대표 관리자 신청)이 되지 않으면 수익화 기능 및 토스 로그인을 사용할 수 없어요.
  :::

‘멤버’ 메뉴에서 **‘+초대하기’** 를 눌러 팀원의 이메일 입력 후 권한 별로 초대할 수 있어요.

* **관리자**: 멤버 관리, 설정 변경 등 모든 권한을 가져요.
* **구성원**: 공동 작업은 가능하지만, 멤버 초대나 설정 변경은 제한돼요.

![](/assets/invite-member.BfmdG6zm.png)

### 대표관리자 변경하는 방법

대표관리자를 변경하려면 **현재 대표관리자가 본인 이름 우측의 \[권한 위임] 버튼**을 눌러 주세요.

::: tip \[권한 위임] 버튼이 비활성화 되어있어요
이미 대표관리자 위임 절차가 진행 중이거나, 사업자 정보 확인이 완료되지 않은 경우에는 버튼이 비활성화 되어 있어요.\
위 절차가 모두 완료 된 뒤 다시 시도해 주세요.
:::

![](/assets/boss_change_2.CGlxsYgA.png)

![](/assets/boss_change_1.VIfUXhXI.png)

대표관리자 변경은 상황에 따라 아래와 같이 진행돼요.

**① 워크스페이스의 사업자 정보 등록 여부에 따라 달라져요.**

* **사업자 정보 등록 이력이 없는 경우,** 추가 확인이 필요 없어서 바로 위임되거나 약관 동의만으로 마무리될 수 있어요.
* **사업자 정보가 이미 등록되어 있는 경우,** 권한 위임 대상자가 동일한 회사 소속이 맞는지 확인해야 해요.\
  안내 이메일의 \[사업자 정보 등록하기] 버튼을 눌러 콘솔로 이동한 후 정보를 제출해 주세요.
  * 대표자인 경우 → 기존 서류로 확인 가능해 추가 제출 없이 진행돼요.
  * 대리인인 경우 → 인감증명서, 위임장, 신분증 사본이 필요해요.

![](/assets/boss_change_3.uqj6_WOX.png)

![](/assets/boss_change_4.P1xFYwgw.png)

::: tip 사업자 인증 과정에서 반려됐어요
대표관리자 위임 중 사업자 인증이 반려된 경우, 반려 사유를 확인한 후 반드시 권한 위임 대상자 본인이 다시 제출해주세요. 반려 사유는 이메일과 위 ‘파트너 정보’ 메뉴에서 확인할 수 있어요.
:::

**② 이전 대표관리자의 약관 동의 이력에 따라 달라져요.**

* **동의 이력이 없는 경우,** 추가 절차 없이 바로 위임이 완료돼요.
* **동의 이력이 있는 경우,** 권한 위임 대상자가 이메일을 통해 약관에 동의해야 위임이 완료돼요.

![](/assets/boss_change_5.D3OtlddM.png)

## 4. 앱 등록하기

워크스페이스를 생성한 이후 ‘앱’ 메뉴에서 **‘+등록하기’** 를 통해 앱을 등록해 주세요.\
실제 개발이 완료되지 않은 앱이더라도 미리 등록할 수 있어요.

::: tip 개발 앱과 라이브 앱을 나눠서 관리하고 싶다면?
같은 워크스페이스 안에서 앱을 구분해서 등록해 주세요.\
테스트용 앱과 실제 배포용 앱을 따로 등록할 수 있어요.
:::

![](/assets/registering-app.CAxYwrH8.png)

![](/assets/registering-app-1.D_h9-HU2.png)

### 4-1) 기본 정보

![](/assets/registering-app-2.CjM6uPmA.png)

#### ① 앱 로고

앱 로고는 토스 앱 전체 메뉴의 미니앱 홈 또는 비게임의 경우 상단 [**공통 내비게이션 바**](/bedrock/reference/framework/UI/Config.html#%E1%84%82%E1%85%A2%E1%84%87%E1%85%B5%E1%84%80%E1%85%A6%E1%84%8B%E1%85%B5%E1%84%89%E1%85%A7%E1%86%AB-%E1%84%87%E1%85%A1-%E1%84%87%E1%85%B5%E1%84%80%E1%85%A6%E1%84%8B%E1%85%B5%E1%86%B7)에 노출돼요.

::: tip 앱 로고 가이드를 확인해 주세요
[앱 로고 가이드.pdf](../resources/prepare/logo_guide.pdf)
:::

* 작은 화면에서도 선명하게 보여야 해요.
* 서비스 특성이 직관적으로 드러나야 해요.
* 다른 앱과 혼동되거나 저작권 문제가 없어야 해요.
* 다크 모드에서도 자연스럽게 보이는 색상·형태를 사용해 주세요.
* 정사각형 600 × 600px, PNG(배경색 필수, 투명 배경 사용 불가)

#### ② 앱 이름

* 토스 앱에 노출되는 이름이므로, 서비스 성격이 바로 이해될 수 있도록 작성해 주세요.
* 기존 브랜드/서비스명을 사용 중이라면 그대로 쓰는 것을 권장해요.
* 나중에 앱 정보에서 수정할 수 있어요.
* 영문명은 아래 규칙을 따라 주세요.

#### ③ appName

* 앱 스킴 호출 시 이 ID를 기준으로 앱인토스 서비스로 이동해요.
* **`intoss://`** 형식으로 구성되고, 규칙을 지키지 않으면 서버 인증서 발급이 실패할 수 있어요.
* appName은 한 번 등록 후 수정할 수 없으니 신중하게 입력해 주세요.

#### ④ 사용 연령

현재 앱인토스는 만 19세 이상 고객에게만 제공되고 있어요. 

#### ⑤ 고객센터 이메일 / 연락처 / 채팅 상담 주소

* 원활한 문의 대응을 위해 고객센터 연결 정보를 입력해 주세요.
* 입력한 정보는 공통 내비게이션 바에서 ‘고객센터’를 눌렀을 때 사용자에게 안내돼요.

![](/assets/registering-app-navigationbar.CqJFDjVz.png)

### 4-2) 카테고리 및 검색

**\[비게임 앱인 경우]**

![](/assets/registering-app-3.CY6K88vX.png)

**\[게임 앱인 경우]**

![](/assets/registering-app-game.B5Fkhlu7.png)

#### **① 게임 앱 설명**

* 게임 소개 화면(가로형 썸네일 등)에 노출되는 보조 설명이에요.
* 플레이 방식·콘텐츠 등 **어떤 게임인지 직관적으로 전달**해 주세요.
* 과장, 부정확한 정보, 혐오·비속어, 오해 소지가 있는 표현 사용 시 반려될 수 있어요.

#### **② 정방형 썸네일**

* 게임의 콘텐츠를 명확히 보여주는 정방형 이미지가 필요해요.
* 배너 등 다양한 지면에 활용될 수 있어요.
* 다른 앱과 혼동되지 않도록 구성해 주세요.
* 저작권 문제가 없는 이미지를 사용해 주세요.
* **1000 × 1000px PNG 파일만 등록할 수 있어요.**

#### **③ 가로형 썸네일**

* 게임의 핵심 콘텐츠가 드러나는 가로형 이미지가 필요해요.
* 배너 등 다양한 지면에 활용돼요.
* 다른 앱과 혼동되지 않도록 구성해 주세요.
* 저작권 문제가 없는 이미지를 사용해 주세요.
* **1932 × 828px PNG 파일만 등록할 수 있어요.**

#### **④ 리더보드**

* 사용자 점수를 기준으로 [순위를 매기는 기능](/game-center/intro.html#%E1%84%80%E1%85%A6%E1%84%8B%E1%85%B5%E1%86%B7-%E1%84%91%E1%85%B3%E1%84%85%E1%85%A9%E1%84%91%E1%85%B5%E1%86%AF-%E1%84%85%E1%85%B5%E1%84%83%E1%85%A5%E1%84%87%E1%85%A9%E1%84%83%E1%85%B3%E1%84%82%E1%85%B3%E1%86%AB-%E1%84%86%E1%85%AE%E1%84%8B%E1%85%A5%E1%86%BA%E1%84%8B%E1%85%B5%E1%86%AB%E1%84%80%E1%85%A1%E1%84%8B%E1%85%AD)이에요.
* 기록할 점수 단위와 정렬 기준 등 정책을 설정해 주세요.

### 4-3) 게임 등급분류

게임은 등급 심의 증빙 자료를 반드시 제출해야 해요.\
입력한 정보를 바탕으로 토스 앱 버전 5.240.0 버전부터 아래와 같이 노출돼요.

![](/assets/game_ranking.FXD3b7tr.png)

### **① 스토어 출시 심사를 받았다면, 해당 스토어 URL을 입력해 주세요.**

오픈마켓(앱스토어, 구글 플레이 스토어, 원스토어, Microsoft Store)를 통해 등급 분류를 받은 경우에는 오픈마켓에 출시된 게임 페이지의 URL 및 자체등급분류 게임물 정보 입력이 필요해요.

오픈마켓을 통해 등급 분류를 받은 경우 입력해야 하는 정보는 다음과 같아요.

::: tip 게임 등급 정보 및 자체등급분류 게임물 정보를 왜 입력해야 하나요?

* 게임물관리위원회 규정에 따라 ‘자체등급분류사업자를 통해 등급을 받은 게임과 앱인토스를 통해 출시하려는 게임이 동일한 게임인지 확인하기 위함이에요.
* 이를 지키지 않을 경우 등급미필 게임물로 간주되어 시정 권고, 수사의뢰 또는 행정처분의뢰 등 행정조치로 이어질 수 있어요.
  :::

![](/assets/console_game_ranking.D2n4Bv_C.png)

**\[게임 등급 정보]**

* ‘스토어 링크’ 로 변경 후 게임이 출시된 페이지의 링크를 입력해 주세요.

**\[기본 정보]**

* 사업자인 경우 사업자 등록증 상의 정보를 입력해 주세요.
* 개인 개발자(비사업자)인 경우 개인 본인 정보를 입력해 주세요.

**\[자체등급분류 게임물 정보]**\
아래 정보를 작성하기 위해 게임물관리위원회의 [**‘자체등급분류 게임물 조회’**](https://www.grac.or.kr/Statistics/SelfRateGameStatistics.aspx)페이지에서 오픈마켓에 출시한 게임을 먼저 조회해 주세요.

* **등록자명:** 스토어에서 조회되는 등록자명 입력이 필요해요. **‘구글플레이스토어’** 의 경우 개발자명을, **‘애플 앱스토어’** 의 경우 제공자명을 입력해 주세요.
* **자체등급분류사업자명:** ‘구글’, ‘애플’, ‘원스토어’ 등과 같이 자체등급분류를 진행한 오픈마켓의 사업자명을 입력해 주세요.
* **등급분류일자:** 게임물관리위원회에서 조회한 등급 분류 일자와 동일하게 입력해 주세요.
* **등급분류번호:** 게임물관리위원회에서 조회한 등급 분류 번호와 동일하게 입력해 주세요.
* **이용등급:** 게임물관리위원회에서 조회한 이용등급과 동일한 등급을 선택해 주세요.
* **내용정보:** 게임물관리위원회에서 조회한 내용정보에 표시된 항목을 모두 선택해 주세요. 만약 전체 이용가인 경우에도 내용정보가 있다면 선택해 주세요.
* **대표자 인감 또는 사인 이미지:** 대표자의 인감 또는 사인 이미지를 첨부해 주세요. 흰 종이에 인감 도장만 날인을 하거나 서명을 해서 이미지를 첨부해 주세요.

**\[게임의 주요 내용이 담긴 화면 첨부 (플레이 화면)]**\
자체등급분류를 받은(오픈마켓에 출시한) 게임 플레이 화면 2장과 앱인토스를 통해 출시하는 게임물 플레이 화면 2장을 각각 첨부해 주세요.

* 이미지 첨부 시 별도로 편집을 하지 않고 원본 플레이 화면을 그대로 첨부해 주세요.
* 만약, 내용정보에서 선정성 및 폭력성이 있는 경우 해당하는 게임 화면 이미지를 각각 첨부해 주세요.

::: tip 게임물 등록자명과 사업자명이 다르면 어떻게 하나요?
자체등급분류 게임물에 표기된 등록자명과 실제 사업자명이 다를 경우 검수에서 반려돼요.\
만약 다른 사유를 소명할 수 있다면 증빙자료 또는 사유를 추가로 제출해 주세요.

* 개인(비사업자): 등록자명과 사업자명이 다른 사유를 작성해 주세요.
* 사업자(개인 또는 법인): 등기부등본을 제출하여 사업체 이름이 변경 되었다거나 하는 등의 사유를 소명해 주세요.
  :::

### **② 게임물관리위원회의 심의를 받았다면, 증명서를 PDF 파일로 첨부해 주세요.**

‘게임물관리위원회’를 통한 등급분류 심의를 받았다면 심의 증명서를 PDF파일로 첨부해 주세요.

![](/assets/console_game_ranking_2.Cf5l1qtp.png)

**\[게임 등급 정보]**

* ‘게임물 등급분류증명서’ 로 변경 후 등급심의 증명서를 PDF로 첨부해 주세요.

**\[자체등급분류 게임물 정보]**

* 게임물 등급분류증명서에 나온 내용과 동일하게 입력해 주세요.

### ③ 아직 등급 정보가 없다면, 출시 전에 꼭 등급 정보를 등록해 주세요.

등급 정보 없이는 출시할 수 없으니 게임물 등급분류증명서를 미리 준비해 주세요.

[게임물 등급분류 신청 방법 보러가기](https://toss.im/apps-in-toss/blog/game_rating_classification)

![](/assets/console_game_ranking_3.B5Q75YIp.png)

앱 등록 가이드라인에 알맞게 입력을 완료한 이후 **‘검토 요청하기’** 버튼을 눌러주세요.\
검토는 영업일 기준 1~2일이 소요되며, 검토 결과는 콘솔과 이메일로 안내해 드려요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/useParams.md
---

# 쿼리 파라미터 사용하기

## `useParams`

`useParams`는 지정된 라우트에서 파라미터를 가져오는 훅이에요.

애플리케이션이 [URL 스킴](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)으로 실행될 때, 스킴에 포함된 [쿼리 스트링](https://en.wikipedia.org/wiki/Query_string) 값을 참조할 수 있어요. 스킴으로 애플리케이션을 실행할 때, 필요한 데이터를 전달하거나 특정 기능을 활성화할 수 있어요.

추가로 `validateParams` 옵션을 활용하면, 화면에서 필요한 쿼리 파라미터를 정의하고 유효성을 검사할 수 있어요.

## 시그니처

```typescript
function useParams<TScreen extends keyof RegisterScreen>(options: {
    from: TScreen;
    strict?: true;
}): RegisterScreen[TScreen];
```

### 파라미터

## 예제

### 라우트 파라미터 가져오기

::: code-group

```tsx [React Native]
import React from 'react';
import { Text } from 'react-native';
import { createRoute, useParams } from '@granite-js/react-native';

export const Route = createRoute('/examples/use-params', {
  validateParams: (params) => params as { id: string },
  component: UseParamsExample,
});

function UseParamsExample() {
  // 첫 번째 방법: 라우트 객체의 `useParams` 메서드 사용
  const params = Route.useParams();

  // 두 번째 방법: useParams 훅 직접 사용
  const params2 = useParams({ from: '/examples/use-params' });

  // 세 번째 방법: strict 모드를 false로 설정하여 사용
  // strict: false로 설정하면 현재 라우트의 파라미터를 가져오며,
  // validateParams가 정의되어 있어도 검증을 건너뛰어요.
  const params3 = useParams({ strict: false }) as { id: string };

  return (
    <>
      <Text>{params.id}</Text>
      <Text>{params2.id}</Text>
      <Text>{params3.id}</Text>
    </>
  );
}
```

:::

## 쿼리 스트링 값 유효성 검증하기

필수로 포함해야 하는 쿼리 파라미터는 `validateParams` 옵션을 사용해서 유효성을 검사할 수 있어요.

예를 들어, 아래 예시 코드는 `name` 파라미터가 없으면 에러를 발생시켜요.

그래서 필수 쿼리 파라미터가 누락되지 않도록 `validateParams` 옵션을 사용해요.

::: code-group

```tsx [vanilla]
import { createRoute } from '@granite-js/react-native';
import { View, Text } from "react-native";

export const Route = createRoute("/", {
  component: Index,
  validateParams: (params) => {
    if (!("name" in params)) {
      throw Error("name is required");
    }
    if (typeof params.name !== "string") {
      throw Error("name must be a string");
    }

    if (!("age" in params)) {
      throw Error("age is required");
    }
    if (typeof params.age !== "number") {
      throw Error("age must be a number");
    }

    return params as {
      name: string;
      age: number;
    };
  },
});

function Index() {
  const { name, age } = Route.useParams();

  return (
    <View>
      <Text>이름: {name}</Text>
      <Text>나이: {age}</Text>
    </View>
  );
}
```

```tsx [valibot]
import { createRoute } from '@granite-js/react-native';
import { View, Text } from "react-native";
import * as v from "valibot";

export const Route = createRoute("/", {
  component: Index,
  validateParams: (params) => {
    return v.parse(
      v.object({
        name: v.string(),
        age: v.number(),
      }),
      params
    );
  },
});

function Index() {
  const { name, age } = Route.useParams();

  return (
    <View>
      <Text>이름: {name}</Text>
      <Text>나이: {age}</Text>
    </View>
  );
}
```

```tsx [zod]
import { createRoute } from '@granite-js/react-native';
import { View, Text } from "react-native";
import { z } from "zod";

export const Route = createRoute("/", {
  component: Index,
  validateParams: (params) => {
    return z
      .object({
        name: z.string(),
        age: z.number(),
      })
      .parse(params);
  },
});

function Index() {
  const { name, age } = Route.useParams();

  return (
    <View>
      <Text>이름: {name}</Text>
      <Text>나이: {age}</Text>
    </View>
  );
}
```

:::

## 쿼리 파라미터 값 변환하기

`createRoute.parserParams` 옵션을 사용하면 쿼리 스트링으로 전달된 `string` 값을 원하는 타입으로 변환할 수 있어요.\
기본적으로 `useParams`는 숫자, 문자열, 배열, 객체 같은 대부분의 단순 타입은 자동으로 변환하기 때문에 파서를 직접 재정의해야 할 일은 많지 않아요.\
하지만 복잡한 데이터 구조를 사용해야 할 때나 특정한 params를 지우고 싶을 때는 파서를 직접 정의해서 원하는 타입으로 변환할 수 있어요.

`parserParams` 옵션의 결과가 `validateParams` 옵션에 전달되기 전에 변환됩니다.

### 기본 파서를 사용한 타입 변환

기본 파서를 활용하면 쿼리 스트링 값이 자동으로 적절한 타입으로 변환돼요. 아래 예제는 쿼리 파라미터를 타입에 맞게 변환하는 방법을 보여줘요.

```tsx
import { createRoute } from '@granite-js/react-native';
import { View, Text } from "react-native";

// URL 예시: intoss://test-app?name=tom&age=10&arr=1,2,3&obj={"name":"jane","age":20}
export const Route = createRoute("/", {
  component: Index,
  validateParams: (params) => ({
    // 기본 파서로 인해 쿼리 파라미터 값을 올바른 타입으로 자동으로 변환
    name: params.name as string, // 문자열로 변환
    age: params.age as number, // 숫자로 변환
    arr: params.arr as string[], // 배열로 변환
    obj: params.obj as { name: string; age: number }, // 객체로 변환
  }),
});

function Index() {
  const { name, age, arr, obj } = Route.useParams();

  return (
    <View>
      <Text>
        이름: {name}, 타입: {typeof name}
      </Text>
      <Text>
        나이: {age}, 타입: {typeof age}
      </Text>
      <Text>
        배열: {JSON.stringify(arr)}, 타입: {typeof arr}
      </Text>
      <Text>
        객체: {JSON.stringify(obj)}, 타입: {typeof obj}
      </Text>
    </View>
  );
}
```

### 파서 재정의

`parserParams` 옵션을 사용하면 기본 파서로 처리하기 어려운 query parameter를 변환하는 함수를 직접 정의해서 사용할 수 있어요. 예를 들어, 특정 파라미터(`referer`)를 제거하고 나머지 파라미터를 기본 파서로 처리하는 방법을 아래 코드에서 보여줘요.

```tsx
import { createRoute } from '@granite-js/react-native';
import { View, Text } from "react-native";

// URL 예시: intoss://test-app?name=tom&age=10&referer=https://google.com
export const Route = createRoute("/", {
  component: Index,

  // 특정 파라미터를 제거하고 나머지를 기본 파서로 처리 // [!code highlight:5]
  parserParams: (params) => {
    const { referer, ...rest } = params;
    return rest;
  },

  validateParams: (params) => {
    // [!code highlight:11]
    // 여기서 `params`는 parserParams 함수에서 변환된 값이에요.
    // 즉, `referer`는 이미 제거된 상태로 전달돼요.
    return {
      name: params.name,
      age: params.age,
    } as {
      name: string;
      age: number;
    };
  },
});

// 컴포넌트에서 파라미터 사용
function Index() {
  const { name, age } = Route.useParams();

  return (
    <View>
      <Text>
        이름: {name}, 타입: {typeof name}
      </Text>
      <Text>
        나이: {age}, 타입: {typeof age}
      </Text>
    </View>
  );
}
```

::: tip 중복된 쿼리 파라미터 주의사항
만약 같은 이름의 쿼리 파라미터가 여러 번 사용되면, 해당 값은 배열로 반환돼요. 예를 들어, `age` 파라미터가 두 번 포함되면 다음과 같이 처리돼요.

```js
// 스킴: `intoss://test-app?name=tom&age=10&age=20`
const params = useParams({
  from: "/",
});

// params
{ name: 'tom', age: [10, 20] }
```

:::

***

::: tip 이전 버전 문서가 필요할 때
이전 버전의 문서는 [쿼리 파라미터 사용하기](/learn-more/query-parameter-deprecated)에서 확인할 수 있어요.
:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/learn-more/query-parameter-deprecated.md
description: 앱인토스 미니앱의 쿼리 파라미터 사용 가이드 (Deprecated)입니다.
---

::: tip 최신 문서를 참고하세요
최신 버전의 문서는 [쿼리 파라미터 사용하기](/bedrock/reference/framework/화면%20제어/useParams)에서 확인할 수 있어요.
:::

# 쿼리 파라미터 사용하기

애플리케이션이 [URL 스킴](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)으로 실행될 때, 스킴에 포함된 [쿼리 스트링](https://en.wikipedia.org/wiki/Query_string) 값을 참조할 수 있어요. 스킴으로 애플리케이션을 실행할 때, 필요한 데이터를 전달하거나 특정 기능을 활성화할 수 있어요.

## 쿼리 파라미터로 데이터 전달하기

애플리케이션을 실행할 때, URL에 데이터의 키-값 쌍을 쿼리 파라미터 형태로 추가할 수 있어요.

예를 들면 다음과 같은 형태에요.

```
supertoss://m/{서비스 이름}?key1=value1&key2=value2
```

이 예시에서는 `test-app`이라는 이름의 애플리케이션을 실행하고, `name`과 `age` 데이터를 전달할 수 있어요.

```
supertoss://m/test-app?name=tom&age=10
```

## 특정 쿼리 파라미터 값 가져오기

useParams 훅을 사용해서 애플리케이션이 실행될 때 전달된 쿼리 스트링 값을 가져올 수 있어요. `useParams`은 주어진 키에 해당하는 값을 반환해요.

```tsx
import { useParams } from "@granite-js/react-native"; // [!code focus]
import { View, Text } from "react-native";

function Component() {
  // 'name' 키에 해당하는 쿼리 스트링 값을 가져와요. // [!code focus]
  const name = useParams("name"); // [!code focus]

  return (
    <View>
      <Text>이름: {name}</Text>
    </View>
  );
}
```

## 쿼리 파라미터 값 변환하기

`useParams` 훅의 `parser` 옵션을 사용하면, `string`으로 전달되는 쿼리 스트링 값을 원하는 타입으로 바꿔서 사용할 수 있어요.

예를 들어 다음 예시에서는 `age` 쿼리 스트링이 문자열로 전달되지만, `parser` 옵션을 사용해서 숫자로 변환해서 사용할 수 있어요. `parser`를 활용하면 그 외에도 다양한 전처리를 할 수 있어요.

```tsx
import { useParams } from "@granite-js/react-native";
import { View, Text } from "react-native";

function Component() {
  // 'age' 값을 숫자 타입으로 변환해서 사용해요.
  const parsedAge = useParams("age", {
    parser: (value) => parseInt(value, 10),
  });

  return (
    <View>
      <Text>나이: {parsedAge}</Text>
    </View>
  );
}
```

## 쿼리 스트링 값 유효성 검증하기

특정 쿼리 파라미터가 반드시 포함되어야 한다면, `useParams` 훅의 `required `옵션을 사용할 수 있어요. 예를 들어, `name` 파라미터가 없으면 에러를 발생시켜요.

이렇게 필수 쿼리 파라미터가 누락되지 않도록 강제할 수 있어요.

```tsx
import { useParams } from '@granite-js/react-native';
import { View, Text } from "react-native";

function Component() {
  // 'name' 키가 반드시 쿼리 스트링에 포함되어야 해요.
  const name = useParams("name", { required: true });

  return (
    <View>
      <Text>이름: {name}</Text>
    </View>
  );
}
```

## 모든 쿼리 스트링 값 참조하기

useParams 훅을 사용하면 전달된 모든 쿼리 파라미터 값을 객체로 가져올 수 있어요. `useParams`는 스킴에 포함된 모든 쿼리 스트링 값을 객체 형태로 반환해요. 이 객체의 각 키는 쿼리 스트링의 키와 일치하고, 값은 해당 키에 대한 쿼리 스트링 값이에요.

```tsx
import { useParams } from '@granite-js/react-native'; // [!code focus]
import { View, Text } from "react-native";

function Component() {
  // 모든 쿼리 스트링 값을 객체로 가져와요. // [!code focus]
  const params = useParams(); // [!code focus]

  return (
    <View>
      <Text>이름: {params.name}</Text>
      <Text>나이: {params.age}</Text>
    </View>
  );
}
```

::: tip 중복된 쿼리 파라미터 주의사항

동일한 이름을 가진 쿼리 파라미터가 여러 번 사용되면, 그 값들은 배열로 반환돼요. 예를 들어, `age` 파라미터가 두 번 포함되었다면 다음과 같이 처리돼요.

```js
// 스킴: `supertoss://m/test-app?name=tom&age=10&age=20`
const params = useParams();

// params
{ name: 'tom', age: ['10', '20'] }
```

이처럼 중복된 쿼리 스트링 값은 배열로 처리되므로, 특정 값만 사용할 때는 배열에서 원하는 값을 직접 선택해서 사용해야 해요.

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/분석/LoggingPress.md
---

# 클릭 이벤트 기록하기

## `LoggingPress`

`LoggingPress` 는 요소가 사용자 액션에 의해 눌렸을 때 눌렸다고 로그를 남기는 컴포넌트예요. 예를 들어, 버튼을 눌러 구매를 하는 로그를 남기고 싶을 때 사용해요.

::: tip 잠시만요

샌드박스나 QR 테스트 환경에서는 클릭 이벤트가 실제로 쌓이지 않아요.

이벤트는 라이브 환경에서만 수집돼요.

또한 콘솔에서 데이터를 확인할 수 있는 시점은 **+1일 후** 예요.

:::

## 시그니처

```typescript
LoggingPress: import("react").ForwardRefExoticComponent<LoggingPressProps & import("react").RefAttributes<unknown>>
```

## 예제

### 클릭 가능한 요소의 클릭 이벤트를 자동으로 수집하는 예시

```tsx
import { Analytics } from '@apps-in-toss/framework';
import { Button } from 'react-native';

// 클릭 가능한 요소의 클릭 이벤트를 자동으로 수집해요.
function TrackElements() {
  return (
    <Analytics.Press>
      <Button label="Press Me" />
    </Analytics.Press>
  );
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/클립보드/getClipboardText.md
---

# 클립보드 텍스트 가져오기

## `getClipboardText`

클립보드에 저장된 텍스트를 가져오는 함수예요. 복사된 텍스트를 읽어서 다른 작업에 활용할 수 있어요.

## 시그니처

```typescript
function getClipboardText(): Promise<string>;
```

### 프로퍼티

### 반환 값

## GetClipboardTextPermissionError

클립보드 읽기 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof GetClipboardTextPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class GetClipboardTextPermissionError extends PermissionError {
    constructor();
}
```

## 예제

### 클립보드의 텍스트 가져오기

클립보드의 텍스트를 가져오는 예제예요.
"권한 확인하기"버튼을 눌러서 현재 클립보드 읽기 권한을 확인해요.
사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`GetClipboardTextPermissionError`](./GetClipboardTextPermissionError)를 반환해요.
"권한 요청하기"버튼을 눌러서 클립보드 읽기 권한을 요청할 수 있어요.

::: code-group

```js [js]
import {
  getClipboardText,
  GetClipboardTextPermissionError,
} from '@apps-in-toss/web-framework';

async function handleGetClipboardText() {
  try {
    const clipboardText = await getClipboardText();
    console.log('클립보드 텍스트:', clipboardText || '클립보드에 텍스트가 없어요.');
  } catch (error) {
    if (error instanceof GetClipboardTextPermissionError) {
      console.log('클립보드 읽기 권한 없음');
    }
    console.error(error);
  }
}

async function handleGetPermissionForGetClipboardText() {
  const permission = await getClipboardText.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForGetClipboardText() {
  const permission = await getClipboardText.openPermissionDialog();
  return permission;
}
```

```tsx [React]
import {
  getClipboardText,
  GetClipboardTextPermissionError,
  SetClipboardTextPermissionError,
} from '@apps-in-toss/web-framework';
import { useState } from 'react';

function PasteButton() {
  const [text, setText] = useState(''); 

  const handlePress = async () => {
    try {
      const clipboardText = await getClipboardText();
      setText(clipboardText || '클립보드에 텍스트가 없어요.');
    } catch (error) {
      if (error instanceof GetClipboardTextPermissionError) {
        // 클립보드 읽기 권한 없음
      } 
    }
  };

  return (
    <div>
      <span>{text}</span>
      <input type="button" value="붙여넣기" onClick={handlePress} />
      <input type="button"
        value="권한 확인하기"
        onClick={async () => {
          const permission = await getClipboardText.getPermission();
          alert(permission);
        }}
      />
      <input type="button"
        value="권한 요청하기"
        onClick={async () => {
          const permission = await getClipboardText.openPermissionDialog();
          alert(permission);
        }}
      />
    </div>
  );
}
```

```tsx [React Native]
import {
  getClipboardText,
  GetClipboardTextPermissionError,
  SetClipboardTextPermissionError,
} from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function PasteButton() {
  const [text, setText] = useState('');

  const handlePress = async () => {
    try {
      const clipboardText = await getClipboardText();
      setText(clipboardText || '클립보드에 텍스트가 없어요.');
    } catch (error) {
      if (error instanceof GetClipboardTextPermissionError) {
        // 클립보드 읽기 권한 없음
      }
    }
  };

  return (
    <View>
      <Text>{text}</Text>
      <Button title="붙여넣기" onPress={handlePress} />
      <Button
        title="권한 확인하기"
        onPress={async () => {
          const permission = await getClipboardText.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="권한 요청하기"
        onPress={async () => {
          const permission = await getClipboardText.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-clipboard-text](https://github.com/toss/apps-in-toss-examples/tree/main/with-clipboard-text) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/클립보드/setClipboardText.md
---

# 클립보드 텍스트 복사하기

## `setClipboardText`

텍스트를 클립보드에 복사해서 사용자가 다른 곳에 붙여 넣기 할 수 있어요.

## 시그니처

```typescript
function setClipboardText(text: string): Promise<void>;
```

### 파라미터

### 프로퍼티

## SetClipboardTextPermissionError

클립보드 쓰기 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof SetClipboardTextPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class SetClipboardTextPermissionError extends PermissionError {
    constructor();
}
```

## 예제

### 텍스트를 클립보드에 복사하기

텍스트를 클립보드에 복사하는 예제예요.
"권한 확인하기"버튼을 눌러서 현재 클립보드 쓰기 권한을 확인해요.
사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`SetClipboardTextPermissionError`](./SetClipboardTextPermissionError)를 반환해요.
"권한 요청하기"버튼을 눌러서 클립보드 쓰기 권한을 요청할 수 있어요.

::: code-group

```js [js]
import { setClipboardText, SetClipboardTextPermissionError } from '@apps-in-toss/web-framework';

async function handleSetClipboardText() {
  try {
    await setClipboardText('복사할 텍스트');
    console.log('텍스트가 복사됐어요!');
  } catch (error) {
    if (error instanceof SetClipboardTextPermissionError) {
      console.log('텍스트 쓰기 권한 없음');
    }
    console.error(error);
  }
}

async function handleGetPermissionForSetClipboardText() {
  const permission = await setClipboardText.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForSetClipboardText() {
  const permission = await setClipboardText.openPermissionDialog();
  return permission; 
}
```

```tsx [React]
import { setClipboardText, SetClipboardTextPermissionError } from '@apps-in-toss/web-framework';

function CopyButton() {
  const handleCopy = async () => {
    try {
      await setClipboardText('복사할 텍스트');
      console.log('텍스트가 복사됐어요!');
    } catch (error) {
      if (error instanceof SetClipboardTextPermissionError) {
        // 텍스트 쓰기 권한 없음
      }
    }
  };

  return (
    <>
      <input type="button" value="복사" onClick={handleCopy} />
      <input type="button"
        value="권한 확인하기"
        onClick={async () => {
          const permission = await setClipboardText.getPermission();
          Alert.alert(permission);
        }}
      />
      <input type="button"
        value="권한 요청하기"
        onClick={async () => {
          const permission = await setClipboardText.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </>
  );
}
```

```tsx [React Native]
import { setClipboardText, SetClipboardTextPermissionError } from '@apps-in-toss/framework';
import { Alert, Button } from 'react-native';

function CopyButton() {
  const handleCopy = async () => {
    try {
      await setClipboardText('복사할 텍스트');
      console.log('텍스트가 복사됐어요!');
    } catch (error) {
      if (error instanceof SetClipboardTextPermissionError) {
        // 텍스트 쓰기 권한 없음
      }
    }
  };

  return (
    <>
      <Button title="복사" onPress={handleCopy} />
      <Button
        title="권한 확인하기"
        onPress={async () => {
          const permission = await setClipboardText.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="권한 요청하기"
        onPress={async () => {
          const permission = await setClipboardText.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </>
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-clipboard-text](https://github.com/toss/apps-in-toss-examples/tree/main/with-clipboard-text) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/development/test/sandbox.md'
description: '앱인토스 샌드박스 앱을 이용한 개발 및 테스트 가이드입니다. 샌드박스 앱 설치, 로그인, 앱 선택, 로컬 서버 연결 방법을 확인하세요.'
---

# 테스트앱(샌드박스)

앱인토스는 개발용 토스앱을 별도로 제공하지 않아요.\
대신 **전용 샌드박스 앱**을 통해 개발·테스트 환경을 구성할 수 있어요.

::: tip 반드시 확인해주세요
실서비스 출시 전, 샌드박스 앱에서 **기능 검증을 완료**해야 해요.\
샌드박스 검증 없이 진행한 기능은 런칭 또는 검수 단계에서 **반려될 수 있어요.**
:::

## 샌드박스 앱이란?

앱인토스는 토스앱 안에서 파트너사의 서비스를 **앱인앱(App-in-App)** 형태로 제공해요.\
별도의 개발용 토스앱 대신, **개발·QA 전용 샌드박스 앱**을 통해 연동 테스트를 진행할 수 있어요.

샌드박스 앱을 설치한 뒤 아래 순서로 개발을 시작하세요.

1. 로그인
2. 앱 선택
3. 스킴(URL) 접속

| 구분        | 빌드번호   | 샌드박스 앱 다운로드                                                                                                                            |
| ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Android     | 2025-12-16 | 다운로드                                       |
| iOS         | 2025-12-07 | 다운로드                             |
| iOS(실기기) | 2025-11-11 |  |

::: tip App Transport Security (ATS)
App Transport Security(ATS) 정책 위반을 방지하기 위해 **샌드박스 앱에서는 http 통신이 허용**돼요.\
단, 라이브 환경에서는 **https만 지원**되므로, http 기반 기능은 샌드박스에서만 정상 동작해요.
:::

### 지원 OS 버전

OS의 최신 기능과 보안 개선 사항을 적용하기 위해, 최신 버전 환경 사용을 권장합니다.
| 구분 | 버전 |
|-----|-----|
|Android|Android 7|
|iOS|iOS 16|

## 샌드박스 앱 사용하기

### 1. 최신 버전 설치

샌드박스 앱은 수시로 업데이트돼요. 오류가 보이면 **최신 버전으로 업데이트**해 주세요.

### 2. 개발자 로그인

콘솔에서 사용하는 토스 비즈니스 계정으로 로그인하세요.\
토스 비즈니스 가입이 필요하다면 [콘솔에서 앱 등록하기](/prepare/console-workspace)를 확인해 주세요.

### 3. 앱 선택

소속된 워크스페이스의 앱 목록이 노출돼요. **테스트할 앱**을 선택하세요.

### 4. 토스 인증

콘솔에 등록한 **토스 계정**으로 본인 인증을 진행해요.\
해당 계정의 **토스앱이 설치된 스마트폰**에서 푸시를 열어 인증을 완료해 주세요.

### 5. 앱 스킴(URL)로 접속

접속할 스킴을 입력하면 미니앱이 실행돼요.

```
intoss://{appName}
```

## 샌드박스에서 테스트 가능한 기능

샌드박스에서 바로 확인 가능한 항목이에요.\
샌드박스에서 미지원인 경우에는 콘솔 ‘출시하기’의 QR 코드로 토스앱에서 테스트해 주세요.

| 기능                   | 테스트 가능 여부                 |
| ---------------------- | -------------------------------- |
| 토스 로그인            | ✅ 가능                          |
| 게임 로그인            | ✅ 가능 (단, mock 데이터 내려감) |
| 토스 페이              | ✅ 가능                          |
| 인앱 결제              | ✅ 가능                          |
| 게임 프로필 & 리더보드 | ✅ 가능                          |
| 분석                   | ❌ 불가능                        |
| 공유 리워드            | ❌ 불가능                        |
| 인앱 광고              | ❌ 불가능                        |
| 가로 버전 게임         | ❌ 불가능                        |
| 내비게이션 바 공유하기 | ❌ 불가능                        |

## 자주 묻는 질문

\<FaqAccordion :items='\[
{
q: "샌드박스에서 테스트 진행이 잘 안돼요.",
a: \`샌드박스 개발자 로그인을 진행해 주세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/tossauth/test.md'
description: 토스인증 구현 시 테스트 방법에 대한 가이드입니다. 테스트 환경을 통해 어떻게 테스트하는지 구체적인 가이드가 담겨있습니다.
---

# 테스트하기

계약이 완료되지 않아도 **토스인증 테스트 환경**에서 인증 연동을 진행해 볼 수 있어요.\
먼저 연동을 진행한 뒤 테스트를 수행해 주세요.\
테스트 시에는 **앱 스토어에서 설치한 최신 버전의 토스앱**을 이용하세요.\
**본인확인**과 **원터치 인증** 방식 모두 테스트가 가능합니다.
::: tip 테스트 환경

* client\_id : `test_a8e23336d673ca70922b485fe806eb2d`
* client\_secret : `test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3`
  :::

## 토스 앱 버전

* **토스앱 (본인확인)** : 5.233.0 이상
* **토스앱 (원터치 인증)** : 5.236.0 이상

[getTossAppVersion](/bedrock/reference/framework/환경%20확인/getTossAppVersion) 함수를 사용하여 토스앱 버전을 체크해보세요.

## 방화벽 설정

요청 서버의 **아웃바운드(Outbound)** 설정에 아래 토스인증 IP를 허용해주세요.\
모든 통신은 **443 포트(HTTPS)** 를 사용해요.

토스 인증 서버는 **인바운드(Inbound)** 가 제한 없이 오픈되어 있어, 별도 설정 없이 바로 통신 테스트를 진행할 수 있어요.

:::tip 본인확인 IP

* 117.52.3.222
* 117.52.3.235
* 211.115.96.222
* 211.115.96.235
  :::

## 라이브 환경과의 차이점

### ✅ 인증 사용료 무료

테스트 환경에서는 인증을 성공적으로 완료하더라도 **과금되지 않아요.**

### ✅ 테스트 환경 자격증명

테스트 환경의 **클라이언트 자격증명(client\_id, client\_secret)** 은 모두 `test_` 로 시작해요.\
이 접두어(prefix)를 통해 **운영 환경 정보와 쉽게 구분**할 수 있어요.

### ✅ Access Token 유효기간

테스트 환경에서는 연동 편의를 위해 **1년(31536000초)** 유효기간이 적용된 Access Token을 제공해요.
운영 환경에서는 **사업자가 신청한 네트워크 방식**에 따라 유효기간이 달라질 수 있으니 참고해주세요.

### ✅ 가상의 개인정보 제공

테스트 환경에서 인증이 완료되면,\
토스에 가입된 사용자의 암호화된 개인정보 대신 **토스가 생성한 가상 인물의 고정된 개인정보**가 전달돼요.

이는 실제 사용자 정보를 보호하기 위한 조치이며,\
정확한 사용자 정보가 필요하다면 **토스로부터 제공받은 이용기관 고유 키**를 사용해 운영 환경과 연동해야 해요.

:::info 테스트 환경에서 제공되는 가상 개인정보 예시

* CI : `CI0110000000001 ...  `
* DI : `DI0110000000001 ...  `
* 이름 : 김토스
* 생년월일 : 19930324
* 성별 : FEMALE
* 내외국인 : LOCAL
  :::

---

---
url: 'https://developers-apps-in-toss.toss.im/design/components.md'
description: '앱인토스 미니앱 개발을 위한 토스 디자인 시스템(TDS) 가이드입니다. 컴포넌트, UX 라이팅, 그래픽 리소스 등 디자인 요소를 확인하세요.'
---

# {{ $frontmatter.title }}

TDS를 사용하면 사용자에게 일관된 제품 경험을 제공하면서 디자이너가 문제 해결에만 집중할 수 있어요. 개발도 커스텀 UI 보다 3~5배 빠르게 완료할 수 있어요.

토스앱의 화면은 대부분 TDS로 구성되어 있고, 앱인토스 서비스에서 필요한 화면도 TDS로 만들 수 있을 거예요.

![TDS](https://static.toss.im/3d-common/tds-kv-text-hero.png)

## 컴포넌트 리스트

가장 자주 쓰는 컴포넌트 12개를 소개해요.\
컴포넌트를 눌러 자세히 확인해보세요.

## TDS 사용 시 유의사항

TDS를 안전하고 올바르게 사용하기 위해 꼭 확인해주세요.

### 1. 지식재산권

토스가 「앱인토스(Appintoss)」 서비스를 통하여 제공하는 모든 자료(지식재산권을 포함하되 이에 한정되지 않음)의 권리는 토스에 귀속됩니다.\
**파트너사는 해당 자료를 오직 앱인토스 서비스 이용을 위한 범위 내에서만 사용할 수 있습니다.**

### 2. 사용 권한

토스의 TDS 사용 허가는 앱인토스 서비스 제공을 위한 **제한적 사용권**을 부여하는 것입니다.\
따라서 파트너사는 이 범위를 넘어서는 결과물이나 권리를 취득할 수 없습니다.

### 3. 준수 의무 및 위반 시 조치

파트너사는 본 조항 및 관련 법령을 준수해야 합니다.\
파트너사가 이를 위반할 경우, 토스는 앱인토스 서비스 제공을 중단하거나 기타 필요한 조치를 취할 수 있습니다.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/로그인/appLogin.md
---

# 토스 로그인

## `appLogin`

`appLogin` 함수는 토스 인증으로 로그인해요. 로그인이 완료되면 다시 토스 앱으로 이동해요.

## 시그니처

```typescript
function appLogin(): Promise<{
  authorizationCode: string;
  referrer: "DEFAULT" | "SANDBOX";
}>;
```

## 예제

### 토스 인증을 통해 로그인을 하는 예제

::: code-group

```js [js]
import { appLogin } from '@apps-in-toss/web-framework';

async function handleLogin() {
  const { authorizationCode, referrer } = await appLogin();
  
  // 획득한 인가 코드(`authorizationCode`)와 `referrer`를 서버로 전달해요.
}
```

```tsx [React]
import { appLogin } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function Page() {
  async function handleLogin() {
    const { authorizationCode, referrer } = await appLogin();

    // 획득한 인가 코드(`authorizationCode`)와 `referrer`를 서버로 전달해요.
  }

  return <Button size="medium" onClick={handleLogin}>로그인</Button>;
}
```

```tsx [React Native]
import { appLogin } from '@apps-in-toss/framework';
import { Button } from "@toss/tds-react-native";

function Page() {
  async function handleLogin() {
    const { authorizationCode, referrer } = await appLogin();

    // 획득한 인가 코드(`authorizationCode`)와 `referrer`를 서버로 전달해요.
  }

  return <Button onPress={handleLogin}>로그인</Button>;
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-app-login](https://github.com/toss/apps-in-toss-examples/tree/main/with-app-login) 코드를 내려받아 체험해 보세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/game-login/migration.md'
---
# 토스 로그인 마이그레이션

**토스 로그인(`userKey`)** 을 사용하는 미니앱을 **게임 로그인(`hash`)** 으로 전환하는 방법을 안내해요.

이 문서를 따라 하면, 현재 토스 로그인을 쓰는 유저를 점진적으로 게임 로그인으로 매핑하고,\
모든 유저가 이전되면 토스 로그인 의존성을 완전히 제거할 수 있어요.

## 언제 이 가이드를 사용하나요?

* 기존에 토스 로그인 `userKey` 로 사용자 식별을 하고 있어요.
* 앞으로는 게임 로그인 `hash`값을 표준 식별자로 쓰고 싶어요.
* 토스 로그인 과정에서의 이탈을 줄이고 싶어요.

::: tip 게임이라면 반드시 게임 로그인을 사용해주세요
토스 로그인은 약관 동의 과정에서 **이탈율이 높습니다.**\
게임 로그인으로 전환하면 사용자 접근성과 전환율을 크게 개선할 수 있어요.
:::

## 핵심 개념

* **게임 로그인 hash**: [`getUserKeyForGame()`](/bedrock/reference/framework/게임/getUserKeyForGame.html) 호출로 발급되는 게임용 고유 식별자
* **토스 로그인 userKey**: 기존 토스 로그인 기반 사용자 식별자
* **매핑**: 동일 사용자의 `userKey` 와 `hash` 값을 1:1로 연결한 상태

> ⚠️ 각 게임별로 `hash` 값은 상이합니다.

## 전체 전환 흐름

1. 클라이언트에서 `getUserKeyForGame()` 으로 게임 `hash` 값을 발급받아요.
2. `getIsTossLoginIntegratedService()` 으로 토스 로그인 연동 여부를 확인해요.
3. 파트너사 서버에 매핑 여부를 조회해요.
4. 매핑되지 않았다면 `appLogin()` 을 통해 토스 로그인을 진행하고, `hash` 값을 서버로 전송해요.
5. 서버에서 토스 로그인 `userKey` 와 게임 로그인 `hash` 값을 매핑 테이블에 저장해요.
6. 이후에는 `hash` 값만으로 사용자를 식별할 수 있어요. 모든 유저가 매핑되면 토스 로그인 의존성을 제거하세요.

## 사전 구현이 필요한 API

파트너사는 아래 두 가지 API를 **직접 구현해야 해요.**\
이 API들은 앱인토스에서 제공하지 않으며, 아래 예시를 참고해 파트너사 서버에서 자체적으로 개발해 주세요.

* **매핑 여부 조회**
  * `POST /api/auth/migration/status`
  * **Req**: `{ hash: string }`
  * **Res**: `{ isMapped: boolean }`

* **매핑 생성**
  * `POST /api/auth/migration/link`
  * **Req**: `{  hash: string; authorizationCode: string; referrer?: string }`
  * **Res**: `{ success: true }`

***

## 클라이언트 구현 단계

### 1. SDK 가져오기

```tsx
import { getUserKeyForGame, getIsTossLoginIntegratedService, appLogin } from '@apps-in-toss/web-framework';
```

### 2. 게임 hash 값 발급

```tsx
  const result = await getUserKeyForGame();
  if (!result) return console.warn('지원하지 않는 앱 버전이에요.');
  if (result === 'INVALID_CATEGORY') return console.error('게임 카테고리가 아닌 미니앱이에요.');
  if (result === 'ERROR') return console.error('사용자 키 조회 중 오류가 발생했어요.');
  if (result.type !== 'HASH') return console.error('알 수 없는 반환값입니다.');
  const { hash } = result;
```

### 3. 토스 로그인 연동 여부 확인

```tsx
  const status = await getIsTossLoginIntegratedService();
  if (status === 'INVALID_CLIENT') {
    console.log('토스 로그인이 연동되어 있지 않은 미니앱이에요.');
    return;
  }
```

자세한 내용은 [토스 로그인 연동 확인](/bedrock/reference/framework/로그인/getIsTossLoginIntegratedService.md) 문서를 확인해주세요.

### 4. 파트너사 서버에 매핑 여부 조회 및 매핑

```tsx
  if (status === true) { // 토스 로그인 연동된 유저
    const { isMapped } = await fetch('/api/auth/migration/status', { // 매핑 여부 확인
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ hash }),
    }).then((r) => r.json());

    if (!isMapped) {
      const { authorizationCode, referrer } = await appLogin(); // 미매핑이면 토스 로그인 후 매핑 생성
      await fetch('/api/auth/migration/link', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ authorizationCode, referrer, hash }),
      });
    }

    console.log('매핑 완료 또는 이미 매핑된 사용자에요.');
    return;
  } 

  console.log ('토스 로그인 미연동 사용자에요.') // status === false
  
```

### 5. 게임 로그인 hash 사용

이제 사용자 식별은 게임 로그인 `hash`값을 기준으로 하면 됩니다.\
토스로그인 `userKey` 대신, `getUserKeyForGame()` 으로 발급받은 게임 `hash`값을 서버와 클라이언트 모두에서 사용자 식별자로 사용하세요.

## 전체 예시 코드

```tsx
import { getUserKeyForGame, getIsTossLoginIntegratedService, appLogin } from '@apps-in-toss/web-framework';

async function migrateIfNeeded() {
  const res = await getUserKeyForGame();
  if (!res) return console.warn('지원하지 않는 앱 버전이에요.');
  if (res === 'INVALID_CATEGORY') return console.error('게임 카테고리가 아닌 미니앱이에요.');
  if (res === 'ERROR') return console.error('사용자 키 조회 중 오류가 발생했어요.');
  if (res.type !== 'HASH') return console.error('알 수 없는 반환값입니다.');
  const { hash } = res;

  let status: boolean;
  try {
    status = await getIsTossLoginIntegratedService();
  } catch (error: any) {
    console.error('토스 로그인 연동 여부 확인 중 오류 발생:', error);
    return;
  }

  if (status === true) {
    // 매핑 여부 조회
    const { isMapped } = await fetch('/api/auth/migration/status', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ hash }),
    }).then((r) => r.json());

    if (!isMapped) {
      // 미매핑이면 토스 로그인 후 매핑 생성
      const { authorizationCode, referrer } = await appLogin();

      await fetch('/api/auth/migration/link', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ authorizationCode, referrer, hash }),
      });
    }

    console.log('매핑 완료 또는 이미 매핑된 사용자입니다.');
    return;
  }

  // status === false : 토스 로그인 기능은 있으나 현재 유저는 미연동
  console.log('토스 로그인 미연동 사용자입니다.');
}

```

### ⚠️ 예외 처리

토스 로그인을 사용하지 않는 미니앱에서\
`getIsTossLoginIntegratedService()`를 호출하면 아래 예외가 발생할 수 있어요.

```tsx
@throw {message: "oauth2ClientId 설정이 필요합니다."}
```

> 이 경우 토스 로그인 기능이 없는 환경이므로 별도 처리가 필요하지 않습니다.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/로그인/getIsTossLoginIntegratedService.md
---

# 토스 로그인 연동 확인

## `getIsTossLoginIntegratedService`

`getIsTossLoginIntegratedService` 함수는 해당 유저가 토스 로그인에 연동된 유저인지 식별하는 값을 반환해요.\
토스 로그인에서 게임 로그인으로의 마이그레이션 과정에 사용돼요.

## 시그니처

```tsx
function getIsTossLoginIntegratedService(): Promise<boolean>
```

| 반환 타입              | 설명                                                   |
| ------------------ | ---------------------------------------------------- |
| `Promise<boolean>` | 현재 서비스가 토스 로그인과 연동되어 있다면 `true`, 아니면 `false`를 반환합니다. |

## 예제

::: code-group

```js [js]
import { getIsTossLoginIntegratedService } from '@apps-in-toss/web-framework';

async function handleGetIsTossLoginIntegratedService() {
  try {
    const result = await getIsTossLoginIntegratedService();

    if (result === undefined) {
      console.warn('지원하지 않는 앱 버전이에요.');
      return;
    }
    if (result === true) {
      console.log('토스 로그인이 연동된 유저에요.');
      // 여기에서 토스 로그인 연동 유저에 대한 처리를 할 수 있어요.
    }
    if (result === false) {
      console.log('토스 로그인이 연동되지 않은 유저에요.');
      // 여기에서 토스 로그인 연동 유저가 아닌 경우에 대한 처리를 할 수 있어요.
    }
  } catch (error) {
    console.error(error);
  }
}
```

```tsx [React]
import { getIsTossLoginIntegratedService } from '@apps-in-toss/web-framework';

function GetIsTossLoginIntegratedServiceButton() {
  async function handleClick() {
    try {
      const result = await getIsTossLoginIntegratedService();

      if (result === undefined) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }
      if (result === true) {
        console.log('토스 로그인이 연동된 유저에요.');
        // 여기에서 토스 로그인 연동 유저에 대한 처리를 할 수 있어요.
      }
      if (result === false) {
        console.log('토스 로그인이 연동되지 않은 유저에요.');
        // 여기에서 토스 로그인 연동 유저가 아닌 경우에 대한 처리를 할 수 있어요.
      }
    } catch (error) {
      console.error(error);
    }
  }

  return (
    <button onClick={handleClick}>토스 로그인 통합 서비스 여부 확인</button>
  );
}
```

```tsx [React Native]
import { Button } from 'react-native';
import { getIsTossLoginIntegratedService } from '@apps-in-toss/framework';

function GetIsTossLoginIntegratedServiceButton() {
  async function handlePress() {
    try {
      const result = await getIsTossLoginIntegratedService();

      if (result === undefined) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }
      if (result === true) {
        console.log('토스 로그인이 연동된 유저에요.');
        // 여기에서 토스 로그인 연동 유저에 대한 처리를 할 수 있어요.
      }
      if (result === false) {
        console.log('토스 로그인이 연동되지 않은 유저에요.');
        // 여기에서 토스 로그인 연동 유저가 아닌 경우에 대한 처리를 할 수 있어요.
      }
    } catch (error) {
      console.error(error);
    }
  }

  return (
    <Button onPress={handlePress} title="토스 로그인 통합 서비스 여부 확인" />
  );
}
```

:::

토스 로그인을 사용하지 않는 미니앱에서 `getIsTossLoginIntegratedService()`를 호출하면\
아래 예외가 발생할 수 있어요.

```tsx
@throw {message: "oauth2ClientId 설정이 필요합니다."}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인증/tosscert.md
description: Bedrock 프레임워크 레퍼런스 문서입니다.
---

# 토스 인증

고객이 입력한 개인정보를 토스에 등록된 정보와 대조하고, 토스앱 인증으로 신원을 최종 확인해요.\
CI/DI가 필요한 회원가입, 로그인, 계정조회 등에서 휴대폰 본인확인을 대신해 사용할 수 있어요.\
성인 인증(연령 확인) 용도로도 활용할 수 있어요.

![본인인증 플로우](/assets/tosscert-flow.BzgVhGds.png)

## 토스 앱 준비하기

테스트를 위해 앱 스토어에서 설치한 최신 버전의 토스를 이용하세요.

## 테스트 클라이언트 자격증명 정보 준비

토스에서는 테스트 연동에 필요한 정보를 미리 안내드려요. 아래 테스트 정보를 사용해서 테스트 요청을 보낼 수 있습니다.\
AccessToken 발급 테스트를 위해 사용되는 정보입니다.

* 클라이언트 아이디 : `test_a8e23336d673ca70922b485fe806eb2d`
* 클라이언트 시크릿 : `test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3`

라이브 환경에서 이용하려면 **계약 및 키 발급**이 필요해요. 자세한 안내는 [**채널톡**](https://apps-in-toss.channel.io/workflows/787658)으로 문의해 주세요.

---

---
url: 'https://developers-apps-in-toss.toss.im/tossauth/contract.md'
description: 토스인증에 대한 소개입니다. 신원인증이 필요한 서비스인 경우 참고해주세요.
---

# 토스 인증

토스 인증은 사용자가 입력한 정보(또는 토스 앱 내 저장된 정보)를 기반으로\
**실명·생년월일·휴대전화번호 등**을 안전하게 확인하고, 토스 앱 인증을 통해 **신원을 검증하는 서비스**예요.

로그인, 가입, 조회 등 사용자 식별이 필요한 서비스에서 **CI(연계정보)** 를 포함한 식별자를 안정적으로 확보할 수 있어요.

::: tip 웹보드 게임은 본인 확인이 필수예요
관련 법령에 따라 **웹보드 게임은 본인 확인 절차가 반드시 필요**해요.\
토스 인증을 연동하면 간편하게 본인 확인(필요 시 성인 인증까지)을 진행할 수 있어요.
:::

## 토스 인증 유형

토스 인증은 두 가지 방식을 제공해요.\
두 방식 모두 최종적으로 **토스 앱 인증**을 통해 사용자를 확인한다는 점은 같으며,\
**클라이언트에서 개인정보를 입력받는지 여부**가 가장 큰 차이예요.

### ① 개인정보 기반 인증

클라이언트에서 **이름·생년월일·휴대전화번호** 를 입력받아 암호화 후 전송하는 방식이에요.

* **권장 상황**
  * 가입 또는 전환 화면에서 이미 개인정보를 수집하고 있는 경우
  * 입력 값과 **실제 가입 정보의 일치 여부**를 즉시 검증해야 하는 경우

* **흐름**
  1. 사용자가 화면에서 개인정보 입력
  2. 입력값을 암호화하여 토스 인증으로 전송
  3. 토스 앱 인증(푸시 또는 생체인증 등)
  4. 결과 수신(CI, 이름, 휴대전화번호, 인증 시각 등)

* **특징**
  * 입력값 검증(형식, 오타 등)에 유리
  * 입력 과정이 있어 사용자의 이탈률이 다소 높을 수 있음

### ② 원터치 인증

클라이언트에서 **개인정보를 입력받지 않고**, 토스 앱을 바로 호출해 한 번의 인증으로 절차를 완료하는 간소화된 방식이에요.

:::tip 원터치 인증 동작 방식
**원터치 인증**은 토스인증 서비스를 이용하는 것과 동일하고, 아래와 같이 동작해요.

* 기기에 토스인증서가 있다면, PIN 인증 또는 단말 생체 인증 (Face ID, 지문인증 등)

* 기기에 토스인증서가 없다면, 토스인증서 발급 후 PIN 인증 또는 단말 생체 인증
  :::

* **권장 상황**
  * **이탈 최소화 / 전환율 최적화**가 중요한 경우
  * 앱 내 간결한 로그인·재인증 UX가 필요한 경우

* **흐름**
  1. “본인 인증” 버튼 클릭
  2. 토스 앱 호출 → 사용자 인증
  3. 결과 수신(CI, 인증 시각 등)

* **특징**
  * 입력 단계가 없어 **UX가 매우 간결**
  * 기존 계정과의 매칭 로직(CI 등) 설계가 중요

## 운영 팁

* **웹보드·성인물 서비스**: 본인 확인 후 서비스 정책에 따라 **성인 여부(ageGroup 기반 정책)** 를 적용하세요.
* **재인증 정책**: 장기간 미사용 또는 주요 정보 변경(이름·번호 변경 등) 시 **재인증 주기**를 정의하면 안전해요.
* **개인정보 최소화**: 원터치 인증을 기본으로 검토하고, 필요한 경우에만 입력 기반 인증을 조합해 **개인정보 수집을 최소화**하세요.

## 계약하기

토스 인증을 사용하려면 **사전 계약**이 필요해요.\
계약 진행에는 **영업일 기준 7~14일**이 소요될 수 있어요.

::: tip '본인 확인' vs '토스 로그인'
앱인토스는 제휴사에 **토스 인증의 ‘본인 확인’ 기능**을 제공해요.\
‘본인 확인’은 사용자의 **이름·생년월일·휴대전화번호를 검증해 신원을 확인하는 서비스**예요.\
이 서비스는 **연령 확인, 실명 인증, 웹보드 게임 등 법적 신원 확인이 필요한 경우**에 사용됩니다.

반면, **‘토스 로그인’은 간편 인증 방식으로,**\
사용자가 별도의 정보 입력 없이 **토스앱을 통해 간편하게 로그인할 수 있는 기능**이에요.\
‘본인 확인’과는 **목적과 계약 구조가 다르며,**\
토스 로그인 연동을 원하신다면 [토스 로그인 가이드](/login/intro.md) 문서를 참고해 주세요.

일부 파트너사에서 두 서비스를 혼동해 잘못 계약한 사례가 있었어요.\
**계약 전 반드시 요청하시는 서비스가 ‘본인 확인’인지 ‘토스 로그인’인지 확인해 주세요.**
:::

::: tip 콘솔에서 계약이 진행되지 않아요
토스 인증 계약은 인증팀에서 **직접** 진행하고 있어요.\
콘솔을 통해 계약할 수 없으니, 아래 절차를 참고해 주세요.
:::

### 1) 서류 다운로드 및 작성

아래 서류를 다운로드해 작성해 주세요.

* 토스 전자 인증 서비스 이용 신청서, 개인(신용)정보 보안관리 약정서

### 2) 어드민 권한 정보 준비

토스 전자 인증 서비스 제휴사 어드민을 통해 **정산 금액**을 확인할 수 있어요.\
어드민 접속 권한이 필요한 담당자의 **이메일 주소**와 **전화번호**를 준비해 주세요.

### 3) 서류 제출

아래 항목을 모두 포함해 cert.support@toss.im 이메일로 제출해주세요.

* 작성 완료된 **신청서 및 약정서**
* 어드민 접속 권한이 필요한 담당자 **이메일 주소와 전화번호**

### 4) 검토 및 안내

* 담당 부서에서 서류를 검토한 후 진행 절차를 안내드려요.
* 토스 전자 인증 서비스 계약은 내부 규정에 따라 **인감 날인된 하드카피 서류**로 진행돼요.
* 서류 검토 및 우편 송부 과정을 포함하여, **영업일 기준 7~14일** 정도 소요돼요.
* 계약서 내용 수정 요청이 있는 경우, 추가 검토로 인해 기간이 더 길어질 수 있어요.

### 5) 계약 완료 및 키 발급

* 계약이 완료되면 인증팀에서 `client_id`와 `client_secret` 키를 이메일로 발급해 드려요.
* 메일 수신 후, 발급받은 키를 확인하여 개발 환경에 적용해 주세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/토스페이/TossPay.md
---

# 토스 페이

## `TossPay`

`TossPay`는 토스페이 결제 관련 함수를 모아둔 객체예요.

### 시그니처

```typescript
TossPay: {
  checkoutPayment: typeof checkoutPayment;
}
```

### 프로퍼티

## `checkoutPayment`

`checkoutPayment` 함수는 토스페이 결제창을 띄우고, 사용자 인증을 수행해요. 인증이 완료되면 성공 여부를 반환해요.

이 함수는 결제창을 통해 사용자 인증만 해요. 실제 결제 처리는 인증 성공 후 서버에서 별도로 해야 해요.

### 시그니처

```typescript
function checkoutPayment(options: CheckoutPaymentOptions): Promise<CheckoutPaymentResult>;
```

### 파라미터

### 반환 값

### 예제

토스페이 결제창 띄우고 인증 처리하기

::: code-group

```js [js]
import { checkoutPayment } from '@apps-in-toss/web-framework';

async function handleCheckoutPayment() {
  try {
    // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
    const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());
    const { success, reason } = await checkoutPayment({ payToken });

    if (success) {
      // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
      await fetch('/my-api/payment/execute', {
        method: 'POST',
        body: JSON.stringify({ payToken }),
        headers: { 'Content-Type': 'application/json' },
      });
      console.log('결제 성공');
    } else {
      console.log('인증 실패:', reason);
    }
  } catch (error) {
    console.error('결제 인증 중 오류가 발생했어요:', error);
  }
}
```

```tsx [React]
import { checkoutPayment } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function TossPayButton() {
  async function handlePayment() {
    try {
      // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
      const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());

      const { success, reason } = await checkoutPayment({ payToken });

      if (success) {
        // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
        await fetch('/my-api/payment/execute', {
          method: 'POST',
          body: JSON.stringify({ payToken }),
          headers: { 'Content-Type': 'application/json' },
        });
        console.log('결제 성공');
      } else {
        console.log('인증 실패:', reason);
      }
    } catch (error) {
      console.error('결제 인증 중 오류가 발생했어요:', error);
    }
  }

  return <Button onClick={handlePayment}>결제하기</Button>;
}
```

```tsx [React Native]
import { TossPay } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function TossPayButton() {
  async function handlePayment() {
    try {
      // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
      const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());

      const { success, reason } = await TossPay.checkoutPayment({ payToken });

      if (success) {
        // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
        await fetch('/my-api/payment/execute', {
          method: 'POST',
          body: JSON.stringify({ payToken }),
          headers: { 'Content-Type': 'application/json' },
        });
        console.log('결제 성공');
      } else {
        console.log('인증 실패:', reason);
      }
    } catch (error) {
      console.error('결제 인증 중 오류가 발생했어요:', error);
    }
  }

  return <Button onPress={handlePayment}>결제하기</Button>;
}
```

:::

## `CheckoutPaymentOptions`

`CheckoutPaymentOptions` 는 토스페이 결제창을 띄울 때 필요한 옵션이에요.

### 시그니처

```typescript
interface CheckoutPaymentOptions {
  payToken: string;
}
```

### 프로퍼티

## `CheckoutPaymentResult`

`CheckoutPaymentResult` 는 토스페이 결제창에서 사용자가 인증에 성공했는지 여부예요.

### 시그니처

```typescript
interface CheckoutPaymentResult {
  success: boolean;
  reason?: string;
}
```

### 프로퍼티

---

---
url: 'https://developers-apps-in-toss.toss.im/development/test/toss.md'
description: '토스 앱에서 미니앱을 테스트하는 방법을 안내합니다. 앱 번들 생성 및 업로드, QR 코드 테스트, 피처 테스트 방법을 확인하세요.'
---

# 토스앱

샌드박스 앱에서 테스트가 완료되었다면,\
**앱 번들(.ait)** 파일을 업로드하고 생성된 **테스트용 앱스킴**을 통해 **토스앱에서 최종 테스트**를 진행할 수 있어요.

## 1. 앱 번들 파일 생성

앱 번들은 `.ait` 확장자를 가진 파일로, 빌드된 프로젝트를 패키징한 결과물이에요.\
아래 명령어를 실행해 앱 번들을 생성하세요.\
빌드가 완료되면 프로젝트 루트 디렉토리에 `<서비스명>.ait` 파일이 생성돼요.

::: code-group

```sh [npm]
npm run build
```

```sh [pnpm]
pnpm build
```

```sh [yarn]
yarn build
```

:::

## 2. 앱 번들 업로드 및 토스앱 테스트

앱 번들을 업로드하고 토스앱에서 테스트하는 방법은 두 가지예요.

1. **콘솔에서 직접 업로드 + QR 코드 테스트**
2. **CI/CD 명령어를 통한 자동 업로드**

::: tip 앱 번들 용량 정책

* 앱 번들은 **압축 해제 기준 100MB 이하**만 업로드할 수 있어요.
* 모든 리소스(이미지, 사운드, 영상 등)을 포함하면 용량을 초과할 수 있어요.
* **리소스 파일은 빌드와 분리**하여 관리하세요.

**권장 사항**

1. 앱 실행에 필요한 최소 리소스만 번들에 포함하세요.
2. 대용량 리소스는 **외부 스토리지 또는 CDN**에서 다운로드하도록 구성해 주세요.
3. 추가 리소스는 **단계적 다운로드(Lazy Loading)** 방식을 적용하면 사용자 경험이 향상돼요.
   :::

### ① 콘솔에서 앱 번들 업로드 및 QR 테스트하기

1. 콘솔에 **앱 번들(.ait)** 파일을 업로드하세요.
2. 업로드가 완료되면 **테스트용 스킴 및 QR 코드**가 자동으로 생성돼요.

> 접속 경로:\
> 워크스페이스 선택 → 앱 선택 → 좌측 메뉴에서 **앱 출시**

![이미지](/resources/deploy/release/release-01.png)

앱 번들을 업로드한 후 **'테스트하기'** 버튼을 클릭하면 콘솔에서 **토스앱 테스트용 QR 코드**를 확인할 수 있어요.\
QR 코드를 스캔하면 **토스앱 내에서 미니앱이 실행**돼요.

QR 코드 테스트는 아래 조건을 충족해야 실행돼요.

* 토스앱에 로그인이 되어있어야 해요.
* 워크스페이스 멤버여야 해요.
* 만 19세 이상 사용자만 테스트 가능해요.

워크스페이스 멤버 전체에게 **푸시 알림을 발송**하여 테스트 참여를 유도할 수도 있어요.\
테스트 스킴(`intoss-private://`)을 직접 실행하여 테스트할 수도 있어요.

::: tip 테스트를 최소 1번 이상 완료해주세요
테스트를 최소 1회 이상 완료해야 검토 요청을 진행할 수 있어요.
:::

![이미지](/assets/release-02.XDtaaPtX.png)

![이미지](/assets/release-03.D65p_X95.png)

### ② CI/CD 명령어 사용하기

콘솔에 접속하지 않고 CLI를 통해 앱 번들을 업로드할 수 있어요.

먼저 콘솔에서 **API 키를 발급**해주세요.\
전체 앱 또는 특정 앱 단위로 접근 권한을 설정할 수 있어요.

> 접속 경로:\
> 워크스페이스 선택 → 좌측 메뉴에서 **키**

![이미지](/assets/release-17.t7JOvIEG.png)

![이미지](/assets/release-18.C62u5o8I.png)

아래 명령어를 실행해 앱 번들을 업로드하세요.\
정상적으로 업로드가 되었다면, 테스트용 앱스킴을 확인할 수 있어요.

```
npx ait deploy --api-key {API 키}
```

API 키를 등록해두면 반복 입력할 필요가 없어요.

```
npx ait token add
npx ait deploy
```

필요에 따라 아래 명령어를 사용해보세요.

| 명령어 | 용도 |
|--------|------------------|
| npx ait token --help | 도움말 보기 |
| npx ait token add \[워크스페이스명] \[API 키] | 토큰 등록하기 |
| npx ait token remove \[워크스페이스명] | 등록된 토큰 삭제하기 |
| npx ait deploy \[워크스페이스명] \[API 키] | 번들 업로드하기 |

## 3. 앱 출시 전 피처 테스트

`intoss://` 스킴은 **앱이 정식 출시된 이후에만 접근 가능해요.**\
출시 전 기능 테스트를 위해서는 업로드 시 생성된 **테스트 스킴(QR 코드)** 를 활용해야 해요.

::: tip 테스트 시 디버깅이 필요하다면?
디버깅하기 문서를 확인하여 보다 빠르게 이슈를 해결하세요.

* [WebView](/learn-more/debugging-webview.md)
* [React Native](/learn-more/debugging.md)
  :::

### ① QR 코드에서 `deploymentId` 확인하기

앱 번들을 업로드할 때마다 새로운 `deploymentId`가 발급돼요.\
테스트 스킴에서는 `_deploymentId` 는 필수 파라미터예요.

예시 :

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

### ② 스킴에 path/query 적용하여 테스트하기

* 하위 path를 적용한 경우 :

```
intoss-private://appsintoss/path/pathpath?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

* 쿼리 파라미터를 적용한 경우 : queryParams는 반드시 URL-encoding이 필요해요.

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22
```

## 문제 해결 가이드

### iOS에서 흰 화면이 보이나요?

샌드박스에서는 정상 동작하지만,\
토스앱 내에서는 **메모리 또는 리소스 부족**으로 흰 화면이 표시될 수 있어요.

* 이미지·폰트 등 리소스 용량을 줄여 빌드 파일을 최적화하세요.
* 불필요한 객체, 메모리 누수를 점검해 주세요.

### 토스앱에서 통신이 되지 않는 경우

#### 1. CORS 설정 확인

Origin 허용 목록에 다음 도메인을 등록하세요.

* `https://<appName>.apps.tossmini.com` : 실제 서비스 환경
* `https://<appName>.private-apps.tossmini.com` : 콘솔 QR 테스트 환경

#### 2. App Transport Security (ATS) 설정 확인

샌드박스에서는 HTTP 요청이 허용되지만, **라이브 환경에서는 HTTPS만 허용**됩니다.\
HTTP 기반 API는 토스앱 내에서 차단됩니다.

#### 3. iOS 서드파티 쿠키 차단 정책 확인

iOS/iPadOS 13.4 이상에서는 **서드파티 쿠키가 완전히 차단**돼요.\
쿠키 기반 로그인 대신 **토큰 기반 인증 방식**을 적용하세요.

## 자주 묻는 질문

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/공유/getTossShareLink.md
---

# 토스앱 공유 링크 만들기 (`getTossShareLink`)

`getTossShareLink` 함수는 사용자가 지정한 경로를 **토스 앱에서 열 수 있는 공유 링크**로 변환해주는 유틸이에요.\
이 링크를 다른 사람에게 전달하면, 토스 앱이 실행되며 **지정한 딥링크 화면으로 바로 이동**할 수 있어요.

토스 앱이 설치되지 않은 경우에는 다음과 같이 동작해요.

* iOS → **앱스토어**로 이동
* Android → **플레이스토어**로 이동

경로는 토스 앱 내부 화면을 가리키는 **딥링크(deep link)** 형식이어야 해요.\
예를 들어 아래와 같이 작성할 수 있어요.

```
intoss://<앱이름>
intoss://<앱이름>/about?name=test
```

또한 `ogImageUrl`을 지정하면 SNS·메신저 등 외부 플랫폼에서 공유될 때 표시되는 **미리보기(OG 이미지)** 를 직접 설정할 수 있어요.\
OG 이미지는 플랫폼별로 잘리는 방식이나 캐시 특성이 다르기 때문에, 공유 시 의도한 대로 노출되려면 아래를 지켜 주세요.

* 이미지 URL은 반드시 `https://`로 시작하는 **절대 경로**여야 합니다.
* 플랫폼별 권장 크기·비율, 파일 형식, 파일 용량 등의 세부 규칙은 내부 문서의 [OG 이미지 규칙](/marketing/open-graph.md)를 확인해 적용하세요.

OG 이미지를 잘못 설정하면 미리보기가 의도와 다르게 보이거나, 일부 플랫폼에서 아예 노출되지 않을 수 있으니 주의해주세요.

![open graph 1](/assets/open_graph_1.D1ERRA3V.png)

:::tip 캐시 관련 안내\
외부 플랫폼은 OG 메타데이터(이미지/제목/설명)를 캐싱해두기 때문에, 한 번 공유된 링크는 변경 사항이 바로 반영되지 않을 수 있어요.\
빠른 반영이 필요하다면 각 플랫폼이 제공하는 **디버거 도구**를 이용해 캐시를 직접 초기화해 주세요.

* Kakao Debugger → https://developers.kakao.com/tool/debugger/sharing
* Facebook Debugger → https://developers.facebook.com/tools/debug/\
  :::

## 시그니처

```typescript
function getTossShareLink(url: string, ogImageUrl?: string): Promise<string>;
```

### 파라미터

### 반환 값

## 예제

::: code-group

```js [js]
import { share, getTossShareLink } from '@apps-in-toss/web-framework';

async function handleShare() {
  const tossLink = await getTossShareLink(
    'intoss://my-app',
    'https://static.toss.im/icons/png/4x/icon-share-dots-mono.png',
  );

  // 생성한 링크를 메시지로 공유해요.
  await share({ message: tossLink });
}
```

```tsx [React]
import { share, getTossShareLink } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function ShareButton() {
  async function handleClick() {
    const tossLink = await getTossShareLink(
      'intoss://my-app',
      'https://static.toss.im/icons/png/4x/icon-share-dots-mono.png',
    );

    // 생성한 링크를 메시지로 공유해요.
    await share({ message: tossLink });
  }

  return <Button onClick={handleClick}>공유하기</Button>;
}
```

```tsx [React Native]
import { share, getTossShareLink } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function ShareButton() {
  async function handleClick() {
    const tossLink = await getTossShareLink(
      'intoss://my-app',
      'https://static.toss.im/icons/png/4x/icon-share-dots-mono.png',
    );

    // 생성한 링크를 메시지로 공유해요.
    await share({ message: tossLink });
  }

  return <Button onPress={handleClick}>공유하기</Button>;
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-share-link](https://github.com/toss/apps-in-toss-examples/tree/main/with-share-link) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

## 앱 출시 전 테스트 안내

`intoss://` 스킴은 **앱이 정식 출시된 이후에만 접근 가능해요.**\
출시 전 기능 테스트를 위해서는 업로드 시 생성된 **테스트 스킴(QR 코드)** 를 활용해야 해요.

::: tip 테스트 시 디버깅이 필요하다면?
디버깅하기 문서를 확인하여 보다 빠르게 이슈를 해결하세요.

* [WebView](/learn-more/debugging-webview.md)
* [React Native](/learn-more/debugging.md)
  :::

### ① QR 코드에서 `deploymentId` 확인하기

앱 번들을 업로드할 때마다 새로운 `deploymentId`가 발급돼요.\
테스트 스킴에서는 `_deploymentId` 는 필수 파라미터예요.

예시 :

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

### ② 스킴에 path/query 적용하여 테스트하기

* 하위 path를 적용한 경우 :

```
intoss-private://appsintoss/path/pathpath?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

* 쿼리 파라미터를 적용한 경우 : queryParams는 반드시 URL-encoding이 필요해요.

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/환경
  확인/getTossAppVersion.md
---

# 토스앱 버전 가져오기

## `getTossAppVersion`

`getTossAppVersion` 함수는 토스 앱 버전을 가져옵니다. 예를 들어, `5.206.0`과 같은 형태로 반환돼요. 토스 앱 버전을 로그로 남기거나, 특정 기능이 특정 버전 이상에서만 실행될 때 사용돼요.

## 시그니처

```typescript
function getTossAppVersion(): string
```

### 반환 값

## 예제

### 토스 앱 버전 확인하기

::: code-group

```js [js]
import { getTossAppVersion } from '@apps-in-toss/web-framework';

const tossAppVersion = getTossAppVersion();
```

```tsx [React]
import { getTossAppVersion } from '@apps-in-toss/web-framework';
import { Text } from '@toss/tds-mobile';

function TossAppVersionPage() {
  const tossAppVersion = getTossAppVersion();

  return <Text>{tossAppVersion}</Text>;
}
```

```tsx [React Native]
import { getTossAppVersion } from '@apps-in-toss/framework';
import { Text } from '@toss/tds-react-native';

function TossAppVersionPage() {
  const tossAppVersion = getTossAppVersion();

  return <Text>{tossAppVersion}</Text>;
}
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/데이터/saveBase64Data.md
---

# 파일 저장하기

## `saveBase64Data`

`saveBase64Data` 함수는 문자열로 인코딩된 Base64 데이터를 지정한 파일 이름과 MIME 타입으로 사용자 기기에 저장해요. 이미지, 텍스트, PDF 등 다양한 형식의 데이터를 저장할 수 있어요.

## 시그니처

```typescript
function saveBase64Data(params: SaveBase64DataParams): Promise<void>;
```

### 파라미터

## 예제

### Base64 이미지 데이터를 사용자 기기에 저장하기

::: code-group

```js [js]
import { saveBase64Data } from '@apps-in-toss/web-framework';

async function handleSaveBase64Data() {
  try {
    await saveBase64Data({
      data: 'iVBORw0KGgo...',
      fileName: 'some-photo.png',
      mimeType: 'image/png',
    });
    console.log('데이터 저장 성공');
  } catch (error) {
    console.error('데이터 저장에 실패했어요:', error);
  }
}
```

```tsx [React]
import { saveBase64Data } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function SaveButton() {
  const handleSave = async () => {
    try {
      await saveBase64Data({
        data: 'iVBORw0KGgo...',
        fileName: 'some-photo.png',
        mimeType: 'image/png',
      });
    } catch (error) {
      console.error('데이터 저장에 실패했어요:', error);
    }
  };

  return <Button onClick={handleSave}>저장</Button>;
}
```

```tsx [React Native]
import { saveBase64Data } from '@apps-in-toss/framework';
import { Button } from "@toss/tds-react-native";

function SaveButton() {
  const handleSave = async () => {
    try {
      await saveBase64Data({
        data: 'iVBORw0KGgo...',
        fileName: 'some-photo.png',
        mimeType: 'image/png',
      });
    } catch (error) {
      console.error('데이터 저장에 실패했어요:', error);
    }
  };

  return <Button onPress={handleSave}>저장</Button>;
}
```

:::

---

---
url: 'https://developers-apps-in-toss.toss.im/login/store-login.md'
---
# 파트너사 로그인 연동하기

파트너사 서비스에 토스 로그인을 연동해보세요.

## 시작하기

로그인 연동을 위해서는 사전 셋팅이 필요해요.\
아래 정보들을 cert.support@toss.im 으로 전달해주세요.

::: tip 🚨 잠시만요

파트너사 로그인 어드민 페이지는 없습니다.

:::

| 목록         | 설명                    |
|-------------|-------------------------|
| 웹/앱 여부        | 웹, 앱, 둘 다            |
| 회원 관리 키      | CI, e-mail, 휴대폰번호 등 |
| 사용자의 권한 목록 | 이름, 이메일 등 필요한 권한을 아래에서 선택해주세요 |
| 로고 이미지       | 원형, 600px x 600px 권장드려요 |
| 약관 목록         | 약관 제목과 약관 URL, 필수 여부를 보내주세요 |
| redirect\_uri     | 완료 후 보내질 화면 url 을 입력해주세요     |
| 연동 예정인 앱 버전 | 파트너사 앱에도 도입할 경우 해당됩니다       |
| 로그인 연결 끊기 API 사용 유무 | default 는 사용안함으로 설정되요 |
| 네트워크 정보      | VPN 사용 유무나 개발환경에서 사용 시 별도 등록이 필요해요 |

### 개발을 위한 키 확인하기

연동을 위해서는 아래 정보들을 받아야해요.\
위 정보들을 메일로 보내주시면 토스 로그인 담당자가 직접 회신해드립니다.

* clientId
* clientSecret
* 복호화 키

::: tip 🚨 잠시만요

앱인토스용 로그인의 clientId, 복호화 키와 상이합니다.\
앱인토스용 로그인이 아니기 때문에 mTLS 인증서 적용이 불필요해요.\
앱인토스용 로그인과 동일한 userKey 사용을 위해서는 앱인토스 콘솔에서 연동해주세요.

:::

## API 공통규격 확인하기

### 도메인 정보

https://oauth2.cert.toss.im

### API 공통 응답

**성공**

```json
// 성공일 경우 resultType이 SUCCESS로 설정되며 해당 API의 응답이 success 하위에 적재됩니다.
{
   "resultType":"SUCCESS",
   "success":{
      "sample":"data"
   }
}
```

**실패**

```json
// 실패일 경우 resultType 이 FAIL로 설정되며 해당 실패 사유가 error 하위에 적재됩니다.
{
   "resultType":"FAIL",
   "error":{
      "errorCode":"INVALID_PARAMETER",
      "reason":"요청에 실패했습니다."
   }
}
```

## 개발하기

![](/assets/store-login_0.C8LO36Um.png)

![](/assets/store-login_1.D_o05Ipz.png)

## 1. 인가 코드 받기

사용자의 인증을 요청합니다.\
사용자의 인증에 성공하면 인가 코드를 redirect\_uri 에 포함시켜 redirect 시켜요.

* Content-type : application/json
* Method : `GET`
* URL : `/authorize`

::: tip 🚨 잠시만요

인가코드의 유효시간은 10분입니다.

:::

**요청**
| 이름 | 타입 | 필수값 여부 | 설명 |
|------|------|------|------|
|grant\_type|string|Y|인가방법|
|client\_id|string|Y|사전에 발급 받은 client\_id|
|redirect\_uri|string|Y|인가 코드를 전달받을 서비스 서버의 URI|
|response\_type|string|Y|code 로 고정|
|scope|string|N|획득하고자 하는 권한(e.g. user\_name)|
|state|string|N|CSRF 공격 방지 토큰. redirect\_uri 에 포함되어 redirect 됩니다|
|intentUnsupported|string|N|안드로이드 웹뷰에서 intent 파싱이 되지 않는 버전 구분|
|policy|string|N|OAuth 로그인 연동 동선 구분 =`LOGIN` 으로 갑 고정 필요 |
|app|string|N|브라우저에 세션이 남아 있어도, 토스앱을 거치도록 강제하는 옵션.  requires 로 주면 강제됩니다.|
|flow|string|N|브라우저에 세션을 무시하고 동작하도록 하는 옵션. ignore\_session 으로 주면 세션이 무시됩니다.|

**성공 응답**\
성공시 요청 파라미터의 redirect\_uri 로 HTTP 302 redirect 하며 응답이 리턴 됩니다.
| 이름 | 타입 | 필수 | 설명 |
|-----|-----|-----|-----|
|code|string|Y|AccessToken 획득을 위한 인가 코드|
|state|string|N|요청 파라미터로 넣어주신 state 값|

**실패 응답**\
실패시 요청 파라미터의 redirect\_uri 로 HTTP 302 redirect 하며 응답이 리턴 됩니다.
| 이름 | 타입 | 필수 | 설명 |
|-----|-----|-----|-----|
|error|string|Y|에러 코드|
|error\_description|string|N|에러 메시지|
|state|string|N|요청 파라미터로 넣어주신 state 값|

```
// 포맷
https://oauth2.cert.toss.im/authorize?grant_type=$grant_type&client_id=$client_id&response_type=code&redirect_uri=$redirect_uri


// 예시
https://oauth2.cert.toss.im/authorize?grant_type=authorization_code&client_id=wnjo5yivr4ftuwlea93n4zazzzszx22o&response_type=code&redirect_uri=https://toss.im
```

## 2. AccessToken 받기

사용자 정보 조회 API 를 사용하기 위한 접근 토큰을 발급합니다.

* Content-type : application/json
* Method : `POST`
* URL : `/token`

::: tip 🚨 잠시만요

AccessToken 유효시간은 1시간이에요.

:::

**요청**
| 이름 | 타입 | 필수값 여부 | 설명 |
|------|------|------|------|
|client\_id|string|Y|사전에 발급 받은 client\_id|
|grant\_type|string|Y|authorization\_code 로 고정|
|code|string|Y|인가코드받기에서 획득한 code|
|client\_secret|string|Y|사전에 발급 받은 client\_secret|
|redirect\_uri|string|Y|인가코드받기에서 넘겨준 uri|

**요청 예시**

```
// 포맷
curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=$code' \
--data-urlencode 'client_id=$client_id' \
--data-urlencode 'client_secret=$client_secret' \
--data-urlencode 'redirect_uri=$redirect_uri'

// 예시
curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=fKjvI8ILZcj3Q8gX-8lFM2weU-_0Z0tLsNK_OiPG6iCWh0wpQW5QPAL_KLGGj8br3gGeu3kyv37tf2iZPDhNGKzza72_4FoAf8vdRHk4oK8-U5Cyb-hos412457jG8Rk' \
--data-urlencode 'client_id=3ezt6e1th86oday9phzz84u4ovng6ss' \
--data-urlencode 'client_secret={Client_secret}' \
--data-urlencode 'redirect_uri={redirect_uri}'
```

**성공 응답**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| token\_type | string | Y | bearer 로 고정 |
| access\_token | string | Y | AccessToken |
| refresh\_token | string | Y | RefreshToken |
| expires\_in | number | Y | 만료시간(초) |
| scope | string | Y | 인가된 scope(구분) |

```json
// 포맷
{
    "access_token": $access_token,
    "scope": $scope,
    "token_type": "Bearer",
    "expires_in": $expires_in
}

// 예시
{
    "access_token":"eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJtMHVmMmhaUmpJTnNEQTdLNHVuVHhMb3IwcWNSa2JNPSIsImF1ZCI6IjNlenQ2ZTF0aDg2b2RheTlwOWN1eTg0dTRvdm5nNnNzIiwibmJmIjoxNzE4MjU0ODM2LCJzY29wZSI6WyJ1c2VyX2NpIiwidXNlcl9iaXJ0aGRheSIsInVzZXJfbmF0aW9uYWxpdHkiLCJ1c2VyX25hbWUiLCJ1c2VyX3Bob25lIiwidXNlcl9nZW5kZXIiXSwiaXNzIjoiaHR0cHM6Ly9jZXJ0LnRvc3MuaW0iLCJleHAiOjE3MTgyNTg0MzYsImlhdCI6MTcxODI1NDgzNiwianRpIjoiMTJkYjYwZjYtMjEzYS00NWQ3LTllOTItODBjMzBdseY2JkMGQ3In0.W1cjoeMN8pd3Jqgh6h8YzSVQ1PUNldulJJgy6bgH1AoDbv5xFTlBLzz9Slb_u52zUpyZbhglwblQmNJs7GT6-us7XtfxSGxTUY3ORqIhF_PPGQ6soi_Qgsi-hmX165CCAilf8cltSTTuTt8xOiEbLuSTY-cecxo7SkPUonQ_0v4_Ik0kwOiOBuYZyuch3KmlYQZTqsJmxlwJAPB8M9tZTtDpLOv9MEPU35YS7CZyN0l7lwn1EKrDHJdzA5CnstqEdz2I0eREmMgZoG9mSEybgD4NtPmVJos6AJerUGgSmzP_TwwlybVATuGpnAUmH1idaZJ-MHZJhUhR82z4zTn3bw",
    "refresh_token":"xNEYPASwWw0n1AxZUHU9KeGj8BitDyYo4wi8rpfkUcJwByVxpAdUzwtIaWGVL6vHdrXLCxIlHAQRPF9hHnFleTsHkqUXzc-_78sD_r1Uh5Ff9UCYfArx8LTn1Vk99dDb",
    "scope":"user_ci user_birthday user_nationality user_name user_phone user_gender",
    "token_type":"Bearer",
    "expires_in":3599
}
```

**실패 응답**\
인가 코드가 만료되었거나 동일한 인가 코드로 AccessToken 을 중복으로 요청할 경우

```json
{
    "error":"invalid_grant"
}
```

```json
{
    "resultType":"FAIL",
    "error":{
        "errorCode":"INTERNAL_ERROR",
        "reason":"요청을 처리하는 도중에 문제가 발생했습니다."
    }
}
```

## 3. AccessToken 재발급 받기

사용자 정보 조회 API 를 사용하기 위한 접근 토큰을 재발급합니다.

* Content-type : application/json
* Method : `POST`
* URL : `/token`

::: tip 🚨 잠시만요

refreshToken 유효시간은 1일이에요.

:::

**요청**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| client\_id | string | Y | 사전에 발급 받은 client\_id |
| grant\_type | string | Y | refresh\_token 로 고정 |
| refresh\_token | string | Y | 2 에서 획득한 RefreshToken |
| client\_secret | string | Y | 사전에 발급 받은 client\_secret |

```
요청 예시 입력
// 포맷
curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=$refresh_token' \
--data-urlencode 'client_id=$client_id' \
--data-urlencode 'client_secret=$client_secret' \
--data-urlencode 'redirect_uri=$redirect_uri'

// 예시
curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=xNEYPASwWw0n1AxZUHU9KeGj8BitDyYo4wi8rpfkUcJwByVxpAdUzwtIaWGVL6vHdrXLCxIlHAQRPF9hHnFleTsHkqUXzc-_78sD_r1Uh5Ff9UCYfArx8LTn1Vk99dDb' \
--data-urlencode 'client_id=3ezt6e1th86oday9p9cuy84u4bbng6ss' \
--data-urlencode 'client_secret={Client_secret}' \
--data-urlencode 'redirect_uri={redirect_uri}'
```

**성공 응답**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| token\_type | string | Y | bearer 로 고정 |
| access\_token | string | Y | AccessToken |
| refresh\_token | string | Y | RefreshToken |
| expires\_in | number | Y | 만료시간(초) |
| scope | string | Y | 인가된 scope(구분) |

**실패 응답**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| error | string | Y | 에러 코드 |
| error\_description | string | Y | 에러 메시지 |

## 4. 사용자 정보 받기

사용자 정보를 조회합니다.\
DI는 null 로 내려가며 횟수 제한없이 호출이 가능해요.\
개인정보 보호를 위해 암호화된 형태로 제공합니다.

* Content-type : application/json
* Method : `GET`
* URL : `/api-partner/v1/apps-in-toss/user/oauth2/login-me`

::: tip 🚨 잠시만요

앱인토스용 로그인 시의 userKey와는 다른 userKey가 내려가요.\
동일한 사업자의 경우 동일한 userKey가 내려가도록 7월에 수정될 예정이니 참고해주세요.

:::

**요청 헤더**
| 이름          | 타입    | 필수값 여부 | 설명                                                                 |
|---------------|---------|--------------|----------------------------------------------------------------------|
| Authorization | string  | Y            | AccessToken으로 인증 요청  `Authorization: Bearer ${AccessToken}` |

```
// 포맷
curl --request GET 'https://oauth2.cert.toss.im/oauth2/api/login/user/me/without-di' \
--header 'Authorization: Bearer $access_token'


// 예시
curl --request GET 'https://oauth2.cert.toss.im/oauth2/api/login/user/me/without-di' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJtMHVmMmhaUmpJTnNEQTdLNHVuVHhMb3IwcWNSa2JNPSIsImF1ZCI6IjNlenQ2ZTF0aDg2b2RheTlwOWN1eTg0dTRvdm5nNnNzIiwibmJmIjoxNzE4MjU0ODM2LCJzY29wZSI6WyJ1c2VyX2NpIiwidXNlcl9iaXJ0aGRheSIsInVzZXJfbmF0aW9uYWxpdHkiLCJ1c2VyX25hbWUiLCJ1c2VyX3Bob25lIiwidXNlcl9nZW5kZXIiXSwiaXNzIjoiaHR0cHM6Ly9jZXJ0LnRvc3MzzW0iLCJleHAiOjE3MTgyNTg0MzYsImlhdCI6MTcxODI1NDgzNiwianRpIjoiMTJkYjYwZjYtMjEzYS00NWQ3LTllOTItODBjzeBmY2JkMGQ3In0.W1cjoeMN8pd3Jqgh6h8YzSVQ1PUNldulJJgy6bgH1AoDbv5xFTlBLwk9Slb_u52zUpyZbhglwblQmNJs7GT6-us7XtfxSGxTUY3ORqIhF_PPGQ6soi_Qgsi-hmX165CCAilf8cltSTTuTt8xOiEbLuSTY-cecxo7SkPUonQ_0v4_Ik0kwOiOBuYZyuch3KmlYQZTqsJmxlwJAPB8M9tZTtDpLOv9MEPU35YS7CZyN0l7lwn1EKrDHJdzA5CnstqEdz2I0eREmMgZoG9mSEybgD4NtPmVJos6AJerUGgSmzP_TwwlybVATuGpnAUmH1idaZJ-MHZJhUhR82z4zTn3bw'

```

**성공 응답**
| 이름 | 타입 | 필수 | 암호화 여부 | 설명 |
| --- | --- | --- | --- | --- |
| userKey | number | Y |  | 유저식별자 |
| scope | string | Y |  | 인가된 scope(구분) |
| agreedTerms | list | Y |  | 동의한 약관 목록 |
| policy | string | Y |  | OAuth 로그인 연동 동선 구분 =`LOGIN`으로 값 고정 필요 |
| certTxId | string | N |  | 회원가입인 경우, 본인확인 식별자. 앱인토스 파트너사의 경우 해당사항 없음 |
| ci | string |  | Y | CI |
| name | string |  | Y | 이름 |
| phone | string |  | Y | 휴대전화번호 |
| gender | string |  | Y | 성별(MALE/FEMALE) |
| nationality | string |  | Y | 내/외국인여부(LOCAL/FOREIGNER) |
| birthday | string |  | Y | 생년월일(yyyyMMdd) |
| email | string |  | Y | 이메일 (점유인증 하지 않은 이메일 정보) |

```json
// 예시
{
    "resultType":"SUCCESS",
    "success":{
        "userKey":443731104,
        "scope":"user_ci,user_birthday,user_nationality,user_name,user_phone,user_gender",
        "agreedTerms":[],
        "policy":"AUTO_SELECT",
        "certTxId":"ad052b57-dc8f-4cdb-a6e2-7b494e28b5ec",
        "name":"ENCRYPTED_VALUE",
        "phone":"ENCRYPTED_VALUE",
        "birthday":"ENCRYPTED_VALUE",
        "ci":"ENCRYPTED_VALUE",
        "di":null,
        "gender":"ENCRYPTED_VALUE",
        "nationality":"ENCRYPTED_VALUE",
        "email":null
    }
}
```

**실패 응답**\
유효하지 않은 토큰을 사용할 경우, 현재 사용 중인 access\_token의 유효시간을 확인하고 재발급을 진행해주세요.

```json
// 예시
{
    "error":"invalid_grant"
}
```

**서버 에러 응답 예시**\
| errorCode      | 설명                       |
|----------------|---------------------------|
| INTERNAL\_ERROR | 내부 서버 에러              |
| USER\_KEY\_NOT\_FOUND | 로그인 서비스에 접속한 유저 키 값을 찾을 수 없음 |
| USER\_NOT\_FOUND | 토스 유저 정보를 찾을 수 없음 |
| BAD\_REQUEST\_RETRIEVE\_CERT\_RESULT\_EXCEEDED\_LIMIT | 조회 가능 횟수 초과  동일한 토큰으로 `/api/login/user/me/without-di` API 조회하면 정상적으로 조회되나, di 필드는 null 값으로 내려감 |

```json
// 예시
{
    "resultType":"FAIL",
    "error":{
        "errorCode":"INTERNAL_ERROR",
        "reason":"요청을 처리하는 도중에 문제가 발생했습니다."
    }
}
```

## 5. 사용자 정보 복호화하기

이메일로 받은 `복호화 키`와 `AAD(Additional Authenticated DATA)` 로 진행해주세요.

**암호화 알고리즘**

* AES 대칭키 암호화
* 키 길이 : 256비트
* 모드 : GCM
* AAD : 복호화 키와 함께 이메일로 전달드립니다.

**데이터 교환방식**

* 암호화된 데이터의 앞 부분에 IV/NONCE 값을 첨부하여 드립니다.
* 복호화할 때는 암호화된 데이터의 앞 부분에서 IV/NONCE 값을 추출하여 사용하시길 바랍니다.

**복호화 샘플 코드**

::: details Kotlin 예제

```kotlin
import java.util.Base64
import javax.crypto.Cipher
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.SecretKeySpec

class Test {
    fun decrypt(
        encryptedText: String,
        base64EncodedAesKey: String,
        add: String,
    ): String {
        val IV_LENGTH = 12
        val decoded = Base64.getDecoder().decode(encryptedText)
        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
        val keyByteArray = Base64.getDecoder().decode(base64EncodedAesKey)
        val key = SecretKeySpec(keyByteArray, "AES")
        val iv = decoded.copyOfRange(0, IV_LENGTH)
        val nonceSpec = GCMParameterSpec(16 * Byte.SIZE_BITS, iv)

        cipher.init(Cipher.DECRYPT_MODE, key, nonceSpec)
        cipher.updateAAD(add.toByteArray())

        return String(cipher.doFinal(decoded, IV_LENGTH, decoded.size - IV_LENGTH))
    }
}
```

:::

::: details PHP 예제

```php
<?php

class Test {
    public function decrypt($encryptedText, $base64EncodedAesKey, $add) {
        $IV_LENGTH = 12;
        $decoded = base64_decode($encryptedText);
        $keyByteArray = base64_decode($base64EncodedAesKey);
        $iv = substr($decoded, 0, $IV_LENGTH);
        $ciphertext = substr($decoded, $IV_LENGTH);

        $tag = substr($ciphertext, -16);
        $ciphertext = substr($ciphertext, 0, -16);

        $decrypted = openssl_decrypt(
            $ciphertext,
            'aes-256-gcm',
            $keyByteArray,
            OPENSSL_RAW_DATA,
            $iv,
            $tag,
            $add
        );

        return $decrypted;
    }
}


// 사용 예제
$test = new Test();
$encryptedText = "Encrypted Text"; // Encrypted Text 입력
$base64EncodedAesKey = "Key"; // Key 입력
$add = "TOSS";

$result = $test->decrypt($encryptedText, $base64EncodedAesKey, $add);
echo $result;

?>
```

:::

::: details JAVA 예제

```java
public class Test {
    public String decrypt(
        String encryptedText,
        String base64EncodedAesKey,
        String add
    ) throws Exception {
        final int IV_LENGTH = 12;
        byte[] decoded = Base64.getDecoder().decode(encryptedText);
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        byte[] keyByteArray = Base64.getDecoder().decode(base64EncodedAesKey);
        SecretKeySpec key = new SecretKeySpec(keyByteArray, "AES");
        byte[] iv = new byte[IV_LENGTH];
        System.arraycopy(decoded, 0, iv, 0, IV_LENGTH);
        GCMParameterSpec nonceSpec = new GCMParameterSpec(16 * Byte.SIZE, iv);

        cipher.init(Cipher.DECRYPT_MODE, key, nonceSpec);
        cipher.updateAAD(add.getBytes());

        byte[] decrypted = cipher.doFinal(decoded, IV_LENGTH, decoded.length - IV_LENGTH);
        return new String(decrypted);
    }
}
```

:::

## 6. 로그인 끊기

발급받은 AccessToken을 더 이상 사용하지 않거나 사용자의 요구에 의해 만료시킬 경우 토큰을 삭제(만료)해주세요.

* Content-type : application/json
* Method : `POST`
* URL : `/api/login/access/remove`

**AccessToken 으로 로그인 연결 끊기**

```
// 포맷
curl --request POST 'https://oauth2.cert.toss.im/oauth2/api/login/access/remove' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $access_token'

// 예시
curl --request POST 'https://oauth2.cert.toss.im/oauth2/api/login/access/remove' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IizzYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJtMHVmMmhaUmpJTnNEQTdLNHVuVHhMb3IwcWNSa2JNPSIsImF1ZCI6IjNlenQ2ZTF0aDg2b2RheTlwOWN1eTg0dTRvdm5nNnNzIiwibmJmIjoxNzE4MjU0ODM2LCJzY29wZSI6WyJ1c2VyX2NpIiwidXNlcl9iaXJ0aGRheSIsInVzZXJfbmF0aW9uYWxpdHkiLCJ1c2VyX25hbWUiLCJ1c2VyX3Bob25lIiwidXNlcl9nZW5kZXIiXSwiaXNzIjoiaHR0cHM6Ly9jZXJ0LnRvc3MuaW0iLCJleHAiOjE3MTgyNTg0MzYsImlhdCI6MTcxODI1NDgzNiwianRpIjoiMTJkYjYwZjYtMjEzYS00NWQ3LTllOTItODBjMzBmY2JkMGQ3In0.W1cjoeMN8pd3Jqgh6h8YzSVQ1PUNldulJJgy6bgH1AoDbv5xFTlBLwk9Slb_u52zUpyZbhglwblQmNJs7GT6-us7XtfxSGxTUY3ORqIhF_PPGQ6soi_Qgsi-hmX165CCAilf8cltSTTuTt8xOiEbLuSTY-cecxo7SkPUonQ_0v4_Ik0kwOiOBuYZyuch3KmlYQZTqsJmxlwJAPB8M9tZTtDpLOv9MEPU35YS7CZyN0l7lwn1EKrDHJdzA5CnstqEdz2I0eREmMgZoG9mSEybgD4NtPmVJos6AJerUGgSmzP_TwwlybVATuGpnAUmH1idaZJ-MHZJhUhR82z4zTn3bw'

```

**userKey 를 이용하여 고객사에서 새로운 access\_token을 발급 후 로그인 연결 끊기**\
Client Credentials Grant (클라이언트 자격증명 승인 방식) 방식으로 획득한 access\_token을 사용 : 권한이 있는 Client에서 로그인 연결 해제를 요청하고 있는지를 검증하기 위해 client\_credentials 방식으로 고객사에서 access\_token을 발급해서 특정 사용자의 로그인 연결을 끊는 방식

::: tip 주의하세요

연결 끊기 요청의 키로 userKey를 사용하기 때문에 유저 연결 관리를 위해 사용자의 userKey 개별적으로 보관 필요\
scope에 연결 끊기 요청을 사용할 수 있는 Client임이 설정되어 있어야 함(참고하여 사전 요청 필요)

:::

1. access\_token 발급 요청 : 요청 시 scope에 `login:access_remove` 꼭 포함되어 있어야 함

* Content-type: application/x-www-form-urlencoded;charset=utf-8

요청
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| grant\_type | string | Y | client\_credentials 로 고정 |
| client\_id | string | Y | 사전에 발급 받은 client\_id |
| client\_secret | string | Y | 사전에 발급 받은 client\_secret |
| scope | string | Y | login:access\_remove |

```
// 포맷
curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=$client_id' \
--data-urlencode 'client_secret=$client_secret' \
--data-urlencode 'scope=$scope'

// 예시
curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=56gnin234285rm8lq7tm6xl1jtlsevhm' \
--data-urlencode 'client_secret=7SzN7nMGlciRIt2MXndx534Dnskdi3v0po2h4Vunaf1ChP9L' \
--data-urlencode 'scope=login:access_remove'
```

```json
{
    "access_token": "eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNS3kdix.esk3XWIiOiI1NmduaW43ZjcyODVybThscTd0bTZ4bDFqdGVsNnZobSIsImF1ZCI6IjU2Z25pbjdmNzI4NXJtOGxxN3RtNnhsMWp0ZWw2dmhtIiwibmJmIjoxNzE5MTkzNDQ4LCJSoekch332syJsb2dpbjphY2Nlc3NfcmVtb3ZlIl0sImlzcyI6Imh0dHBzOi8vY2VydC1hbHBoYS50b3NzLmltIiwiZXhwIjoxNzE5MTk3MDQ4LCJpYXQiOjE3MTkxOTM0NDgsImp0aSI6IjZmYmMwMDhiLTc2MDUtNDc3OC1hYTZiLTBkMDZjYWMwZTU4MSJ9.GY7EzoEuarv0It5tmYu67fvJccsGqqd_mQ0CSJ36X5SG_DziF--8qNmenBlUUkd9JTfyp9DoVRH33ferpzcuUz6VL-zg1bHuylgORaz8WJiXlamdEjf0svx88sYZ__w5LBaVpu7BY8hkAv248mR0deyyvn5mF0COU2RoG-NFwee6LWQ7fnN3xhlFFKN7GJRrMf9uNF2z7sgNzLTRztAteeL7-XsV5-jXvf3MrKScuBiwA1MTj7_lZPPzHFYVWtP4rAywizaZTVk4fSdRSO__Uc__jETd6d5wYYf1gw-sNsaeRsCzrRGOiJTMq93DaQgQuCOothn3xNvNAYIMdcuaAw",
    "scope": "login:access_remove",
    "token_type": "Bearer",
    "expires_in": 3599
}
```

로그인 연결 끊기 scope를 사용할 수 있는 client가 아닌 경우

```json
{"error":"invalid_scope"}
```

2. 로그인 연결 끊기

* Content-type: Content-type: application/json;charset=utf-8

```
// 포맷
curl --request POST 'https://oauth2.cert.toss.im/oauth2/api/login/access/remove' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $access_token' \
--data '{"userKey": $user_key}'

// 예시
curl --request POST 'https://oauth2.cert.toss.im/oauth2/api/login/access/remove' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IizzYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJtMHVmMmhaUmpJTnNEQTdLNHVuVHhMb3IwcWNSa2JNPSIsImF1ZCI6IjNlenQ2ZTF0aDg2b2RheTlwOWN1eTg0dTRvdm5nNnNzIiwibmJmIjoxNzE4MjU0ODM2LCJzY29wZSI6WyJ1c2VyX2NpIiwidXNlcl9iaXJ0aGRheSIsInVzZXJfbmF0aW9uYWxpdHkiLCJ1c2VyX25hbWUiLCJ1c2VyX3Bob25lIiwidXNlcl9nZW5kZXIiXSwiaXNzIjoiaHR0cHM6Ly9jZXJ0LnRvc3MuaW0iLCJleHAiOjE3MTgyNTg0MzYsImlhdCI6MTcxODI1NDgzNiwianRpIjoiMTJkYjXwZjYtMjEzYS00NWQ3LTllOTItODBjMzBmY2JkMGQ3In0.W1cjoeMN8pd3Jqgh6h8YzSVQ1PUNldulJJhysi3H1AoDbv5xFTlBLwk9Slb_u52zUpyZbhglwblQmNJs7GT6-us7XtfxSGxTUY3ORqIhF_PPGQ6soisiel_-hmX165CCAilf8cltSTTuTt8xOiEbLuSTY-cecxo7SkPUonQ_0v4_Ik0kwOiOBuYZyuch3KmlYTiskex4mx6wJAPB8M9tZTtDpLOv9MEPU35YS7CZyN0l7lwn1EKrDHJdzA5CnstqEdz2I0eREmMgZoG9mSEybgD3NtPmVJos6AJerUGgSmzP_TwwlybVATuGpnAUmH1idaZJ-MHZJhUhR82z4zTn3bw' \
--data '{"userKey": 443731103}'
```

```json
{
    "resultType": "SUCCESS",
    "success": {
        "userKey": 443731103 
    }
}
```

요청시 사용한 userKey로 연결된 유저가 없는 경우

```json
{
    "resultType": "FAIL",
    "error": {
        "errorType": 0,
        "errorCode": "USER_KEY_NOT_FOUND",
        "reason": "UserKeyNotFound",
        "data": {},
        "title": null
    }
}
```

요청시 사용한 access\_token의 scope에 로그인 연결 끊기가 포함되지 않은 경우

```json
{
    "resultType": "FAIL",
    "error": {
        "errorType": 0,
        "errorCode": "BAD_REQUEST_NOT_ALLOWED_SCOPE",
        "reason": "잘못된 요청입니다.",
        "data": {},
        "title": null
    }
}
```

## 7. 콜백을 통해 로그인 끊기

사용자가 토스앱 내에서 서비스와의 연결을 해제한 경우 가맹점 서버로 알려드려요.\
서비스에서 연결이 끊긴 사용자에 대한 처리가 필요한 경우 활용할 수 있어요.
콜백을 받을 URL과 basic Auth 헤더는 콘솔에서 입력할 수 있어요.\
서비스에서 직접 로그인 연결 끊기 요청을 호출한 경우 콜백이 호출되지 않아요.

**GET 방식**

* 요청 requestParam에 `userKey`와 `referrer`을 포함합니다.

```
// 포맷
curl --request GET '$callback_url?userKey=$userKey&referrer=$referrer'

// 예시
curl --request GET '$callback_url?userKey=443731103&referrer=UNLINK'
```

**POST 방식**

* 요청 body에 `userKey`와 `referrer`을 포함합니다.

```
// 포맷
curl --request POST '$callback_url' \
--header 'Content-Type: application/json' \
--data '{"userKey": $user_key, "referrer": $referrer}'

// 예시
curl --request POST '$callback_url' \
--header 'Content-Type: application/json' \
--data '{"userKey": 443731103, "referrer": "UNLINK"}'
```

referrer 은 연결 끊기 요청 경로에요.\
| referrer | 설명 |
|----------|------|
| `UNLINK` | 사용자가 앱에서 연결 끊기 |
| `WITHDRAWAL_TERMS` | 로그인 서비스 약관 철회 |
| `WITHDRAWAL_TOSS` | 토스 회원 탈퇴 |

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/optimization/runtime/particle.md'
---
# 파티클 최적화

파티클 시스템 예산 관리는 앱인토스 미니앱의 제한된 WebGL 환경에서 파티클 효과를 효율적으로 사용하는 핵심 도구예요.\
모바일 기기의 성능 한계와 토스 앱의 리소스 제약을 고려해, 파티클의 품질과 성능 사이에서 최적의 균형을 맞춰요.

***

## 앱인토스 플랫폼 특화 파티클 관리

### 1. 동적 파티클 예산 시스템

```c#
// Unity C# - 앱인토스 파티클 예산 매니저
using UnityEngine;
using System.Collections.Generic;
using System.Linq;

public class AITParticleBudgetManager : MonoBehaviour
{
    private static AITParticleBudgetManager instance;
    public static AITParticleBudgetManager Instance => instance;
    
    [System.Serializable]
    public class ParticleBudget
    {
        [Header("전역 예산")]
        public int maxTotalParticles = 1000;        // 전체 최대 파티클 수
        public int maxActiveEmitters = 20;          // 동시 활성 이미터 수
        public float maxMemoryUsage = 50f;          // 최대 메모리 사용량 (MB)
        
        [Header("품질별 예산")]
        public int highQualityParticles = 500;      // 고품질 파티클 수
        public int mediumQualityParticles = 300;    // 중품질 파티클 수
        public int lowQualityParticles = 200;       // 저품질 파티클 수
        
        [Header("카테고리별 예산")]
        public int uiEffectParticles = 200;         // UI 이펙트 파티클
        public int gameplayParticles = 600;         // 게임플레이 파티클
        public int backgroundParticles = 200;       // 배경 파티클
        
        [Header("성능 임계값")]
        public float cpuUsageThreshold = 70f;       // CPU 사용률 임계값 (%)
        public float fpsThreshold = 30f;            // FPS 임계값
        public float memoryThreshold = 80f;         // 메모리 사용률 임계값 (%)
    }
    
    [System.Serializable]
    public class ParticleSystemInfo
    {
        public ParticleSystem particleSystem;
        public string category;
        public int priority;                        // 우선순위 (높을수록 중요)
        public int currentParticleCount;
        public float memoryUsage;
        public bool isActive;
        public float lastActiveTime;
        public QualityLevel qualityLevel;
        
        public enum QualityLevel
        {
            Low = 0,
            Medium = 1, 
            High = 2
        }
    }
    
    [Header("파티클 예산 설정")]
    public ParticleBudget budget;
    public bool enableDynamicBudgeting = true;     // 동적 예산 조정
    public bool enableAutomaticCleanup = true;     // 자동 정리
    public float budgetUpdateInterval = 1f;        // 예산 업데이트 간격
    
    private List<ParticleSystemInfo> managedParticles;
    private Dictionary<string, int> categoryUsage;
    private Dictionary<ParticleSystemInfo.QualityLevel, int> qualityUsage;
    
    // 성능 메트릭
    private float currentCPUUsage;
    private float currentFPS;
    private float currentMemoryUsage;
    private int totalActiveParticles;
    
    // 이벤트
    public static event System.Action<int> OnBudgetExceeded;
    public static event System.Action<ParticleSystemInfo> OnParticleSystemCulled;
    public static event System.Action<ParticleBudget> OnBudgetUpdated;
    
    private void Awake()
    {
        if (instance == null)
        {
            instance = this;
            DontDestroyOnLoad(gameObject);
            InitializeParticleBudget();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    private void InitializeParticleBudget()
    {
        managedParticles = new List<ParticleSystemInfo>();
        categoryUsage = new Dictionary<string, int>();
        qualityUsage = new Dictionary<ParticleSystemInfo.QualityLevel, int>();
        
        // 초기 예산 설정
        ApplyInitialBudget();
        
        if (enableDynamicBudgeting)
        {
            InvokeRepeating(nameof(UpdateBudget), budgetUpdateInterval, budgetUpdateInterval);
        }
        
        if (enableAutomaticCleanup)
        {
            InvokeRepeating(nameof(CleanupInactiveParticles), 5f, 5f);
        }
    }
    
    private void ApplyInitialBudget()
    {
        // 디바이스 성능에 따른 초기 예산 조정
        var deviceClass = GetDevicePerformanceClass();
        
        switch (deviceClass)
        {
            case DevicePerformanceClass.Low:
                budget.maxTotalParticles = Mathf.RoundToInt(budget.maxTotalParticles * 0.5f);
                budget.maxActiveEmitters = Mathf.RoundToInt(budget.maxActiveEmitters * 0.6f);
                break;
                
            case DevicePerformanceClass.Medium:
                budget.maxTotalParticles = Mathf.RoundToInt(budget.maxTotalParticles * 0.8f);
                budget.maxActiveEmitters = Mathf.RoundToInt(budget.maxActiveEmitters * 0.8f);
                break;
                
            case DevicePerformanceClass.High:
                // 기본 예산 사용
                break;
        }
        
        Debug.Log($"[AIT Particle] 초기 예산 설정 - 총 파티클: {budget.maxTotalParticles}, 이미터: {budget.maxActiveEmitters}");
    }
    
    private DevicePerformanceClass GetDevicePerformanceClass()
    {
        // 시스템 성능 기반 클래스 분류
        int memorySize = SystemInfo.systemMemorySize;
        int processorCount = SystemInfo.processorCount;
        
        if (memorySize < 2048 || processorCount < 4)
            return DevicePerformanceClass.Low;
        else if (memorySize < 4096 || processorCount < 6)
            return DevicePerformanceClass.Medium;
        else
            return DevicePerformanceClass.High;
    }
    
    public enum DevicePerformanceClass
    {
        Low,
        Medium,
        High
    }
    
    public void RegisterParticleSystem(ParticleSystem ps, string category, int priority, 
        ParticleSystemInfo.QualityLevel quality = ParticleSystemInfo.QualityLevel.Medium)
    {
        if (ps == null) return;
        
        var info = new ParticleSystemInfo
        {
            particleSystem = ps,
            category = category,
            priority = priority,
            qualityLevel = quality,
            isActive = false,
            lastActiveTime = Time.time
        };
        
        managedParticles.Add(info);
        
        Debug.Log($"[AIT Particle] 파티클 시스템 등록: {ps.name} ({category}, 우선순위: {priority})");
    }
    
    public bool RequestParticleActivation(ParticleSystem ps, int requestedParticles)
    {
        var info = GetParticleSystemInfo(ps);
        if (info == null)
        {
            Debug.LogWarning($"[AIT Particle] 등록되지 않은 파티클 시스템: {ps.name}");
            return false;
        }
        
        // 예산 확인
        if (!CanAllocateParticles(requestedParticles, info))
        {
            Debug.LogWarning($"[AIT Particle] 파티클 예산 초과: {ps.name} (요청: {requestedParticles})");
            
            // 낮은 우선순위 파티클 정리 시도
            if (TryFreeUpBudget(requestedParticles, info.priority))
            {
                Debug.Log($"[AIT Particle] 예산 확보 성공: {ps.name}");
            }
            else
            {
                OnBudgetExceeded?.Invoke(requestedParticles);
                return false;
            }
        }
        
        // 파티클 활성화
        ActivateParticleSystem(info, requestedParticles);
        return true;
    }
    
    private bool CanAllocateParticles(int requestedParticles, ParticleSystemInfo info)
    {
        // 전역 예산 확인
        if (totalActiveParticles + requestedParticles > budget.maxTotalParticles)
            return false;
        
        // 카테고리별 예산 확인
        int categoryBudget = GetCategoryBudget(info.category);
        int currentCategoryUsage = categoryUsage.ContainsKey(info.category) ? categoryUsage[info.category] : 0;
        
        if (currentCategoryUsage + requestedParticles > categoryBudget)
            return false;
        
        // 품질별 예산 확인
        int qualityBudget = GetQualityBudget(info.qualityLevel);
        int currentQualityUsage = qualityUsage.ContainsKey(info.qualityLevel) ? qualityUsage[info.qualityLevel] : 0;
        
        if (currentQualityUsage + requestedParticles > qualityBudget)
            return false;
        
        return true;
    }
    
    private int GetCategoryBudget(string category)
    {
        switch (category.ToLower())
        {
            case "ui":
            case "uieffect":
                return budget.uiEffectParticles;
            case "gameplay":
            case "game":
                return budget.gameplayParticles;
            case "background":
            case "ambient":
                return budget.backgroundParticles;
            default:
                return budget.maxTotalParticles / 4; // 기본 할당
        }
    }
    
    private int GetQualityBudget(ParticleSystemInfo.QualityLevel quality)
    {
        switch (quality)
        {
            case ParticleSystemInfo.QualityLevel.High:
                return budget.highQualityParticles;
            case ParticleSystemInfo.QualityLevel.Medium:
                return budget.mediumQualityParticles;
            case ParticleSystemInfo.QualityLevel.Low:
                return budget.lowQualityParticles;
            default:
                return budget.mediumQualityParticles;
        }
    }
    
    private bool TryFreeUpBudget(int requiredParticles, int requestPriority)
    {
        var sortedParticles = managedParticles
            .Where(p => p.isActive && p.priority < requestPriority)
            .OrderBy(p => p.priority)
            .ThenBy(p => p.lastActiveTime);
        
        int freedParticles = 0;
        
        foreach (var info in sortedParticles)
        {
            if (freedParticles >= requiredParticles)
                break;
            
            freedParticles += info.currentParticleCount;
            DeactivateParticleSystem(info);
            
            Debug.Log($"[AIT Particle] 낮은 우선순위 파티클 정리: {info.particleSystem.name}");
        }
        
        return freedParticles >= requiredParticles;
    }
    
    private void ActivateParticleSystem(ParticleSystemInfo info, int particleCount)
    {
        info.isActive = true;
        info.currentParticleCount = particleCount;
        info.lastActiveTime = Time.time;
        
        // 사용량 업데이트
        totalActiveParticles += particleCount;
        
        if (categoryUsage.ContainsKey(info.category))
            categoryUsage[info.category] += particleCount;
        else
            categoryUsage[info.category] = particleCount;
        
        if (qualityUsage.ContainsKey(info.qualityLevel))
            qualityUsage[info.qualityLevel] += particleCount;
        else
            qualityUsage[info.qualityLevel] = particleCount;
        
        // 파티클 시스템 설정 적용
        ApplyQualitySettings(info);
    }
    
    private void DeactivateParticleSystem(ParticleSystemInfo info)
    {
        if (!info.isActive) return;
        
        // 사용량 업데이트
        totalActiveParticles -= info.currentParticleCount;
        categoryUsage[info.category] -= info.currentParticleCount;
        qualityUsage[info.qualityLevel] -= info.currentParticleCount;
        
        info.isActive = false;
        info.currentParticleCount = 0;
        
        // 파티클 시스템 정지
        info.particleSystem.Stop(true, ParticleSystemStopBehavior.StopEmittingAndClear);
        
        OnParticleSystemCulled?.Invoke(info);
    }
    
    private void ApplyQualitySettings(ParticleSystemInfo info)
    {
        var ps = info.particleSystem;
        var main = ps.main;
        
        switch (info.qualityLevel)
        {
            case ParticleSystemInfo.QualityLevel.Low:
                main.maxParticles = Mathf.RoundToInt(main.maxParticles * 0.5f);
                SetParticleSystemLOD(ps, 0); // 최저 품질
                break;
                
            case ParticleSystemInfo.QualityLevel.Medium:
                main.maxParticles = Mathf.RoundToInt(main.maxParticles * 0.75f);
                SetParticleSystemLOD(ps, 1); // 중간 품질
                break;
                
            case ParticleSystemInfo.QualityLevel.High:
                // 원래 설정 유지
                SetParticleSystemLOD(ps, 2); // 최고 품질
                break;
        }
    }
    
    private void SetParticleSystemLOD(ParticleSystem ps, int lodLevel)
    {
        var renderer = ps.GetComponent<ParticleSystemRenderer>();
        if (renderer == null) return;
        
        switch (lodLevel)
        {
            case 0: // 낮음
                renderer.sortMode = ParticleSystemSortMode.None;
                DisableExpensiveModules(ps);
                break;
                
            case 1: // 중간
                renderer.sortMode = ParticleSystemSortMode.Distance;
                OptimizeModules(ps);
                break;
                
            case 2: // 높음
                // 모든 기능 활성화
                break;
        }
    }
    
    private void DisableExpensiveModules(ParticleSystem ps)
    {
        // 비용이 높은 모듈들 비활성화
        var collision = ps.collision;
        collision.enabled = false;
        
        var lights = ps.lights;
        lights.enabled = false;
        
        var trails = ps.trails;
        trails.enabled = false;
    }
    
    private void OptimizeModules(ParticleSystem ps)
    {
        // 모듈별 최적화 설정
        var emission = ps.emission;
        if (emission.enabled)
        {
            var rate = emission.rateOverTime;
            emission.rateOverTime = rate.constant * 0.8f;
        }
        
        var shape = ps.shape;
        if (shape.enabled)
        {
            shape.meshRenderer = null; // 메시 렌더러 제거로 성능 향상
        }
    }
    
    private void UpdateBudget()
    {
        // 성능 메트릭 업데이트
        UpdatePerformanceMetrics();
        
        // 동적 예산 조정
        if (enableDynamicBudgeting)
        {
            AdjustBudgetBasedOnPerformance();
        }
        
        // 사용량 통계 업데이트
        UpdateUsageStatistics();
    }
    
    private void UpdatePerformanceMetrics()
    {
        currentFPS = 1f / Time.deltaTime;
        
        // 메모리 사용량 (근사치)
        currentMemoryUsage = UnityEngine.Profiling.Profiler.GetTotalAllocatedMemory(UnityEngine.Profiling.Profiler.Area.Total) / (1024 * 1024);
        
        // CPU 사용률은 프레임 시간으로 추정
        currentCPUUsage = (Time.deltaTime / (1f/60f)) * 100f; // 60fps 기준
    }
    
    private void AdjustBudgetBasedOnPerformance()
    {
        bool budgetChanged = false;
        ParticleBudget newBudget = budget;
        
        // FPS 기반 조정
        if (currentFPS < budget.fpsThreshold)
        {
            newBudget.maxTotalParticles = Mathf.RoundToInt(newBudget.maxTotalParticles * 0.9f);
            budgetChanged = true;
            Debug.Log($"[AIT Particle] FPS 저하로 인한 예산 감소: {newBudget.maxTotalParticles}");
        }
        else if (currentFPS > budget.fpsThreshold * 1.5f && newBudget.maxTotalParticles < 1000)
        {
            newBudget.maxTotalParticles = Mathf.RoundToInt(newBudget.maxTotalParticles * 1.1f);
            budgetChanged = true;
            Debug.Log($"[AIT Particle] 성능 여유로 인한 예산 증가: {newBudget.maxTotalParticles}");
        }
        
        // 메모리 기반 조정
        if (currentMemoryUsage > budget.memoryThreshold)
        {
            newBudget.maxTotalParticles = Mathf.RoundToInt(newBudget.maxTotalParticles * 0.8f);
            budgetChanged = true;
            Debug.LogWarning($"[AIT Particle] 메모리 부족으로 인한 예산 감소: {newBudget.maxTotalParticles}");
        }
        
        if (budgetChanged)
        {
            budget = newBudget;
            OnBudgetUpdated?.Invoke(budget);
            
            // 현재 예산을 초과하는 파티클들 정리
            EnforceBudgetLimits();
        }
    }
    
    private void EnforceBudgetLimits()
    {
        if (totalActiveParticles <= budget.maxTotalParticles) return;
        
        int excessParticles = totalActiveParticles - budget.maxTotalParticles;
        
        // 낮은 우선순위부터 정리
        var particlesToCull = managedParticles
            .Where(p => p.isActive)
            .OrderBy(p => p.priority)
            .ThenBy(p => p.lastActiveTime);
        
        int culledParticles = 0;
        foreach (var info in particlesToCull)
        {
            if (culledParticles >= excessParticles) break;
            
            culledParticles += info.currentParticleCount;
            DeactivateParticleSystem(info);
        }
    }
    
    private void UpdateUsageStatistics()
    {
        // 실시간 파티클 카운트 업데이트
        totalActiveParticles = 0;
        categoryUsage.Clear();
        qualityUsage.Clear();
        
        foreach (var info in managedParticles)
        {
            if (!info.isActive) continue;
            
            int actualCount = info.particleSystem.particleCount;
            info.currentParticleCount = actualCount;
            
            totalActiveParticles += actualCount;
            
            if (categoryUsage.ContainsKey(info.category))
                categoryUsage[info.category] += actualCount;
            else
                categoryUsage[info.category] = actualCount;
            
            if (qualityUsage.ContainsKey(info.qualityLevel))
                qualityUsage[info.qualityLevel] += actualCount;
            else
                qualityUsage[info.qualityLevel] = actualCount;
        }
    }
    
    private void CleanupInactiveParticles()
    {
        var inactiveParticles = managedParticles
            .Where(p => !p.isActive && Time.time - p.lastActiveTime > 30f) // 30초 이상 비활성
            .ToList();
        
        foreach (var info in inactiveParticles)
        {
            if (info.particleSystem == null)
            {
                managedParticles.Remove(info);
                continue;
            }
            
            // 완전히 정리
            if (!info.particleSystem.isPlaying && info.particleSystem.particleCount == 0)
            {
                Debug.Log($"[AIT Particle] 비활성 파티클 시스템 정리: {info.particleSystem.name}");
                managedParticles.Remove(info);
            }
        }
    }
    
    private ParticleSystemInfo GetParticleSystemInfo(ParticleSystem ps)
    {
        return managedParticles.FirstOrDefault(p => p.particleSystem == ps);
    }
    
    // 공개 API 메서드들
    public void SetParticlePriority(ParticleSystem ps, int newPriority)
    {
        var info = GetParticleSystemInfo(ps);
        if (info != null)
        {
            info.priority = newPriority;
            Debug.Log($"[AIT Particle] 우선순위 변경: {ps.name} -> {newPriority}");
        }
    }
    
    public void SetParticleQuality(ParticleSystem ps, ParticleSystemInfo.QualityLevel newQuality)
    {
        var info = GetParticleSystemInfo(ps);
        if (info != null)
        {
            info.qualityLevel = newQuality;
            if (info.isActive)
            {
                ApplyQualitySettings(info);
            }
        }
    }
    
    public ParticleBudgetStats GetBudgetStats()
    {
        return new ParticleBudgetStats
        {
            totalActiveParticles = totalActiveParticles,
            maxTotalParticles = budget.maxTotalParticles,
            activeEmitters = managedParticles.Count(p => p.isActive),
            maxActiveEmitters = budget.maxActiveEmitters,
            memoryUsage = currentMemoryUsage,
            maxMemoryUsage = budget.maxMemoryUsage,
            fps = currentFPS,
            categoryUsage = new Dictionary<string, int>(categoryUsage),
            qualityUsage = new Dictionary<ParticleSystemInfo.QualityLevel, int>(qualityUsage)
        };
    }
    
    public void ForceCleanup()
    {
        foreach (var info in managedParticles.ToList())
        {
            if (info.particleSystem == null || !info.isActive)
            {
                managedParticles.Remove(info);
            }
        }
        
        UpdateUsageStatistics();
        Debug.Log($"[AIT Particle] 강제 정리 완료 - 활성 파티클: {totalActiveParticles}");
    }
    
    public void SetGlobalQuality(ParticleSystemInfo.QualityLevel globalQuality)
    {
        foreach (var info in managedParticles)
        {
            if (info.qualityLevel > globalQuality)
            {
                info.qualityLevel = globalQuality;
                if (info.isActive)
                {
                    ApplyQualitySettings(info);
                }
            }
        }
        
        Debug.Log($"[AIT Particle] 전역 품질 설정: {globalQuality}");
    }
}

[System.Serializable]
public class ParticleBudgetStats
{
    public int totalActiveParticles;
    public int maxTotalParticles;
    public int activeEmitters;
    public int maxActiveEmitters;
    public float memoryUsage;
    public float maxMemoryUsage;
    public float fps;
    public Dictionary<string, int> categoryUsage;
    public Dictionary<AITParticleBudgetManager.ParticleSystemInfo.QualityLevel, int> qualityUsage;
    
    public float GetBudgetUtilization()
    {
        return maxTotalParticles > 0 ? (float)totalActiveParticles / maxTotalParticles : 0f;
    }
    
    public float GetEmitterUtilization()
    {
        return maxActiveEmitters > 0 ? (float)activeEmitters / maxActiveEmitters : 0f;
    }
    
    public float GetMemoryUtilization()
    {
        return maxMemoryUsage > 0 ? memoryUsage / maxMemoryUsage : 0f;
    }
}
```

### 2. 파티클 LOD(Level of Detail) 시스템

```c#
// Unity C# - 파티클 LOD 관리자
using UnityEngine;
using System.Collections.Generic;

public class AITParticleLODManager : MonoBehaviour
{
    [System.Serializable]
    public class ParticleLOD
    {
        [Header("거리 기반 LOD")]
        public float[] lodDistances = { 10f, 25f, 50f };  // LOD 전환 거리
        public float[] particleMultipliers = { 1f, 0.5f, 0.25f, 0f }; // 거리별 파티클 배수
        
        [Header("성능 기반 LOD")]
        public bool enablePerformanceLOD = true;
        public float fpsThreshold = 30f;
        public float memoryThreshold = 80f; // MB
        
        [Header("가시성 기반 LOD")]
        public bool enableFrustumCulling = true;
        public bool enableOcclusionCulling = false;
        public LayerMask cullingLayers = -1;
    }
    
    [System.Serializable]
    public class ParticleLODInfo
    {
        public ParticleSystem particleSystem;
        public Transform referenceTransform;        // LOD 계산 기준점
        public int originalMaxParticles;
        public int currentLODLevel;
        public bool isVisible;
        public float distanceToCamera;
        public Vector3 lastPosition;
        public Bounds bounds;
    }
    
    private Camera mainCamera;
    private List<ParticleLODInfo> lodParticles;
    private AITParticleBudgetManager budgetManager;
    
    [Header("LOD 설정")]
    public ParticleLOD lodSettings;
    public float updateInterval = 0.5f;             // LOD 업데이트 간격
    public bool enableDebugVisualization = false;   // 디버그 시각화
    
    private void Start()
    {
        mainCamera = Camera.main ?? FindObjectOfType<Camera>();
        budgetManager = AITParticleBudgetManager.Instance;
        lodParticles = new List<ParticleLODInfo>();
        
        // 씬의 모든 파티클 시스템 등록
        RegisterAllParticleSystems();
        
        InvokeRepeating(nameof(UpdateLOD), 0f, updateInterval);
    }
    
    private void RegisterAllParticleSystems()
    {
        var allParticles = FindObjectsOfType<ParticleSystem>();
        
        foreach (var ps in allParticles)
        {
            RegisterParticleSystem(ps);
        }
        
        Debug.Log($"[AIT ParticleLOD] {allParticles.Length}개 파티클 시스템 등록");
    }
    
    public void RegisterParticleSystem(ParticleSystem ps, Transform referenceTransform = null)
    {
        if (ps == null) return;
        
        var lodInfo = new ParticleLODInfo
        {
            particleSystem = ps,
            referenceTransform = referenceTransform ?? ps.transform,
            originalMaxParticles = ps.main.maxParticles,
            currentLODLevel = 0,
            isVisible = true,
            lastPosition = ps.transform.position
        };
        
        // 파티클 시스템의 바운드 계산
        var renderer = ps.GetComponent<ParticleSystemRenderer>();
        if (renderer != null)
        {
            lodInfo.bounds = renderer.bounds;
        }
        
        lodParticles.Add(lodInfo);
    }
    
    private void UpdateLOD()
    {
        if (mainCamera == null) return;
        
        Vector3 cameraPos = mainCamera.transform.position;
        Plane[] frustumPlanes = null;
        
        if (lodSettings.enableFrustumCulling)
        {
            frustumPlanes = GeometryUtility.CalculateFrustumPlanes(mainCamera);
        }
        
        foreach (var lodInfo in lodParticles)
        {
            if (lodInfo.particleSystem == null) continue;
            
            UpdateParticleLOD(lodInfo, cameraPos, frustumPlanes);
        }
    }
    
    private void UpdateParticleLOD(ParticleLODInfo lodInfo, Vector3 cameraPos, Plane[] frustumPlanes)
    {
        var ps = lodInfo.particleSystem;
        var psTransform = lodInfo.referenceTransform;
        
        // 거리 계산
        lodInfo.distanceToCamera = Vector3.Distance(cameraPos, psTransform.position);
        
        // 가시성 검사
        bool wasVisible = lodInfo.isVisible;
        lodInfo.isVisible = CheckVisibility(lodInfo, frustumPlanes);
        
        // LOD 레벨 결정
        int newLODLevel = CalculateLODLevel(lodInfo);
        
        // LOD 적용
        if (newLODLevel != lodInfo.currentLODLevel || wasVisible != lodInfo.isVisible)
        {
            ApplyLOD(lodInfo, newLODLevel);
            lodInfo.currentLODLevel = newLODLevel;
        }
        
        // 위치 업데이트
        lodInfo.lastPosition = psTransform.position;
    }
    
    private bool CheckVisibility(ParticleLODInfo lodInfo, Plane[] frustumPlanes)
    {
        // 프러스텀 컬링
        if (lodSettings.enableFrustumCulling && frustumPlanes != null)
        {
            if (!GeometryUtility.TestPlanesAABB(frustumPlanes, lodInfo.bounds))
            {
                return false;
            }
        }
        
        // 오클루전 컬링
        if (lodSettings.enableOcclusionCulling)
        {
            if (IsOccluded(lodInfo))
            {
                return false;
            }
        }
        
        return true;
    }
    
    private bool IsOccluded(ParticleLODInfo lodInfo)
    {
        Vector3 cameraPos = mainCamera.transform.position;
        Vector3 particlePos = lodInfo.referenceTransform.position;
        
        // 레이캐스트를 통한 오클루전 검사
        if (Physics.Raycast(cameraPos, (particlePos - cameraPos).normalized, 
            out RaycastHit hit, lodInfo.distanceToCamera, lodSettings.cullingLayers))
        {
            return hit.distance < lodInfo.distanceToCamera - 1f; // 1미터 버퍼
        }
        
        return false;
    }
    
    private int CalculateLODLevel(ParticleLODInfo lodInfo)
    {
        // 보이지 않으면 최고 LOD (비활성화)
        if (!lodInfo.isVisible)
        {
            return lodSettings.lodDistances.Length;
        }
        
        // 거리 기반 LOD
        for (int i = 0; i < lodSettings.lodDistances.Length; i++)
        {
            if (lodInfo.distanceToCamera <= lodSettings.lodDistances[i])
            {
                return i;
            }
        }
        
        return lodSettings.lodDistances.Length; // 최고 거리 = 최고 LOD
    }
    
    private void ApplyLOD(ParticleLODInfo lodInfo, int lodLevel)
    {
        var ps = lodInfo.particleSystem;
        var main = ps.main;
        
        if (lodLevel >= lodSettings.particleMultipliers.Length)
        {
            // 완전히 비활성화
            ps.Stop(true, ParticleSystemStopBehavior.StopEmittingAndClear);
            return;
        }
        
        float multiplier = lodSettings.particleMultipliers[lodLevel];
        
        if (multiplier <= 0f)
        {
            // 파티클 비활성화
            ps.Stop(true, ParticleSystemStopBehavior.StopEmittingAndClear);
        }
        else
        {
            // 파티클 수 조정
            int newMaxParticles = Mathf.RoundToInt(lodInfo.originalMaxParticles * multiplier);
            main.maxParticles = Mathf.Max(1, newMaxParticles);
            
            // 이미션 레이트 조정
            var emission = ps.emission;
            if (emission.enabled)
            {
                var rate = emission.rateOverTime;
                emission.rateOverTime = rate.constant * multiplier;
            }
            
            // 필요시 파티클 시스템 재시작
            if (!ps.isPlaying && lodInfo.isVisible)
            {
                ps.Play();
            }
        }
        
        // 성능 기반 추가 조정
        ApplyPerformanceBasedLOD(lodInfo, multiplier);
        
        if (enableDebugVisualization)
        {
            Debug.Log($"[AIT ParticleLOD] {ps.name} LOD {lodLevel} 적용 (배수: {multiplier}, 파티클: {main.maxParticles})");
        }
    }
    
    private void ApplyPerformanceBasedLOD(ParticleLODInfo lodInfo, float baseMutiplier)
    {
        if (!lodSettings.enablePerformanceLOD) return;
        
        var budgetStats = budgetManager?.GetBudgetStats();
        if (budgetStats == null) return;
        
        float performanceMultiplier = 1f;
        
        // FPS 기반 조정
        if (budgetStats.fps < lodSettings.fpsThreshold)
        {
            performanceMultiplier *= 0.7f; // 30% 감소
        }
        
        // 메모리 기반 조정
        if (budgetStats.memoryUsage > lodSettings.memoryThreshold)
        {
            performanceMultiplier *= 0.8f; // 20% 감소
        }
        
        // 예산 활용률 기반 조정
        float budgetUtilization = budgetStats.GetBudgetUtilization();
        if (budgetUtilization > 0.9f)
        {
            performanceMultiplier *= 0.6f; // 40% 감소
        }
        
        if (performanceMultiplier < 1f)
        {
            var ps = lodInfo.particleSystem;
            var main = ps.main;
            
            int adjustedMaxParticles = Mathf.RoundToInt(main.maxParticles * performanceMultiplier);
            main.maxParticles = Mathf.Max(1, adjustedMaxParticles);
            
            if (enableDebugVisualization)
            {
                Debug.Log($"[AIT ParticleLOD] 성능 기반 조정: {ps.name} (배수: {performanceMultiplier})");
            }
        }
    }
    
    // 공개 API 메서드들
    public void SetLODDistance(int lodLevel, float distance)
    {
        if (lodLevel >= 0 && lodLevel < lodSettings.lodDistances.Length)
        {
            lodSettings.lodDistances[lodLevel] = distance;
        }
    }
    
    public void SetLODMultiplier(int lodLevel, float multiplier)
    {
        if (lodLevel >= 0 && lodLevel < lodSettings.particleMultipliers.Length)
        {
            lodSettings.particleMultipliers[lodLevel] = multiplier;
        }
    }
    
    public void ForceUpdateLOD()
    {
        UpdateLOD();
    }
    
    public ParticleLODStats GetLODStats()
    {
        var stats = new ParticleLODStats();
        
        foreach (var lodInfo in lodParticles)
        {
            if (lodInfo.particleSystem == null) continue;
            
            stats.totalParticleSystems++;
            
            if (lodInfo.isVisible)
                stats.visibleParticleSystems++;
            
            stats.lodLevelCounts[lodInfo.currentLODLevel]++;
            stats.totalActiveParticles += lodInfo.particleSystem.particleCount;
        }
        
        return stats;
    }
    
    public void SetGlobalLODMultiplier(float globalMultiplier)
    {
        for (int i = 0; i < lodSettings.particleMultipliers.Length; i++)
        {
            lodSettings.particleMultipliers[i] *= globalMultiplier;
        }
        
        // 모든 파티클에 즉시 적용
        ForceUpdateLOD();
    }
    
    // 디버그 시각화
    private void OnDrawGizmos()
    {
        if (!enableDebugVisualization || lodParticles == null) return;
        
        foreach (var lodInfo in lodParticles)
        {
            if (lodInfo.particleSystem == null) continue;
            
            // LOD 레벨에 따른 색상
            Color gizmoColor = GetLODColor(lodInfo.currentLODLevel);
            Gizmos.color = gizmoColor;
            
            // 파티클 시스템 위치에 구 그리기
            Gizmos.DrawWireSphere(lodInfo.referenceTransform.position, 1f);
            
            // 거리 정보 표시
            if (mainCamera != null)
            {
                Vector3 cameraPos = mainCamera.transform.position;
                Vector3 particlePos = lodInfo.referenceTransform.position;
                
                Gizmos.color = gizmoColor * 0.5f;
                Gizmos.DrawLine(cameraPos, particlePos);
            }
        }
        
        // LOD 거리 표시
        if (mainCamera != null)
        {
            Vector3 cameraPos = mainCamera.transform.position;
            
            for (int i = 0; i < lodSettings.lodDistances.Length; i++)
            {
                Gizmos.color = GetLODColor(i) * 0.3f;
                Gizmos.DrawWireSphere(cameraPos, lodSettings.lodDistances[i]);
            }
        }
    }
    
    private Color GetLODColor(int lodLevel)
    {
        Color[] lodColors = {
            Color.green,    // LOD 0 - 최고 품질
            Color.yellow,   // LOD 1 - 중간 품질
            Color.orange,   // LOD 2 - 낮은 품질
            Color.red       // LOD 3+ - 매우 낮은/비활성
        };
        
        int colorIndex = Mathf.Min(lodLevel, lodColors.Length - 1);
        return lodColors[colorIndex];
    }
}

[System.Serializable]
public class ParticleLODStats
{
    public int totalParticleSystems;
    public int visibleParticleSystems;
    public int totalActiveParticles;
    public Dictionary<int, int> lodLevelCounts = new Dictionary<int, int>();
    
    public float GetVisibilityRatio()
    {
        return totalParticleSystems > 0 ? (float)visibleParticleSystems / totalParticleSystems : 0f;
    }
    
    public int GetParticleSystemsAtLOD(int lodLevel)
    {
        return lodLevelCounts.ContainsKey(lodLevel) ? lodLevelCounts[lodLevel] : 0;
    }
}
```

### 3. 파티클 풀링 시스템

```c#
// Unity C# - 파티클 오브젝트 풀
using UnityEngine;
using System.Collections.Generic;
using System.Linq;

public class AITParticlePool : MonoBehaviour
{
    [System.Serializable]
    public class ParticlePoolEntry
    {
        public string poolName;
        public ParticleSystem prefab;
        public int initialSize = 10;
        public int maxSize = 50;
        public bool expandable = true;
        public float autoReturnTime = 10f;     // 자동 반환 시간
    }
    
    [System.Serializable]
    public class PooledParticle
    {
        public ParticleSystem particleSystem;
        public string poolName;
        public bool isActive;
        public float spawnTime;
        public float autoReturnTime;
        public Transform originalParent;
        
        public bool ShouldAutoReturn()
        {
            return isActive && autoReturnTime > 0 && 
                   Time.time - spawnTime > autoReturnTime;
        }
    }
    
    private static AITParticlePool instance;
    public static AITParticlePool Instance => instance;
    
    [Header("파티클 풀 설정")]
    public List<ParticlePoolEntry> poolEntries;
    public Transform poolContainer;                 // 풀 컨테이너
    public bool enableAutoReturn = true;           // 자동 반환 활성화
    public float autoReturnCheckInterval = 2f;     // 자동 반환 체크 간격
    
    private Dictionary<string, Queue<PooledParticle>> availablePools;
    private Dictionary<string, List<PooledParticle>> activePools;
    private Dictionary<string, ParticlePoolEntry> poolConfigs;
    
    private void Awake()
    {
        if (instance == null)
        {
            instance = this;
            DontDestroyOnLoad(gameObject);
            InitializePools();
        }
        else
        {
            Destroy(gameObject);
        }
    }
    
    private void InitializePools()
    {
        availablePools = new Dictionary<string, Queue<PooledParticle>>();
        activePools = new Dictionary<string, List<PooledParticle>>();
        poolConfigs = new Dictionary<string, ParticlePoolEntry>();
        
        // 풀 컨테이너 생성
        if (poolContainer == null)
        {
            poolContainer = new GameObject("ParticlePoolContainer").transform;
            poolContainer.SetParent(transform);
        }
        
        // 각 풀 초기화
        foreach (var entry in poolEntries)
        {
            CreatePool(entry);
        }
        
        if (enableAutoReturn)
        {
            InvokeRepeating(nameof(CheckAutoReturn), autoReturnCheckInterval, autoReturnCheckInterval);
        }
        
        Debug.Log($"[AIT ParticlePool] {poolEntries.Count}개 파티클 풀 초기화 완료");
    }
    
    private void CreatePool(ParticlePoolEntry entry)
    {
        if (string.IsNullOrEmpty(entry.poolName) || entry.prefab == null)
        {
            Debug.LogWarning("[AIT ParticlePool] 잘못된 풀 설정");
            return;
        }
        
        var availableQueue = new Queue<PooledParticle>();
        var activeList = new List<PooledParticle>();
        
        // 풀 컨테이너 생성
        var poolObject = new GameObject($"Pool_{entry.poolName}");
        poolObject.transform.SetParent(poolContainer);
        
        // 초기 파티클 생성
        for (int i = 0; i < entry.initialSize; i++)
        {
            var pooledParticle = CreatePooledParticle(entry, poolObject.transform);
            availableQueue.Enqueue(pooledParticle);
        }
        
        availablePools[entry.poolName] = availableQueue;
        activePools[entry.poolName] = activeList;
        poolConfigs[entry.poolName] = entry;
        
        Debug.Log($"[AIT ParticlePool] 풀 생성: {entry.poolName} ({entry.initialSize}개)");
    }
    
    private PooledParticle CreatePooledParticle(ParticlePoolEntry entry, Transform parent)
    {
        var particleObj = Instantiate(entry.prefab, parent);
        particleObj.gameObject.SetActive(false);
        
        var pooledParticle = new PooledParticle
        {
            particleSystem = particleObj,
            poolName = entry.poolName,
            isActive = false,
            autoReturnTime = entry.autoReturnTime,
            originalParent = parent
        };
        
        return pooledParticle;
    }
    
    public ParticleSystem SpawnParticle(string poolName, Vector3 position, Quaternion rotation = default, Transform parent = null)
    {
        if (!availablePools.ContainsKey(poolName))
        {
            Debug.LogWarning($"[AIT ParticlePool] 존재하지 않는 풀: {poolName}");
            return null;
        }
        
        var availableQueue = availablePools[poolName];
        var activeList = activePools[poolName];
        var config = poolConfigs[poolName];
        
        PooledParticle pooledParticle = null;
        
        // 사용 가능한 파티클 찾기
        if (availableQueue.Count > 0)
        {
            pooledParticle = availableQueue.Dequeue();
        }
        else if (config.expandable && activeList.Count < config.maxSize)
        {
            // 풀 확장
            pooledParticle = CreatePooledParticle(config, poolContainer.Find($"Pool_{poolName}"));
            Debug.Log($"[AIT ParticlePool] 풀 확장: {poolName} ({activeList.Count + 1}/{config.maxSize})");
        }
        else
        {
            Debug.LogWarning($"[AIT ParticlePool] 풀 고갈: {poolName}");
            return null;
        }
        
        // 파티클 활성화
        ActivatePooledParticle(pooledParticle, position, rotation, parent);
        activeList.Add(pooledParticle);
        
        return pooledParticle.particleSystem;
    }
    
    private void ActivatePooledParticle(PooledParticle pooledParticle, Vector3 position, Quaternion rotation, Transform parent)
    {
        var ps = pooledParticle.particleSystem;
        var psTransform = ps.transform;
        
        // 위치 및 회전 설정
        psTransform.position = position;
        psTransform.rotation = rotation;
        
        // 부모 설정
        if (parent != null)
        {
            psTransform.SetParent(parent, true);
        }
        else
        {
            psTransform.SetParent(null);
        }
        
        // 파티클 시스템 활성화
        ps.gameObject.SetActive(true);
        ps.Clear();
        ps.Play();
        
        // 풀링 정보 업데이트
        pooledParticle.isActive = true;
        pooledParticle.spawnTime = Time.time;
        
        // 예산 시스템에 등록
        if (AITParticleBudgetManager.Instance != null)
        {
            var main = ps.main;
            AITParticleBudgetManager.Instance.RequestParticleActivation(ps, main.maxParticles);
        }
    }
    
    public void ReturnParticle(ParticleSystem particleSystem)
    {
        if (particleSystem == null) return;
        
        // 활성 풀에서 찾기
        PooledParticle targetPooled = null;
        string targetPoolName = null;
        
        foreach (var kvp in activePools)
        {
            var pooled = kvp.Value.FirstOrDefault(p => p.particleSystem == particleSystem);
            if (pooled != null)
            {
                targetPooled = pooled;
                targetPoolName = kvp.Key;
                break;
            }
        }
        
        if (targetPooled != null)
        {
            ReturnPooledParticle(targetPooled, targetPoolName);
        }
    }
    
    private void ReturnPooledParticle(PooledParticle pooledParticle, string poolName)
    {
        var ps = pooledParticle.particleSystem;
        
        // 파티클 시스템 정지 및 정리
        ps.Stop(true, ParticleSystemStopBehavior.StopEmittingAndClear);
        ps.gameObject.SetActive(false);
        
        // 원래 위치로 복귀
        ps.transform.SetParent(pooledParticle.originalParent);
        ps.transform.localPosition = Vector3.zero;
        ps.transform.localRotation = Quaternion.identity;
        
        // 풀링 정보 업데이트
        pooledParticle.isActive = false;
        pooledParticle.spawnTime = 0f;
        
        // 풀 간 이동
        activePools[poolName].Remove(pooledParticle);
        availablePools[poolName].Enqueue(pooledParticle);
    }
    
    private void CheckAutoReturn()
    {
        foreach (var kvp in activePools)
        {
            var poolName = kvp.Key;
            var activeList = kvp.Value;
            var particlesToReturn = new List<PooledParticle>();
            
            foreach (var pooled in activeList)
            {
                if (pooled.ShouldAutoReturn() || !pooled.particleSystem.isPlaying)
                {
                    particlesToReturn.Add(pooled);
                }
            }
            
            foreach (var pooled in particlesToReturn)
            {
                ReturnPooledParticle(pooled, poolName);
            }
        }
    }
    
    // 편의 메서드들
    public ParticleSystem SpawnParticleAtPosition(string poolName, Vector3 position)
    {
        return SpawnParticle(poolName, position);
    }
    
    public ParticleSystem SpawnParticleWithDuration(string poolName, Vector3 position, float duration)
    {
        var ps = SpawnParticle(poolName, position);
        if (ps != null)
        {
            StartCoroutine(ReturnParticleAfterDelay(ps, duration));
        }
        return ps;
    }
    
    private System.Collections.IEnumerator ReturnParticleAfterDelay(ParticleSystem ps, float delay)
    {
        yield return new WaitForSeconds(delay);
        ReturnParticle(ps);
    }
    
    public void ReturnAllParticles(string poolName = null)
    {
        if (string.IsNullOrEmpty(poolName))
        {
            // 모든 풀의 파티클 반환
            foreach (var kvp in activePools)
            {
                ReturnAllParticlesInPool(kvp.Key);
            }
        }
        else
        {
            ReturnAllParticlesInPool(poolName);
        }
    }
    
    private void ReturnAllParticlesInPool(string poolName)
    {
        if (!activePools.ContainsKey(poolName)) return;
        
        var activeList = activePools[poolName];
        var particlesToReturn = new List<PooledParticle>(activeList);
        
        foreach (var pooled in particlesToReturn)
        {
            ReturnPooledParticle(pooled, poolName);
        }
    }
    
    public ParticlePoolStats GetPoolStats(string poolName = null)
    {
        if (string.IsNullOrEmpty(poolName))
        {
            // 전체 통계
            var totalStats = new ParticlePoolStats();
            
            foreach (var kvp in availablePools)
            {
                string name = kvp.Key;
                totalStats.totalAvailable += kvp.Value.Count;
                totalStats.totalActive += activePools[name].Count;
                totalStats.poolCount++;
            }
            
            return totalStats;
        }
        else
        {
            // 특정 풀 통계
            if (availablePools.ContainsKey(poolName))
            {
                return new ParticlePoolStats
                {
                    poolName = poolName,
                    totalAvailable = availablePools[poolName].Count,
                    totalActive = activePools[poolName].Count,
                    maxSize = poolConfigs[poolName].maxSize,
                    poolCount = 1
                };
            }
            
            return new ParticlePoolStats();
        }
    }
    
    public void PrewarmPool(string poolName, int count)
    {
        if (!poolConfigs.ContainsKey(poolName)) return;
        
        var config = poolConfigs[poolName];
        var availableQueue = availablePools[poolName];
        var poolParent = poolContainer.Find($"Pool_{poolName}");
        
        int currentTotal = availableQueue.Count + activePools[poolName].Count;
        int targetCount = Mathf.Min(currentTotal + count, config.maxSize);
        
        for (int i = currentTotal; i < targetCount; i++)
        {
            var pooledParticle = CreatePooledParticle(config, poolParent);
            availableQueue.Enqueue(pooledParticle);
        }
        
        Debug.Log($"[AIT ParticlePool] 풀 예열: {poolName} ({targetCount}개)");
    }
}

[System.Serializable]
public class ParticlePoolStats
{
    public string poolName = "All";
    public int totalAvailable;
    public int totalActive;
    public int maxSize;
    public int poolCount;
    
    public float GetUtilization()
    {
        int total = totalAvailable + totalActive;
        return maxSize > 0 ? (float)total / maxSize : 0f;
    }
    
    public float GetActiveRatio()
    {
        int total = totalAvailable + totalActive;
        return total > 0 ? (float)totalActive / total : 0f;
    }
}
```

***

## 코드 예제 및 설정

### 1. 파티클 효과 매니저

```c#
// Unity C# - 통합 파티클 효과 매니저
using UnityEngine;
using System.Collections.Generic;

public class AITParticleEffectManager : MonoBehaviour
{
    [System.Serializable]
    public class ParticleEffect
    {
        public string effectName;
        public string poolName;
        public Vector3 offset;
        public float duration;
        public int priority;
        public string category;
        public ParticleSystemInfo.QualityLevel quality;
        public AudioClip soundEffect;
        public float soundVolume = 1f;
    }
    
    private AITParticleBudgetManager budgetManager;
    private AITParticlePool particlePool;
    private AudioSource audioSource;
    
    [Header("파티클 효과 설정")]
    public List<ParticleEffect> particleEffects;
    public bool enableSoundEffects = true;
    public LayerMask effectLayers = -1;
    
    private Dictionary<string, ParticleEffect> effectLookup;
    
    private void Start()
    {
        budgetManager = AITParticleBudgetManager.Instance;
        particlePool = AITParticlePool.Instance;
        audioSource = GetComponent<AudioSource>() ?? gameObject.AddComponent<AudioSource>();
        
        InitializeEffects();
    }
    
    private void InitializeEffects()
    {
        effectLookup = new Dictionary<string, ParticleEffect>();
        
        foreach (var effect in particleEffects)
        {
            if (!string.IsNullOrEmpty(effect.effectName))
            {
                effectLookup[effect.effectName] = effect;
            }
        }
        
        Debug.Log($"[AIT ParticleEffect] {particleEffects.Count}개 파티클 효과 등록");
    }
    
    public ParticleSystem PlayEffect(string effectName, Vector3 position, Quaternion rotation = default, Transform parent = null)
    {
        if (!effectLookup.ContainsKey(effectName))
        {
            Debug.LogWarning($"[AIT ParticleEffect] 존재하지 않는 효과: {effectName}");
            return null;
        }
        
        var effect = effectLookup[effectName];
        Vector3 finalPosition = position + rotation * effect.offset;
        
        // 파티클 스폰
        var ps = particlePool?.SpawnParticle(effect.poolName, finalPosition, rotation, parent);
        if (ps == null) return null;
        
        // 예산 관리에 등록
        budgetManager?.RegisterParticleSystem(ps, effect.category, effect.priority, effect.quality);
        
        // 사운드 효과 재생
        if (enableSoundEffects && effect.soundEffect != null)
        {
            PlaySoundEffect(effect.soundEffect, effect.soundVolume, position);
        }
        
        // 자동 정리 설정
        if (effect.duration > 0)
        {
            StartCoroutine(StopEffectAfterDelay(ps, effect.duration));
        }
        
        return ps;
    }
    
    private void PlaySoundEffect(AudioClip clip, float volume, Vector3 position)
    {
        if (audioSource.isPlaying && audioSource.clip == clip) return;
        
        audioSource.clip = clip;
        audioSource.volume = volume;
        audioSource.Play();
    }
    
    private System.Collections.IEnumerator StopEffectAfterDelay(ParticleSystem ps, float delay)
    {
        yield return new WaitForSeconds(delay);
        
        if (ps != null)
        {
            particlePool?.ReturnParticle(ps);
        }
    }
    
    // 편의 메서드들
    public ParticleSystem PlayHitEffect(Vector3 position, Vector3 normal)
    {
        Quaternion rotation = Quaternion.LookRotation(normal);
        return PlayEffect("hit", position, rotation);
    }
    
    public ParticleSystem PlayExplosionEffect(Vector3 position, float scale = 1f)
    {
        var ps = PlayEffect("explosion", position);
        if (ps != null && scale != 1f)
        {
            ps.transform.localScale = Vector3.one * scale;
        }
        return ps;
    }
    
    public ParticleSystem PlayTrailEffect(Vector3 startPos, Vector3 endPos)
    {
        Vector3 direction = (endPos - startPos).normalized;
        Quaternion rotation = Quaternion.LookRotation(direction);
        return PlayEffect("trail", startPos, rotation);
    }
    
    public void StopAllEffects()
    {
        particlePool?.ReturnAllParticles();
    }
    
    public void StopEffectsByCategory(string category)
    {
        // 카테고리별 효과 중지 (구현 필요)
        Debug.Log($"[AIT ParticleEffect] 카테고리별 효과 중지: {category}");
    }
}
```

### 2. 파티클 성능 모니터

```c#
// Unity C# - 파티클 성능 모니터링
using UnityEngine;
using UnityEngine.UI;
using System.Collections.Generic;

public class AITParticlePerformanceMonitor : MonoBehaviour
{
    [System.Serializable]
    public class PerformanceMetrics
    {
        public int totalActiveParticles;
        public int totalActiveEmitters;
        public float particleMemoryUsage;
        public float averageFPS;
        public float budgetUtilization;
        public Dictionary<string, int> categoryBreakdown;
        public Dictionary<int, int> qualityBreakdown;
    }
    
    private AITParticleBudgetManager budgetManager;
    private AITParticleLODManager lodManager;
    private AITParticlePool particlePool;
    
    [Header("모니터링 UI")]
    public Canvas monitorUI;
    public Text totalParticlesText;
    public Text budgetUtilizationText;
    public Text fpsText;
    public Text memoryText;
    public Slider budgetSlider;
    public Button optimizeButton;
    
    [Header("모니터링 설정")]
    public bool showMonitorUI = true;
    public float updateInterval = 0.5f;
    public bool enableAutoOptimization = true;
    public float optimizationThreshold = 0.85f; // 85% 이상 사용률에서 최적화
    
    private PerformanceMetrics currentMetrics;
    private List<float> fpsHistory;
    private const int FPS_HISTORY_SIZE = 30;
    
    private void Start()
    {
        budgetManager = AITParticleBudgetManager.Instance;
        lodManager = FindObjectOfType<AITParticleLODManager>();
        particlePool = AITParticlePool.Instance;
        
        fpsHistory = new List<float>();
        currentMetrics = new PerformanceMetrics
        {
            categoryBreakdown = new Dictionary<string, int>(),
            qualityBreakdown = new Dictionary<int, int>()
        };
        
        SetupUI();
        
        InvokeRepeating(nameof(UpdateMetrics), 0f, updateInterval);
        
        if (enableAutoOptimization)
        {
            InvokeRepeating(nameof(CheckAutoOptimization), 5f, 5f);
        }
    }
    
    private void SetupUI()
    {
        if (monitorUI != null)
        {
            monitorUI.gameObject.SetActive(showMonitorUI);
        }
        
        if (optimizeButton != null)
        {
            optimizeButton.onClick.AddListener(PerformManualOptimization);
        }
    }
    
    private void UpdateMetrics()
    {
        CollectMetrics();
        UpdateUI();
        
        // 성능 히스토리 업데이트
        fpsHistory.Add(currentMetrics.averageFPS);
        if (fpsHistory.Count > FPS_HISTORY_SIZE)
        {
            fpsHistory.RemoveAt(0);
        }
    }
    
    private void CollectMetrics()
    {
        // 예산 관리자에서 메트릭 수집
        if (budgetManager != null)
        {
            var budgetStats = budgetManager.GetBudgetStats();
            currentMetrics.totalActiveParticles = budgetStats.totalActiveParticles;
            currentMetrics.totalActiveEmitters = budgetStats.activeEmitters;
            currentMetrics.budgetUtilization = budgetStats.GetBudgetUtilization();
            currentMetrics.particleMemoryUsage = budgetStats.memoryUsage;
            currentMetrics.categoryBreakdown = new Dictionary<string, int>(budgetStats.categoryUsage);
        }
        
        // FPS 계산
        currentMetrics.averageFPS = 1f / Time.deltaTime;
        
        // LOD 관리자에서 추가 메트릭
        if (lodManager != null)
        {
            var lodStats = lodManager.GetLODStats();
            // LOD 관련 메트릭 추가 처리
        }
    }
    
    private void UpdateUI()
    {
        if (!showMonitorUI || monitorUI == null) return;
        
        // 총 파티클 수
        if (totalParticlesText != null)
        {
            totalParticlesText.text = $"활성 파티클: {currentMetrics.totalActiveParticles}";
        }
        
        // 예산 활용률
        if (budgetUtilizationText != null)
        {
            float utilization = currentMetrics.budgetUtilization * 100f;
            budgetUtilizationText.text = $"예산 사용률: {utilization:F1}%";
            
            // 색상 변경
            if (utilization > 90f)
                budgetUtilizationText.color = Color.red;
            else if (utilization > 70f)
                budgetUtilizationText.color = Color.yellow;
            else
                budgetUtilizationText.color = Color.green;
        }
        
        // 예산 슬라이더
        if (budgetSlider != null)
        {
            budgetSlider.value = currentMetrics.budgetUtilization;
        }
        
        // FPS
        if (fpsText != null)
        {
            fpsText.text = $"FPS: {currentMetrics.averageFPS:F1}";
            
            if (currentMetrics.averageFPS < 30f)
                fpsText.color = Color.red;
            else if (currentMetrics.averageFPS < 45f)
                fpsText.color = Color.yellow;
            else
                fpsText.color = Color.green;
        }
        
        // 메모리
        if (memoryText != null)
        {
            memoryText.text = $"메모리: {currentMetrics.particleMemoryUsage:F1} MB";
        }
    }
    
    private void CheckAutoOptimization()
    {
        if (currentMetrics.budgetUtilization > optimizationThreshold)
        {
            Debug.Log($"[AIT ParticleMonitor] 자동 최적화 실행 (사용률: {currentMetrics.budgetUtilization:P1})");
            PerformAutomaticOptimization();
        }
    }
    
    private void PerformAutomaticOptimization()
    {
        // 1. LOD 시스템 최적화
        if (lodManager != null)
        {
            lodManager.SetGlobalLODMultiplier(0.8f);
        }
        
        // 2. 품질 저하
        if (budgetManager != null)
        {
            budgetManager.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Medium);
        }
        
        // 3. 불필요한 파티클 정리
        if (particlePool != null)
        {
            particlePool.ReturnAllParticles();
        }
        
        Debug.Log("[AIT ParticleMonitor] 자동 최적화 완료");
    }
    
    public void PerformManualOptimization()
    {
        Debug.Log("[AIT ParticleMonitor] 수동 최적화 실행");
        
        // 사용자가 요청한 최적화
        PerformAutomaticOptimization();
        
        // 추가적인 최적화 옵션들
        OptimizeParticleQuality();
        CleanupInactiveParticles();
    }
    
    private void OptimizeParticleQuality()
    {
        // 현재 FPS에 따른 품질 조정
        AITParticleBudgetManager.ParticleSystemInfo.QualityLevel targetQuality;
        
        if (currentMetrics.averageFPS < 25f)
        {
            targetQuality = AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Low;
        }
        else if (currentMetrics.averageFPS < 40f)
        {
            targetQuality = AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Medium;
        }
        else
        {
            targetQuality = AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.High;
        }
        
        budgetManager?.SetGlobalQuality(targetQuality);
    }
    
    private void CleanupInactiveParticles()
    {
        budgetManager?.ForceCleanup();
        particlePool?.ReturnAllParticles();
    }
    
    // 공개 API 메서드들
    public PerformanceMetrics GetCurrentMetrics()
    {
        return currentMetrics;
    }
    
    public float GetAverageFPS(int sampleCount = 10)
    {
        if (fpsHistory.Count == 0) return 0f;
        
        int samples = Mathf.Min(sampleCount, fpsHistory.Count);
        float total = 0f;
        
        for (int i = fpsHistory.Count - samples; i < fpsHistory.Count; i++)
        {
            total += fpsHistory[i];
        }
        
        return total / samples;
    }
    
    public void SetOptimizationThreshold(float threshold)
    {
        optimizationThreshold = Mathf.Clamp01(threshold);
    }
    
    public void ToggleMonitorUI()
    {
        showMonitorUI = !showMonitorUI;
        if (monitorUI != null)
        {
            monitorUI.gameObject.SetActive(showMonitorUI);
        }
    }
    
    // 디버그 정보 출력
    [ContextMenu("Print Performance Report")]
    public void PrintPerformanceReport()
    {
        var report = $@"
=== 파티클 성능 리포트 ===
총 활성 파티클: {currentMetrics.totalActiveParticles}
총 활성 이미터: {currentMetrics.totalActiveEmitters}
예산 사용률: {currentMetrics.budgetUtilization:P1}
평균 FPS: {currentMetrics.averageFPS:F1}
메모리 사용량: {currentMetrics.particleMemoryUsage:F1} MB

=== 카테고리별 분석 ===";
        
        foreach (var kvp in currentMetrics.categoryBreakdown)
        {
            report += $"\n{kvp.Key}: {kvp.Value}개";
        }
        
        report += "\n========================";
        
        Debug.Log(report);
    }
}
```

***

## 문제 해결 및 디버깅

### 1. 일반적인 파티클 성능 문제

#### 메모리 누수 감지 및 해결

```c#
public class AITParticleMemoryDiagnostic : MonoBehaviour
{
    public void DiagnoseMemoryLeaks()
    {
        // 활성 파티클 시스템 분석
        var allParticles = FindObjectsOfType<ParticleSystem>();
        var suspiciousParticles = new List<ParticleSystem>();
        
        foreach (var ps in allParticles)
        {
            // 긴 시간 동안 계속 파티클을 생성하는 시스템 감지
            if (ps.isPlaying && ps.main.loop && ps.particleCount > ps.main.maxParticles * 0.8f)
            {
                suspiciousParticles.Add(ps);
            }
        }
        
        Debug.Log($"[AIT Diagnostic] 메모리 누수 의심 파티클: {suspiciousParticles.Count}개");
        
        foreach (var ps in suspiciousParticles)
        {
            Debug.LogWarning($"  - {ps.name}: {ps.particleCount}/{ps.main.maxParticles} 파티클");
        }
    }
    
    public void FixMemoryLeaks()
    {
        var allParticles = FindObjectsOfType<ParticleSystem>();
        
        foreach (var ps in allParticles)
        {
            // 과도한 파티클 생성 중단
            if (ps.particleCount > 1000)
            {
                ps.Stop(true, ParticleSystemStopBehavior.StopEmittingAndClear);
                Debug.Log($"[AIT Fix] 과도한 파티클 시스템 정지: {ps.name}");
            }
        }
    }
}
```

#### 성능 최적화 권장사항

```c#
public class AITParticleOptimizationSuggestions
{
    public static void AnalyzeAndSuggest(ParticleSystem ps)
    {
        Debug.Log($"=== {ps.name} 최적화 분석 ===");
        
        var main = ps.main;
        var emission = ps.emission;
        var shape = ps.shape;
        var renderer = ps.GetComponent<ParticleSystemRenderer>();
        
        // 파티클 수 최적화
        if (main.maxParticles > 500)
        {
            Debug.LogWarning("권장사항: 최대 파티클 수를 500개 이하로 제한하세요");
        }
        
        // 이미션 최적화
        if (emission.enabled && emission.rateOverTime.constant > 100)
        {
            Debug.LogWarning("권장사항: 초당 이미션을 100개 이하로 줄이세요");
        }
        
        // 렌더링 최적화
        if (renderer != null)
        {
            if (renderer.material != null && renderer.material.shader.name.Contains("Standard"))
            {
                Debug.LogWarning("권장사항: 모바일 최적화 쉐이더 사용을 고려하세요");
            }
            
            if (renderer.sortMode == ParticleSystemSortMode.Distance)
            {
                Debug.LogWarning("권장사항: 정렬이 필요하지 않다면 None으로 설정하세요");
            }
        }
        
        // 충돌 검사 최적화
        var collision = ps.collision;
        if (collision.enabled && collision.type == ParticleSystemCollisionType.World)
        {
            Debug.LogWarning("권장사항: 월드 충돌 대신 Planes 사용을 고려하세요");
        }
    }
}
```

***

## 관련 도구 및 리소스

### 1. 파티클 예산 설정 도구

```c#
// Unity Editor - 파티클 예산 설정 에디터
#if UNITY_EDITOR
using UnityEngine;
using UnityEditor;

[CustomEditor(typeof(AITParticleBudgetManager))]
public class AITParticleBudgetEditor : Editor
{
    public override void OnInspectorGUI()
    {
        DrawDefaultInspector();
        
        AITParticleBudgetManager manager = (AITParticleBudgetManager)target;
        
        EditorGUILayout.Space();
        EditorGUILayout.LabelField("실시간 통계", EditorStyles.boldLabel);
        
        if (Application.isPlaying && manager != null)
        {
            var stats = manager.GetBudgetStats();
            
            EditorGUILayout.LabelField($"활성 파티클: {stats.totalActiveParticles}/{stats.maxTotalParticles}");
            EditorGUILayout.LabelField($"활성 이미터: {stats.activeEmitters}/{stats.maxActiveEmitters}");
            EditorGUILayout.LabelField($"메모리 사용: {stats.memoryUsage:F1}/{stats.maxMemoryUsage} MB");
            EditorGUILayout.LabelField($"현재 FPS: {stats.fps:F1}");
            
            // 예산 사용률 프로그레스 바
            float budgetUtilization = stats.GetBudgetUtilization();
            EditorGUILayout.LabelField($"예산 사용률: {budgetUtilization:P1}");
            
            Rect rect = EditorGUILayout.GetControlRect();
            EditorGUI.ProgressBar(rect, budgetUtilization, "Budget Utilization");
            
            // 카테고리별 분석
            EditorGUILayout.Space();
            EditorGUILayout.LabelField("카테고리별 사용량", EditorStyles.boldLabel);
            
            foreach (var category in stats.categoryUsage)
            {
                EditorGUILayout.LabelField($"{category.Key}: {category.Value}개");
            }
        }
        else
        {
            EditorGUILayout.LabelField("플레이 모드에서만 통계 표시");
        }
        
        EditorGUILayout.Space();
        
        // 유틸리티 버튼들
        if (GUILayout.Button("강제 정리"))
        {
            if (Application.isPlaying)
            {
                manager.ForceCleanup();
            }
        }
        
        if (GUILayout.Button("전체 품질 - 낮음"))
        {
            if (Application.isPlaying)
            {
                manager.SetGlobalQuality(AITParticleBudgetManager.ParticleSystemInfo.QualityLevel.Low);
            }
        }
        
        if (GUILayout.Button("성능 리포트 출력"))
        {
            var monitor = FindObjectOfType<AITParticlePerformanceMonitor>();
            if (monitor != null)
            {
                monitor.PrintPerformanceReport();
            }
        }
    }
}
#endif
```

### 2. 자동화된 파티클 최적화 도구

```c#
// Unity Editor - 자동 파티클 최적화 도구
#if UNITY_EDITOR
using UnityEngine;
using UnityEditor;
using System.Collections.Generic;

public class AITParticleOptimizerWindow : EditorWindow
{
    private Vector2 scrollPosition;
    private List<ParticleSystem> sceneParticles;
    private Dictionary<ParticleSystem, OptimizationSuggestion> suggestions;
    
    [System.Serializable]
    public class OptimizationSuggestion
    {
        public string issue;
        public string solution;
        public System.Action fix;
        public bool canAutoFix;
    }
    
    [MenuItem("앱인토스/파티클 최적화 도구")]
    public static void ShowWindow()
    {
        GetWindow<AITParticleOptimizerWindow>("파티클 최적화 도구");
    }
    
    private void OnGUI()
    {
        GUILayout.Label("파티클 시스템 최적화 도구", EditorStyles.boldLabel);
        
        if (GUILayout.Button("씬 분석"))
        {
            AnalyzeScene();
        }
        
        if (sceneParticles != null && sceneParticles.Count > 0)
        {
            scrollPosition = EditorGUILayout.BeginScrollView(scrollPosition);
            
            foreach (var ps in sceneParticles)
            {
                if (ps == null) continue;
                
                EditorGUILayout.BeginVertical("box");
                EditorGUILayout.LabelField(ps.name, EditorStyles.boldLabel);
                
                if (suggestions.ContainsKey(ps))
                {
                    var suggestion = suggestions[ps];
                    EditorGUILayout.LabelField($"문제: {suggestion.issue}");
                    EditorGUILayout.LabelField($"해결책: {suggestion.solution}");
                    
                    if (suggestion.canAutoFix && GUILayout.Button("자동 수정"))
                    {
                        suggestion.fix?.Invoke();
                    }
                }
                
                EditorGUILayout.EndVertical();
            }
            
            EditorGUILayout.EndScrollView();
            
            if (GUILayout.Button("모든 문제 자동 수정"))
            {
                AutoFixAllIssues();
            }
        }
    }
    
    private void AnalyzeScene()
    {
        sceneParticles = new List<ParticleSystem>();
        suggestions = new Dictionary<ParticleSystem, OptimizationSuggestion>();
        
        var allParticles = FindObjectsOfType<ParticleSystem>();
        
        foreach (var ps in allParticles)
        {
            sceneParticles.Add(ps);
            
            var suggestion = AnalyzeParticleSystem(ps);
            if (suggestion != null)
            {
                suggestions[ps] = suggestion;
            }
        }
        
        Debug.Log($"파티클 분석 완료: {sceneParticles.Count}개 발견, {suggestions.Count}개 최적화 가능");
    }
    
    private OptimizationSuggestion AnalyzeParticleSystem(ParticleSystem ps)
    {
        var main = ps.main;
        
        // 과도한 파티클 수 검사
        if (main.maxParticles > 1000)
        {
            return new OptimizationSuggestion
            {
                issue = $"과도한 파티클 수: {main.maxParticles}",
                solution = "1000개 이하로 줄이기",
                canAutoFix = true,
                fix = () => {
                    var mainModule = ps.main;
                    mainModule.maxParticles = 500;
                    EditorUtility.SetDirty(ps);
                }
            };
        }
        
        // 비효율적 렌더링 검사
        var renderer = ps.GetComponent<ParticleSystemRenderer>();
        if (renderer != null && renderer.sortMode == ParticleSystemSortMode.Distance)
        {
            return new OptimizationSuggestion
            {
                issue = "거리 정렬 활성화됨",
                solution = "정렬 비활성화로 성능 향상",
                canAutoFix = true,
                fix = () => {
                    renderer.sortMode = ParticleSystemSortMode.None;
                    EditorUtility.SetDirty(ps);
                }
            };
        }
        
        return null;
    }
    
    private void AutoFixAllIssues()
    {
        int fixedCount = 0;
        
        foreach (var kvp in suggestions)
        {
            if (kvp.Value.canAutoFix)
            {
                kvp.Value.fix?.Invoke();
                fixedCount++;
            }
        }
        
        Debug.Log($"{fixedCount}개 파티클 시스템 자동 수정 완료");
        AnalyzeScene(); // 재분석
    }
}
#endif
```

***

## 모범 사례

### 파티클 시스템 설계 가이드라인

1. 파티클 수 제한

* UI 효과: 최대 50개
* 게임플레이 효과: 최대 200개
* 배경 효과: 최대 100개
* 폭발/임팩트: 최대 300개

2. 메모리 효율성

* 텍스처 아틀라스 사용
* 파티클 풀링 필수
* 자동 정리 메커니즘 구현

3. 성능 최적화

* LOD 시스템 적용
* 동적 품질 조정
* 예산 기반 관리

4. 모바일 최적화

* 알파 블렌딩 최소화
* 오버드로우 방지
* 배터리 소모 고려

이러한 파티클 예산 관리 시스템을 통해 앱인토스 플랫폼의 제한된 환경에서도 풍부하고 효율적인 파티클 효과를 구현할 수 있어요.

---

---
url: 'https://developers-apps-in-toss.toss.im/unity/intro/migration-guide.md'
---
# 포팅 순서

아래 그림은 새로운 Unity 게임을 앱인토스 미니앱 플랫폼에 연동하는 주요 포팅 순서를 소개하며, 다음 내용은 각 단계의 작업을 설명해요.

![](/assets/migration_steps.sm9t61s2.png)

* 【1단계】 전환 점검: 게임이 미니앱 환경에서도 잘 동작할 수 있는지 살펴봐요.
* 【2단계】 프로젝트 전환: Unity 프로젝트를 WebGL 기반 미니앱으로 변환해요.
* 【3단계】 플랫폼 기능 연동: AppsInToss SDK를 통해 인증, 결제 등 플랫폼 기능을 연동해요.
* 【4단계】 체험 개선: 미니앱에서의 UX·성능을 최적화해 출시 수준의 품질을 확보해요.
* 【5단계】 배포 및 모니터링: 미니앱을 배포하고, 실행 현황과 사용자 지표를 점검해요.

***

## 1. 호환성 검토

새로운 게임을 미니앱으로 전환하기 전에, 해당 기술 방안이 프로젝트에 적합한지 먼저 확인하세요.\
이미 전환된 사례를 참고해, 현재 프로젝트의 구조·리소스·엔진 버전이 AppsInToss 미니앱 환경에 맞는지 검토하는 단계입니다.

:::info 관련 메뉴얼

* [호환성 평가](/unity/guide/precheck)
* [권장 엔진 버전](/unity/guide/recommend-engine)
  :::

***

## 2. 프로젝트 포팅

이 단계에서는 Unity 프로젝트를 실제로 AppsInToss 미니앱 형태로 변환합니다.\
전환 도구를 이용해 빠르게 WebGL 빌드를 만들고, 플러그인을 설치해 테스트 가능한 미니앱을 생성해보세요.

***

## 3. 앱인토스 SDK 연동

Unity 게임을 앱인토스 SDK와 연동하면, 플랫폼의 다양한 기능을 활용할 수 있습니다.\
토스 로그인, 인앱 결제, 인앱 광고 등 필요한 기능을 선택적으로 연동하세요.

***

## 4. UX 최적화

이 단계까지 진행했다면, 이제 Unity 게임은 앱인토스 미니앱 플랫폼에서 정상적으로 실행될 거예요.\
하지만 더 좋은 게임 경험을 위해선 프로젝트를 계속 다듬고 최적화해야 합니다.

이 섹션에서는 앱인토스 미니앱 플랫폼이 제공하는 튜닝 기능을 소개해요.\
출시 전 마지막으로 성능을 점검하고, 완성도를 높이는 단계예요.

### 첫 씬 로딩 최적화

통계에 따르면 미니앱 사용자는 게임 시작 속도에 매우 민감해요. 시작이 길어지면 이탈률이 눈에 띄게 높아집니다.\
그래서 Unity 네이티브 게임을 앱인토스 미니앱으로 연동할 때는, 첫 씬이 빠르게 표시되도록 최적화하는 게 가장 중요해요.

첫 씬 최적화는 단순한 설정만으로 해결되진 않아요. 대부분의 경우, 첫 프레임 로직과 초기 게임 코드를 직접 다듬어야 해요.

자세한 방법은 아래 메뉴얼을 참고하세요.

:::info 관련 메뉴얼

* [Unity WebGL 게임 시작 속도 향상](/unity/optimization/start/startup-speed)
* [게임 시작 시간 최적화](/unity/optimization/start/startup-sequence)
* [첫 씬 시작 최적화](/unity/optimization/start/first-scene-optimization)
  :::

### 리소스 사전 다운로드

Unity Loader 로딩 중에는 CPU 작업이 집중되고, 네트워크는 상대적으로 여유로운 구간이 있어요.\
이 시점을 활용해 필요한 리소스를 미리 다운로드하면, 게임 씬 로딩 속도를 더 빠르게 만들 수 있어요.
:::info 관련 메뉴얼

* [사전 다운로드 기능 사용](/unity/optimization/start/preload)
  :::

### 실행 성능 개선

Unity WebGL 게임의 실행 성능을 높여 더 좋은 사용자 경험을 만들어보세요.\
성능 프로파일링 도구를 활용하면 병목 구간을 정확히 찾아내고, 체계적으로 최적화할 수 있어요.
:::info 관련 메뉴얼

* [Unity WebGL 성능 최적화](/unity/optimization/runtime/performance)
* [Android CPU Profiler를 이용한 성능 튜닝](/unity/optimization/runtime/android-profiling)
* [Unity Profiler 활용](/unity/optimization/runtime/unity-profiler)
* [Unity WebGL 메모리 최적화](/unity/optimization/runtime/memory)
  :::

### 리소스 압축 및 최적화

게임 리소스를 효과적으로 압축하고 최적화하여 다운로드 시간을 단축하고 메모리 사용량을 줄여요.
:::info 관련 메뉴얼

* [에셋 최적화](/unity/optimization/runtime/asset)
* [텍스처 최적화](/unity/optimization/runtime/compressed-texture)
* [텍스처/오디오 압축](/unity/optimization/runtime/audio-video)
  :::

### WASM 코드 분할

Unity에서 미니앱 프로젝트를 내보내면 코드가 wasm 파일로 변환돼 저장돼요.\
게임을 시작할 때는 완전한 wasm 파일이 모두 로드돼야 실행할 수 있어요.\
wasm 파일을 초기 로딩용과 지연 로딩용으로 나누어 더 작은 초기 패키지로 빠르게 메인 씬에 진입할 수 있습니다.

:::info 관련 메뉴얼

* [코드 분할 도구 사용](/unity/optimization/start/wasm-split)
  :::

### 커버 이미지 설정

시작 커버 설정

로딩 중에는 커버 이미지나 영상으로 자연스러운 과도기를 연출할 수 있습니다.\
자동 숨김 시점 등을 커스터마이즈할 수 있습니다.
:::info 관련 메뉴얼

* [커스텀 로딩 화면 구현](/unity/optimization/start/custom-loading)
  :::

## 5. 배포 및 모니터링

### 성능 모니터링

출시 후 실제 사용자 환경에서의 성능을 모니터링하고 지속적으로 최적화해요.
:::info 관련 메뉴얼

* [성능 모니터링 가이드](/unity/optimization/perf-optimization)
  :::

### 사용자 피드백 및 분석

사용자 로그와 피드백을 수집해 게임 체험을 지속적으로 개선합니다.

### 지속적인 업데이트

버전별 업데이트 전략을 세워 지속적인 서비스 품질을 유지하세요.

:::info 관련 메뉴얼

* 버전 업데이트 가이드
  :::

---

---
url: 'https://developers-apps-in-toss.toss.im/design/prepare/design.md'
description: '피그마를 이용한 앱인토스 미니앱 디자인 가이드입니다. TDS 컴포넌트 라이브러리, 에셋 활용, 색상 적용, 반응형 디자인 방법을 확인하세요.'
---

# 피그마

제공된 라이브러리에 있는 TDS 컴포넌트로 디자인하는 것을 추천해요.\
UI 스타일 개발에 신경쓰지 않고 개발 문서에 있는 코드를 토대로 빠르게 개발할 수 있어요.

***

## **1. 피그마 권한을 먼저 신청해 주세요**

[**채널톡**](https://apps-in-toss.channel.io/workflows/748915)으로 피그마 권한을 신청하면, 초대받은 프로젝트에서 TDS 라이브러리를 사용할 수 있어요.\
피그마 좌측의 Recents 메뉴에서 해당 프로젝트에 들어갈 수 있어요.

![](/assets/figma-1._66C_i5f.png)

## 2. TDS 컴포넌트를 검색해서 사용할 수 있어요

* **TDS Components for ApssInToss :** 각종 컴포넌트가 있는 라이브러리
* **TDS Foundation for AppsInToss :** 폰트, 컬러, 아이콘 라이브러리

![](/assets/figma-2.DokWANWf.png)

단축키 `option + 2` 혹은 왼쪽 Assets 패널에서 원하는 컴포넌트를 찾아보세요.

* 🔵 파란색 원: 개발 문서에서 코드가 제공되는 TDS 컴포넌트예요.
* 🟣 보라색 원: 피그마에서 사용할 수 있지만, 아직 코드가 제공되지 않는 TDS 컴포넌트예요. 별도로 코드를 작성해야 해요.
* 🔴 빨간색 원: 디자인 커스텀을 할 수 없는 TDS 컴포넌트예요.
* 🌈 무지개: 개발 문서가 없어 별도로 코드를 작성해야 해요.

## **3. 에셋, 이미지는 이렇게 활용해 보세요**

1. 제공된 아이콘을 검색해 다른 아이콘으로 교체할 수 있어요.
2. 직접 제작한 아이콘을 컴포넌트로 만들어 교체할 수도 있어요.
   * 직접 제작하려면 [**아이콘 가이드라인**](https://www.notion.so/21b714bbfde780fb84bac2acfbb4a6b9?pvs=21)을 참고해 주세요.
3. 빈 이미지를 `Cmd + 클릭`하고 원하는 이미지를 직접 업로드할 수도 있어요.

![](/assets/figma-3.CZZu8QdX.png)

![](/assets/figma-4.BJxjWJBc.png)

## **참고해 주세요**

1. 모든 화면 최상단엔 🔴 Mobile\_Navigation 컴포넌트를 놓아야 해요. 필수 컴포넌트가 이미 포함된 🌈 Screen을 꺼내서 사용하면 편리해요.
2. 화면에 텍스트만 입력하고 싶을 때는 피그마의 텍스트 대신 🔵 **Mobile\_Text** 컴포넌트를 사용해주세요. 자동으로 모든 플랫폼에서 더큰텍스트 대응이 돼요. 또한 일관된 크기감의 폰트 사이즈를 사용할 수 있고, 자간이나 행간을 신경쓰지 않아도 돼요.
3. 가능한 우측 패널에서만 속성을 조작해주세요. 만약 캔버스에서 컴포넌트를 직접 조작한다면 코드에 없는 속성이 추가돼 개발 과정에서 똑같이 구현하기 어렵거나 오래 걸릴 수 있어요.
4. 가능하면 가로 375px 화면으로 작업해주세요. 다른 사이즈도 쓸 수 있지만, 🔵 **Mobile\_Keypad** 같이 반응형으로 대응되지 않는 일부 컴포넌트가 있어서 불편할 수 있어요.
5. 화면 가장 상단에는 🔵 **Mobile\_Top** 컴포넌트를, 그 아래엔 🔵 **Mobile\_ListRow** 컴포넌트를 사용하면 대부분의 화면을 쉽게 만들 수 있어요.
6. 대부분의 TDS 컴포넌트엔 좌우상하 패딩이 포함되어 있어서 gap 없이 다 붙여서 쓸 수 있도록 만들어졌어요. 예를 들어 🔵 **Mobile\_ListRow** 에는 좁음, 일반, 넓음, 매우넓음 4가지의 상하 패딩 옵션이 내장되어 있어요. 다른 일부 컴포넌트들도 마찬가지예요.

   그래도 만약 사이를 띄워야 한다면 오토레이아웃의 gap을 사용하거나 **🌈 Padding・Margin** 컴포넌트를 사용해보세요. 프리셋으로 되어 있는 마진값을 사용할 수 있어요.

\<FaqAccordion :items='\[
{
q: "컴포넌트가 원하는 대로 동작하지 않아요.",
a: `<p>  <a href="https://techchat-apps-in-toss.toss.im/">개발자 커뮤니티</a>로 문의해 주세요. 빠르게 해결해 드릴게요.</p>`
},
{
q: "원하는 컴포넌트가 없어요.",
a: \`

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/권한/permission.md
---

# 필요한 권한 설정하기

앱에서 클립보드, 위치 정보, 사진첩, 연락처 등의 기능을 사용하려면 권한을 설정해야 해요. 이러한 기능들을 토스앱에서 쓸 수 있도록 권한을 설정하는 방법을 안내해요.

## 권한 목록

아래는 권한 이름과 허용된 작업 목록이에요. 각 권한에 맞는 접근값도 확인해 보세요.

### 클립보드

* 권한 이름: `clipboard`
* 읽기(`read`): [getClipboardText](/bedrock/reference/framework/클립보드/getClipboardText.md)
* 쓰기(`write`): [setClipboardText](/bedrock/reference/framework/클립보드/setClipboardText.md)

### 연락처

* 권한 이름: `contacts`
* 읽기(`read`): [fetchContacts](/bedrock/reference/framework/연락처/fetchContacts.md)

### 사진첩

* 권한 이름: `photos`
* 읽기(`read`): [fetchAlbumPhotos](/bedrock/reference/framework/사진/fetchAlbumPhotos.md)

### 카메라

* 권한 이름: `camera`
* 접근(`access`): [openCamera](/bedrock/reference/framework/카메라/openCamera.md)

### 위치

* 권한 이름: `geolocation`
* 접근(`access`): [startUpdateLocation](/bedrock/reference/framework/위치%20정보/startUpdateLocation.md), [getCurrentLocation](/bedrock/reference/framework/위치%20정보/getCurrentLocation.md), [useGeolocation](/bedrock/reference/framework/위치%20정보/useGeolocation.md)

## 권한 설정하기

앱에서 쓸 권한을 `granite.config.ts`에 정의할 수 있어요. 이는 앱을 검토할 때 쓰여요. [권한 목록](#권한-목록)을 참고해 설정해주세요.

아래는 클립보드와, 카메라, 사진첩을 쓰도록 설정한 예시예요.

::: code-group

```tsx [granite.config.ts]
import { appsInToss } from "@apps-in-toss/framework/plugins";
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  appName: "<my-service-name>",
  plugins: [
    appsInToss({
      permissions: [
        {
          name: "clipboard",
          access: "read",
        },
        {
          name: "clipboard",
          access: "write",
        },
        {
          name: "camera",
          access: "access",
        },
        {
          name: "photos",
          access: "read",
        },
      ],
    }),
  ],
});
```

:::

## 웹뷰 개발환경에서 설정하기

[웹뷰 개발환경](/tutorials/webview)일 때에도 `granite.config.ts`의 `permissions`에 똑같이 설정하면 돼요.

::: code-group

```tsx [granite.config.ts]
import { defineConfig } from "@apps-in-toss/web-framework/config";

export default defineConfig({
  appName: "<my-service-name>", // 앱인토스 콘솔에서 설정한 앱 이름
  web: {
    /* 기존설정 */
  },
  permissions: [
    {
      name: "clipboard",
      access: "read",
    },
    {
      name: "clipboard",
      access: "write",
    },
    {
      name: "camera",
      access: "access",
    },
    {
      name: "photos",
      access: "read",
    },
  ],
});
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/인터렉션/generateHapticFeedback.md
---

# 햅틱 진동 실행하기

## `generateHapticFeedback`

`generateHapticFeedback`은 디바이스에서 햅틱 진동을 발생시키는 함수예요.\
버튼 터치나 화면 전환 시, 촉각적인 반응을 주고 싶을 때 사용할 수 있어요.

### 시그니처

```typescript
function generateHapticFeedback(options: HapticFeedbackOptions): Promise<void>;
```

### 반환 값

### 예제 : 버튼을 눌러 햅틱 일으키기

::: code-group

```js [js]
import { generateHapticFeedback } from "@apps-in-toss/web-framework";

generateHapticFeedback({ type: "tickWeak" });
```

```tsx [React]
import React from "react";
import { generateHapticFeedback } from "@apps-in-toss/web-framework";

function GenerateHapticFeedbackWeb() {
  return (
    <button
      onClick={() => {
        generateHapticFeedback({ type: "tickWeak" });
      }}
      style={{
        padding: "10px 20px",
        borderRadius: "8px",
        border: "none",
        backgroundColor: "#3182f6",
        color: "white",
        cursor: "pointer",
        fontSize: "16px",
      }}
    >
      햅틱
    </button>
  );
}

export default GenerateHapticFeedbackWeb;
```

```tsx [React Native]
import { Button } from "react-native";
import { generateHapticFeedback } from '@apps-in-toss/framework';

function GenerateHapticFeedback() {
  return (
    <Button
      title="햅틱"
      onPress={() => {
        generateHapticFeedback({ type: "tickWeak" });
      }}
    />
  );
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-haptic-feedback](https://github.com/toss/apps-in-toss-examples/tree/main/with-haptic-feedback) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

## `HapticFeedbackOptions`

`HapticFeedbackOptions`는 `generateHapticFeedback` 함수에 전달할 진동의 타입을 정의해요.\
사용 가능한 진동 타입은 아래와 같습니다.

```typescript
type HapticFeedbackType =
| "tickWeak"
| "tap"
| "tickMedium"
| "softMedium"
| "basicWeak"
| "basicMedium"
| "success"
| "error"
| "wiggle"
| "confetti";
```

### 시그니처

```typescript
interface HapticFeedbackOptions {
    type: HapticFeedbackType;
}
```

### 타입 정의

#### `HapticFeedbackOptions`

*`type: HapticFeedbackType`*

#### `HapticFeedbackType`

*`"tickWeak" | "tap" | "tickMedium" | "softMedium" | "basicWeak" | "basicMedium" | "success" | "error" | "wiggle" | "confetti"`*

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/위치
  정보/getCurrentLocation.md
---

# 현재 위치 가져오기

## `getCurrentLocation`

디바이스의 현재 위치 정보를 가져오는 함수예요.
위치 기반 서비스를 구현할 때 사용되고, 한 번만 호출되어 현재 위치를 즉시 반환해요.
예를 들어 지도 앱에서 사용자의 현재 위치를 한 번만 가져올 때, 날씨 앱에서 사용자의 위치를 기반으로 기상 정보를 제공할 때, 매장 찾기 기능에서 사용자의 위치를 기준으로 가까운 매장을 검색할 때 사용하면 유용해요.

## 시그니처

```typescript
function getCurrentLocation(options: {
  accuracy: Accuracy;
}): Promise<Location>;
```

### 파라미터

### 프로퍼티

### 반환 값

## GetCurrentLocationPermissionError

위치 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 `error instanceof GetCurrentLocationPermissionError`를 통해 확인할 수 있어요.

## 시그니처

```typescript
class GetCurrentLocationPermissionError extends PermissionError {
    constructor();
}
```

## 예제

### 디바이스의 현재 위치 정보 가져오기

"권한 확인하기"버튼을 눌러서 현재 위치정보 권한을 확인해요.
사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`GetCurrentLocationPermissionError`](./GetCurrentLocationPermissionError)를 반환해요.
"권한 요청하기"버튼을 눌러서 위치정보 권한을 요청할 수 있어요.

::: code-group

```js [js]
import { Accuracy, getCurrentLocation } from '@apps-in-toss/web-framework';

async function handleGetCurrentLocation() {
  try {
    const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
    console.log(`위치: ${response.coords.latitude}, ${response.coords.longitude}`);
  } catch (error) {
    console.error('위치 정보를 가져오는 데 실패했어요:', error);
  }
}

async function handleGetPermissionForGetCurrentLocation() {
  const permission = await getCurrentLocation.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForGetCurrentLocation() {
  const permission = await getCurrentLocation.openPermissionDialog();
  return permission;
}
```

```tsx [React]
import { Accuracy, getCurrentLocation, Location } from '@apps-in-toss/web-framework';
import { useState } from 'react';


// 현재 위치 정보를 가져와 화면에 표시하는 컴포넌트
function CurrentPosition() {
  const [position, setPosition] = useState<Location | null>(null);

  const handlePress = async () => {
    try {
      const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
      setPosition(response);
    } catch (error) {
      console.error('위치 정보를 가져오는 데 실패했어요:', error);
    }
  };

  return (
    <div>
      {position ? (
        <span>
          위치: {position.coords.latitude}, {position.coords.longitude}
        </span>
      ) : (
        <span>위치 정보를 아직 가져오지 않았어요</span>
      )}
      <input type="button" value="현재 위치 정보 가져오기" onClick={handlePress} />
      <input type="button"
        value="권한 확인하기"
        onClick={async () => {
          alert(await getCurrentLocation.getPermission());
        }}
      />
      <input type="button"
        value="권한 요청하기"
        onClick={async () => {
          alert(await getCurrentLocation.openPermissionDialog());
        }}
      />
    </div>
  );
}
```

```tsx [React Native]
import { Accuracy, getCurrentLocation, Location } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

// 현재 위치 정보를 가져와 화면에 표시하는 컴포넌트
function CurrentPosition() {
  const [position, setPosition] = useState<Location | null>(null);

  const handlePress = async () => {
    try {
      const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
      setPosition(response);
    } catch (error) {
      console.error('위치 정보를 가져오는 데 실패했어요:', error);
    }
  };

  return (
    <View>
      {position ? (
        <Text>
          위치: {position.coords.latitude}, {position.coords.longitude}
        </Text>
      ) : (
        <Text>위치 정보를 아직 가져오지 않았어요</Text>
      )}
      <Button title="현재 위치 정보 가져오기" onPress={handlePress} />
      <Button
        title="권한 확인하기"
        onPress={async () => {
          Alert.alert(await getCurrentLocation.getPermission());
        }}
      />
      <Button
        title="권한 요청하기"
        onPress={async () => {
          Alert.alert(await getCurrentLocation.openPermissionDialog());
        }}
      />
    </View>
  );
}

```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-location-once](https://github.com/toss/apps-in-toss-examples/tree/main/with-location-once) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/closeView.md
---

# 화면 닫기

## `closeView`

`closeView` 는 현재 화면을 닫는 함수에요. 예를 들어, "닫기" 버튼을 눌러서 서비스를 종료할 때 사용할 수 있어요.

## 시그니처

```typescript
function closeView(): Promise<void>;
```

### 반환 값

## 예제

### 닫기 버튼을 눌러 화면 닫기

```tsx
import { Button } from 'react-native';
import { closeView } from '@granite-js/react-native';

function CloseButton() {
 return <Button title="닫기" onPress={closeView} />;
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/setDeviceOrientation.md
---

# 화면 방향 설정하기

## `setDeviceOrientation`

`setDeviceOrientation` 함수는 기기의 화면 방향을 설정하는 기능을 제공해요.
이 기능은 특정 화면에서 가로 모드나 세로 모드를 강제로 지정해야 할 때 유용해요.

`type` 옵션을 통해 원하는 화면 방향을 지정할 수 있어요. 특히, 이 함수는 앱 전체에 영향을 미치므로
특정 화면에서만 사용하려면 화면을 벗어날 때 이전 상태로 복구하는 추가 작업이 필요해요.

예를 들어, 동영상 감상 화면에서는 가로 모드를 강제하고, 화면을 떠날 때 설정을 복구해서
다른 화면들의 방향 설정에 영향을 주지 않도록 할 수 있어요.

## 시그니처

```typescript
function setDeviceOrientation(options: {
  type: 'portrait' | 'landscape';
}): Promise<void>;
```

### 파라미터

'portrait' | 'landscape' 중 하나를 선택할 수 있어요.

### 반환 값

## 예제

### 화면 방향 설정하기

::: code-group

```js [js]
import { setDeviceOrientation } from '@apps-in-toss/web-framework';

setDeviceOrientation({ type: 'landscape' });
```

```tsx [React]
import { setDeviceOrientation } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function SetDeviceOrientationButton() {
  function handleClick() {
    setDeviceOrientation({ type: 'landscape' });
  }

  return <Button onClick={handleClick}>가로 모드로 변경</Button>;
}
```

```tsx [React Native]
import { setDeviceOrientation } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function SetDeviceOrientationButton() {
  function handlePress() {
    setDeviceOrientation({ type: 'landscape' });
  }

  return <Button onPress={handlePress}>가로 모드로 변경</Button>;
}
```

:::

### 화면 방향 복구하기

특정 화면을 벗어날 때 이전 상태로 복구하려면 다음과 같이 `useEffect`를 사용하세요.

::: code-group

```js [js]
import { setDeviceOrientation } from '@apps-in-toss/web-framework';

document.addEventListener('DOMContentLoaded', () => {
  setDeviceOrientation({ type: 'landscape' });

  window.addEventListener('pagehide', () => {
    setDeviceOrientation({ type: 'portrait' });
  });
});
```

```tsx [React]
import { setDeviceOrientation } from '@apps-in-toss/web-framework';
import { Text } from '@toss/tds-mobile';
import { useEffect } from 'react';

function VideoScreen() {
  useEffect(() => {
    setDeviceOrientation({ type: 'landscape' });

    return () => {
      setDeviceOrientation({ type: 'portrait' }); // 설정을 이전 상태로 복구해요.
    };
  }, []);

  return <Text>동영상을 감상하는 화면</Text>;
}
```

```tsx [React Native]
import { setDeviceOrientation } from '@apps-in-toss/framework';
import { Text } from '@toss/tds-react-native';
import { useEffect } from 'react';

function VideoScreen() {
  useEffect(() => {
    setDeviceOrientation({ type: 'landscape' });

    return () => {
      setDeviceOrientation({ type: 'portrait' }); // 설정을 이전 상태로 복구해요.
    };
  }, []);

  return <Text>동영상을 감상하는 화면</Text>;
}
```

:::

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-game](https://github.com/toss/apps-in-toss-examples/tree/main/with-game) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/useVisibility.md
---

# 화면 보임 여부 확인하기

## `useVisibility`

`useVisibility` 훅을 사용하면 화면이 현재 사용자에게 보이는지 여부를 알 수 있어요. 사용자가 화면을 보고 있을 때만 특정 작업을 실행하거나, 로그를 남길 수 있어요.

앱의 화면이 현재 사용자에게 보인다면 `true`를 반환하고, 보이지 않는다면 `false`를 반환해요. 단, 시스템 공유하기 모달([share](/bedrock/reference/framework/공유/share))을 열고 닫을 때는 화면이 보이는 상태가 바뀌지 않아요.

사용 예시는 다음과 같아요.

* 다른 앱으로 전환하거나 홈 버튼을 누르면 `false` 를 반환해요.
* 다시 토스 앱으로 돌아오거나 화면이 보이면 `true` 를 반환해요.
* 토스 앱 내 다른 서비스로 이동하면 `false` 를 반환해요.

## 시그니처

```typescript
function useVisibility(): boolean;
```

### 반환 값

## 예제

### 화면이 보이는 상태를 확인하는 예제

아래 코드는 화면이 사용자에게 보였을 때 `visibility` 값을 `console.log`로 확인하는 예시예요.

* 홈 화면으로 이동하면 `false`가 기록되고, 다시 돌아오면 `true`가 기록돼요.
* 외부 링크(`https://toss.im`)로 이동하면 `false`가 기록되고, 다시 돌아오면 `true`가 기록돼요.

```tsx{1,6,8-12}
import { useVisibility } from '@granite-js/react-native';
import { useEffect } from 'react';
import { Button, Linking } from 'react-native';

export default function VisibilityPage() {
  const visibility = useVisibility();

  useEffect(() => {
    console.log({
      visibility,
    });
  }, [visibility]);

  return (
    <Button
      onPress={() => {
        Linking.openURL('https://toss.im');
      }}
      title="https://toss.im 이동"
    />
  );
}

/**
 * 출력 예시:
 * { "visibility": false }
 * { "visibility": true }
 * { "visibility": false }
 * { "visibility": true }
 */
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/useWaitForReturnNavigator.md
---

# 화면 복귀 후 코드 실행하기

## `useWaitForReturnNavigator`

`useWaitForReturnNavigator` 는 화면 전환을 하고 돌아왔을 때 다음 코드를 동기적으로 실행할 수 있도록 도와주는 Hook 이에요.
화면 이동은 [@react-navigation/native `useNavigation`의 `navigate`](https://reactnavigation.org/docs/6.x/navigation-prop#navigate)를 사용해요.

예를 들어, 사용자가 다른 화면으로 이동했다가 돌아왔다는 로그를 남기고 싶을 때 사용해요.

## 시그니처

```typescript
function useWaitForReturnNavigator<T extends Record<string, object | undefined>>(): <RouteName extends keyof T>(route: RouteName, params?: T[RouteName]) => Promise<void>;
```

## 예제

### 화면 이동 후 돌아왔을 때 코드가 실행되는 예제

**"이동하기"** 버튼을 누르면 다른 화면으로 이동하고, 돌아왔을 때 로그가 남겨져요.

```tsx
import { Button } from 'react-native';
import { useWaitForReturnNavigator } from '@apps-in-toss/framework';

function UseWaitForReturnNavigator() {
  const navigate = useWaitForReturnNavigator();

  return (
    <Button
      title="이동하기"
      onPress={async () => {
        console.log(1);
        await navigate('/examples/use-visibility');
        // 화면에 돌아오면 이 코드가 실행됩니다.
        console.log(2);
      }}
    />
  );
}
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  이동/routing.md
---

# 화면 이동

Granite 애플리케이션에서는 새로운 화면으로 이동하거나, 화면 기록을 제어하는 등의 라우팅 작업을 쉽게 처리할 수 있어요.\
이 기능은 [React Navigation](https://reactnavigation.org/)을 기반으로 동작해요.

:::info WebView 라우팅
WebView에서는 **프로젝트에 설정한 웹 라우터**(예: React Router) 규칙을 그대로 따라요.
:::

## 라우팅 예제 구조

라우팅 예제는 총 3개의 페이지(`page-a`, `page-b`, `page-c`)로 구성되어 있어요.

```
root
├─── pages
│    ├─── page-a.tsx
│    ├─── page-b.tsx
│    └─── page-c.tsx
└─── src
     └─── ...
```

::: details `page-a.tsx` 소스코드

```tsx
// page-a.tsx
import { StyleSheet, View, Text, Pressable } from "react-native";
import { createRoute, useNavigation } from '@granite-js/react-native';

export const Route = createRoute("/page-a", {
  validateParams: (params) => params,
  component: PageA,
});

function PageA() {
  const navigation = useNavigation();

  const handlePress = () => {
    navigation.navigate("/page-b");
  };

  return (
    <View style={[styles.container, { backgroundColor: "#3182f6" }]}>
      <Text style={styles.text}>Page A</Text>
      <Pressable onPress={handlePress}>
        <Text style={styles.buttonLabel}>B 페이지로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

:::

::: details `page-b.tsx` 소스코드

```tsx
// page-b.tsx
import { createRoute, useNavigation } from '@granite-js/react-native';
import { StyleSheet, View, Text, Pressable } from "react-native";

export const Route = createRoute("/page-b", {
  validateParams: (params) => params,
  component: PageB,
});

function PageB() {
  const navigation = useNavigation();

  // 이전 화면으로 돌아가는 함수예요.
  const handlePressBackButton = () => {
    if (navigation.canGoBack()) {
      navigation.goBack();
    } else {
      console.warn("이전 화면으로 이동할 수 없습니다.");
    }
  };

  const handlePressNextButton = () => {
    navigation.navigate("/page-c", {
      message: "안녕!",
      date: new Date().getTime(),
    });
  };

  return (
    <View style={[styles.container, { backgroundColor: "#fe9800" }]}>
      <Text style={styles.text}>Page B</Text>
      <Pressable onPress={handlePressBackButton}>
        <Text style={styles.buttonLabel}>이전으로 이동하기</Text>
      </Pressable>
      <Pressable onPress={handlePressNextButton}>
        <Text style={styles.buttonLabel}>C 페이지로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

:::

::: details `page-c.tsx` 소스코드

```tsx
// page-c.tsx
import { useNavigation, createRoute } from '@granite-js/react-native';
import { CommonActions } from "@granite-js/native/@react-navigation/native";
import { StyleSheet, View, Text, Pressable } from "react-native";

export const Route = createRoute("/page-c", {
  validateParams: (params) => params as { message: string; date: number },
  component: PageC,
});

function PageC() {
  const navigation = useNavigation();
  const params = Route.useParams();

  const handlePressHomeButton = () => {
    navigation.dispatch((state) => {
      return CommonActions.reset({
        ...state,
        index: 0,
        routes: state.routes.filter((route) => route.name === "/page-a"),
      });
    });
  };

  return (
    <View style={[styles.container, { backgroundColor: "#f04452" }]}>
      <Text style={styles.text}>{params.message}</Text>
      <Text style={styles.text}>{params.date}</Text>
      <View style={styles.line} />
      <Text style={styles.text}>Page C</Text>
      <Pressable onPress={handlePressHomeButton}>
        <Text style={styles.buttonLabel}>처음으로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

:::

## 페이지 A: 화면 이동하기

[`useNavigation`](https://reactnavigation.org/docs/use-navigation)은 화면 간 이동을 처리할 때 사용해요. [`navigate`](https://reactnavigation.org/docs/navigation-actions/#navigate) 메서드로 이동할 화면의 경로와 필요한 데이터를 함께 전달할 수 있어요.

```tsx
// page-a.tsx
import { createRoute, useNavigation } from '@granite-js/react-native'; // [!code highlight]
import { StyleSheet, View, Text, Pressable } from "react-native";

export const Route = createRoute("/page-a", {
  validateParams: (params) => params,
  component: PageA,
});

function PageA() {
  const navigation = useNavigation(); // [!code highlight]
  // [!code highlight:4]
  const handlePress = () => {
    navigation.navigate("/page-b");
  };

  return (
    <View style={[styles.container, { backgroundColor: "#3182f6" }]}>
      <Text style={styles.text}>Page A</Text>
      <Pressable onPress={handlePress}>
        <Text style={styles.buttonLabel}>B 페이지로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

### 주요 포인트

* `useNavigation` 훅을 사용해 `navigation` 객체를 가져와요.
* `navigation.navigate('/page-b')`를 호출하면 'B' 페이지로 이동해요.

## 페이지 B: 이전 화면으로 돌아가기

[`goBack`](https://reactnavigation.org/docs/navigation-actions/#goback) 메서드를 사용하면 이전 화면으로 돌아갈 수 있어요. 하지만 이전 화면 기록이 없는 경우에는 에러가 발생할 수 있으니, [`canGoBack`](https://reactnavigation.org/docs/navigation-prop/#cangoback)으로 먼저 확인해야 해요.

```tsx
// page-b.tsx
import { createRoute, useNavigation } from '@granite-js/react-native'; // [!code highlight]
import { StyleSheet, View, Text, Pressable } from "react-native";

export const Route = createRoute("/page-b", {
  validateParams: (params) => params,
  component: PageB,
});

function PageB() {
  const navigation = useNavigation(); // [!code highlight]

  // 이전 화면으로 돌아가는 함수예요. // [!code highlight:8]
  const handlePressBackButton = () => {
    if (navigation.canGoBack()) {
      navigation.goBack();
    } else {
      console.warn("이전 화면으로 이동할 수 없습니다.");
    }
  };

  const handlePressNextButton = () => {
    navigation.navigate("/page-c", {
      message: "안녕!",
      date: new Date().getTime(),
    });
  };

  return (
    <View style={[styles.container, { backgroundColor: "#fe9800" }]}>
      <Text style={styles.text}>Page B</Text>
      <Pressable onPress={handlePressBackButton}>
        <Text style={styles.buttonLabel}>이전으로 이동하기</Text>
      </Pressable>
      <Pressable onPress={handlePressNextButton}>
        <Text style={styles.buttonLabel}>C 페이지로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

### 주요 포인트

* `canGoBack()`으로 이전 화면이 있는지 확인하고, 있으면 `goBack()`을 호출해요.
* `navigate('/page-c', { message: '안녕!', date: new Date().getTime() })`로 데이터를 전달하면서 'C' 페이지로 이동해요.

## 페이지 C: 전달받은 데이터 사용하기

`Route.useParams` 훅은 다른 화면에서 전달된 데이터를 가져올 때 사용해요.

이때, `createRoute.validateParams` 옵션을 설정하면 전달된 데이터를 타입 검증(Type-Safe)하면서 접근할 수 있어요. 이를 통해 잘못된 데이터 형식으로 인한 에러를 방지할 수 있어요.

```tsx
// page-c.tsx
import { createRoute, useNavigation } from '@granite-js/react-native'; // [!code highlight]
import { CommonActions } from "@granite-js/native/@react-navigation/native";
import { StyleSheet, View, Text, Pressable } from "react-native";

// [!code highlight:5]
export const Route = createRoute("/page-c", {
  validateParams: (params) => params as { message: string; date: number },
  component: PageC,
});

function PageC() {
  const navigation = useNavigation();
  const params = Route.useParams(); // [!code highlight:7]
  // 또는 아래와 같이 사용할 수 있어요.
  // import { useParams } from '@granite-js/react-native';
  //
  // const params = useParams({
  //   from: '/page-b',
  // });

  const handlePressHomeButton = () => {
    navigation.dispatch((state) => {
      return CommonActions.reset({
        ...state,
        index: 0,
        routes: state.routes.filter((route) => route.name === "/page-a"),
      });
    });
  };

  return (
    <View style={[styles.container, { backgroundColor: "#f04452" }]}>
      <Text style={styles.text}>{params.message}</Text> // [!code highlight]
      <Text style={styles.text}>{params.date}</Text> // [!code highlight]
      <View style={styles.line} />
      <Text style={styles.text}>Page C</Text>
      <Pressable onPress={handlePressHomeButton}>
        <Text style={styles.buttonLabel}>처음으로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

### 주요 포인트

* `Route.useParams` 훅을 사용하면 URL에서 전달된 데이터(매개변수)에 접근할 수 있어요.
* `createRoute.validateParams` 옵션을 설정하면 데이터 타입을 검증하면서(Type-Safe) 안전하게 사용할 수 있어요.

## 화면 파라미터 타입 정의하기

페이지마다 아래와 같은 Route 컴포넌트를 정의해요.
여기서 `validateParams` 옵션은 해당 화면에서 받을 파라미터의 타입을 정의해요.

```tsx
export const Route = createRoute("/page-c", {
  validateParams: (params) => params as { message: string; date: number }, // [!code highlight]
  component: PageC,
});
```

위 코드에서 `validateParams`는 `message`와 `date`라는 두 필드를 포함한 매개변수를 타입으로 정의해요.

이를 통해 다른 코드에서 `useNavigate`나 `useParams`를 사용할 때, 타입 검사를 통해 필요한 경로와 전달해야 할 데이터를 명확히 알 수 있어요. 이렇게 하면 코드의 안전성과 가독성이 높아져요.

***

### 자동 타입 정의 생성

개발 모드에서는 `pages/` 디렉토리에 파일이 추가되면 자동으로 타입 정의가 생성되므로 별도의 명령어를 실행하지 않아도 돼요.

### 생성된 파일 예시

자동으로 생성된 파일은 다음과 같아요. 이 파일은 자동 생성되므로 수동으로 수정할 필요가 없어요.

```tsx
// src/router.gen.ts

/* eslint-disable */
// This file is auto-generated by @granite-js/react-native. DO NOT EDIT.
import { Route as _AboutRoute } from '../pages/about';
import { Route as _IndexRoute } from '../pages/';

declare module '@granite-js/react-native' {
  interface RegisterScreen {
    '/about': ReturnType<typeof _AboutRoute.useParams>;
    '/': ReturnType<typeof _IndexRoute.useParams>;
  }
}
```

### 주요 포인트

* 각 화면에서 받을 파라미터의 타입을 `createRoute.validateParams` 옵션으로 정의해두면, `navigate`와 `params` 사용 시 타입 검사를 받을 수 있어 더 안전하게 코드를 작성할 수 있어요.
* 개발 모드에서는 `pages/` 디렉토리에 파일이 추가되면 타입 정의가 자동으로 생성되기 때문에 별도의 명령어 실행이 필요하지 않아요.

이렇게 React Navigation을 사용하면 화면 간 이동을 쉽게 처리할 수 있고, 데이터를 전달하거나 기록을 조작하는 기능을 통해 다양한 UX를 구현할 수 있어요. 또한 타입스크립트와 함께 사용하면 안전하고 견고한 코드를 작성할 수 있답니다.

## 라우팅 상태 초기화하기

![navigate-state-1](/assets/navigate-flow.BhUTsx6V.png)

페이지 A → 페이지 B → 페이지 C 순서로 이동한 직후의 상태는 아래와 그림과 같이 같이 나타낼 수 있어요.

![navigate-state-1](/assets/navigate-state-1.CdMco613.png)

페이지 A, 페이지 B, 페이지 C가 순서대로 `routes` 기록에 남아 있고, `index` 값은 마지막으로 이동한 페이지 C의 위치인 2를 가리켜요.

`reset`을 사용하면 화면 이동 기록을 초기화할 수 있어요. 예를 들어, '페이지 A → B → C'로 이동한 후에 '페이지 A'로 돌아가면서 B와 C 기록을 삭제하고 싶다면, [`CommonActions.reset`](https://reactnavigation.org/docs/navigation-actions/#reset)을 사용해요.

```tsx
navigation.dispatch(
  CommonActions.reset({
    index: 0,
    routes: [{ name: "/page-a" }],
  })
);
```

![navigate-state-2](/assets/navigate-state-2.DrROcTxJ.png)

### 주요 포인트

* `CommonActions.reset`으로 특정 화면만 기록에 남기고 나머지 화면 기록을 삭제할 수 있어요.

## 레퍼런스

* [React Navigation 공식 문서](https://reactnavigation.org/)

***

::: tip 이전 버전 문서가 필요할 때
이전 버전의 문서는 [화면 이동하기](/development/routing-deprecated)에서 확인할 수 있어요.
:::

---

---
url: 'https://developers-apps-in-toss.toss.im/development/routing-deprecated.md'
description: Bedrock 애플리케이션의 화면 이동 및 라우팅 가이드 (Deprecated). 최신 문서는 Bedrock 레퍼런스를 참고하세요.
---

::: tip 최신 문서를 참고하세요
최신 버전의 문서는 [화면 이동하기](/bedrock/reference/framework/화면%20이동/routing)에서 확인할 수 있어요.
:::

# 화면 이동하기

Bedrock 애플리케이션에서 새로운 화면으로 이동하거나, 화면 기록(History)을 제어하는 등의 라우팅 작업을 쉽게 처리할 수 있어요.

아래 예제 코드를 통해 다양한 라우팅 기능을 설명할게요.

::: tip Bedrock은 [React Navigation](https://reactnavigation.org/)을 기반으로 동작해요

Bedrock의 화면 이동은 [React Navigation](https://reactnavigation.org/) 라이브러리를 기반으로 동작해요. 자세한 API는 해당 문서를 참고하세요.

:::

## 예제 코드

예제 코드는 총 3개의 페이지로 구성되어 있고, 구조는 아래와 같아요.

```
root
├─── pages
│    ├─── page-a.tsx
│    ├─── page-b.tsx
│    └─── page-c.tsx
└─── src
     └─── ...
```

::: details `page-a.tsx` 소스코드

```tsx
// page-a.tsx
import { useNavigation } from "@granite-js/react-native";
import { StyleSheet, View, Text, Pressable } from "react-native";

export default function PageA() {
  const navigation = useNavigation();

  const handlePress = () => {
    navigation.navigate("/page-b");
  };

  return (
    <View style={[styles.container, { backgroundColor: "#3182f6" }]}>
      <Text style={styles.text}>Page A</Text>
      <Pressable onPress={handlePress}>
        <Text style={styles.buttonLabel}>B 페이지로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

:::

::: details `page-b.tsx` 소스코드

```tsx
// page-b.tsx
import { useNavigation } from "@granite-js/react-native";
import { StyleSheet, View, Text, Pressable } from "react-native";

export default function PageB() {
  const navigation = useNavigation();

  // 이전 화면으로 돌아가는 함수예요.
  const handlePressBackButton = () => {
    if (navigation.canGoBack()) {
      navigation.goBack();
    } else {
      console.warn("이전 화면으로 이동할 수 없습니다.");
    }
  };

  const handlePressNextButton = () => {
    navigation.navigate("/page-c", {
      message: "안녕!",
      date: new Date().getTime(),
    });
  };

  return (
    <View style={[styles.container, { backgroundColor: "#fe9800" }]}>
      <Text style={styles.text}>Page B</Text>
      <Pressable onPress={handlePressBackButton}>
        <Text style={styles.buttonLabel}>이전으로 이동하기</Text>
      </Pressable>
      <Pressable onPress={handlePressNextButton}>
        <Text style={styles.buttonLabel}>C 페이지로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

:::

::: details `page-c.tsx` 소스코드

```tsx
// page-c.tsx
import {
  useNavigation,
  useRoute,
  CommonActions,
} from "@granite-js/native/@react-navigation/native";
import { StyleSheet, View, Text, Pressable } from "react-native";

export default function PageC() {
  const navigation = useNavigation();
  const route = useRoute();

  const handlePressHomeButton = () => {
    navigation.dispatch((state) => {
      return CommonActions.reset({
        ...state,
        index: 0,
        routes: state.routes.filter((route) => route.name === "/page-a"),
      });
    });
  };

  return (
    <View style={[styles.container, { backgroundColor: "#f04452" }]}>
      <Text style={styles.text}>{route.params?.message}</Text>
      <Text style={styles.text}>{route.params?.date}</Text>
      <View style={styles.line} />
      <Text style={styles.text}>Page C</Text>
      <Pressable onPress={handlePressHomeButton}>
        <Text style={styles.buttonLabel}>처음으로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

:::

## 페이지 A: 화면 이동하기

[`useNavigation`](https://reactnavigation.org/docs/use-navigation) 훅을 사용해서 다른 화면으로 이동할 수 있어요. [`navigate`](https://reactnavigation.org/docs/navigation-actions/#navigate) 메서드에 이동할 화면의 경로를 전달하면 됩니다.

```tsx
// page-a.tsx
import { useNavigation } from "@react-native-bedrock/native/@react-navigation/native"; // [!code focus] // [!code highlight]
import { StyleSheet, View, Text, Pressable } from "react-native";

export default function PageA() {
  const navigation = useNavigation();

  const handlePress = () => {
    // [!code focus:3] // [!code highlight:3]
    navigation.navigate("/page-b");
  };

  return (
    <View style={[styles.container, { backgroundColor: "#3182f6" }]}>
      <Text style={styles.text}>Page A</Text>
      <Pressable onPress={handlePress}>
        <Text style={styles.buttonLabel}>B 페이지로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

### 주요 포인트

* `useNavigation` 훅을 사용해 `navigation` 객체를 가져와요.
* `navigation.navigate('/page-b')`를 호출하면 'B' 페이지로 이동해요.

## 페이지 B: 이전 화면으로 돌아가기

[`goBack`](https://reactnavigation.org/docs/navigation-actions/#goback) 메서드를 사용하면 이전 화면으로 돌아갈 수 있어요. 하지만 이전 화면 기록이 없는 경우에는 에러가 발생할 수 있으니, [`canGoBack`](https://reactnavigation.org/docs/navigation-prop/#cangoback)으로 먼저 확인해야 해요.

```tsx
// page-b.tsx
import { useNavigation } from "@react-native-bedrock/native/@react-navigation/native"; // [!code focus] // [!code highlight]
import { StyleSheet, View, Text, Pressable } from "react-native";

export default function PageB() {
  const navigation = useNavigation(); // [!code focus] // [!code highlight]

  // 이전 화면으로 돌아가는 함수예요.  // [!code focus:8] // [!code highlight:8]
  const handlePressBackButton = () => {
    if (navigation.canGoBack()) {
      navigation.goBack();
    } else {
      console.warn("이전 화면으로 이동할 수 없습니다.");
    }
  };

  const handlePressNextButton = () => {
    navigation.navigate("/page-c", {
      message: "안녕!",
      date: new Date().getTime(),
    });
  };

  return (
    <View style={[styles.container, { backgroundColor: "#fe9800" }]}>
      <Text style={styles.text}>Page B</Text>
      <Pressable onPress={handlePressBackButton}>
        <Text style={styles.buttonLabel}>이전으로 이동하기</Text>
      </Pressable>
      <Pressable onPress={handlePressNextButton}>
        <Text style={styles.buttonLabel}>C 페이지로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

### 주요 포인트

* `canGoBack()`으로 이전 화면이 있는지 확인하고, 있으면 `goBack()`을 호출해요.
* `navigate('/page-c', { message: '안녕!', date: new Date().getTime() })`로 데이터를 전달하면서 'C' 페이지로 이동해요.

## 페이지 C: 전달받은 데이터 사용하기

[`useRoute`](https://reactnavigation.org/docs/use-route) 훅을 사용하면 다른 화면에서 전달된 데이터를 가져올 수 있어요. 전달된 데이터는 `route.params`를 통해 접근할 수 있어요.

```tsx
import {
  useNavigation,
  useRoute,
  CommonActions,
} from "@granite-js/native/@react-navigation/native"; // [!code focus] // [!code highlight]
import { StyleSheet, View, Text, Pressable } from "react-native";

export default function PageC() {
  const navigation = useNavigation();
  const route = useRoute(); // [!code focus] // [!code highlight]

  const handlePressHomeButton = () => {
    navigation.dispatch((state) => {
      return CommonActions.reset({
        ...state,
        index: 0,
        routes: state.routes.filter((route) => route.name === "/page-a"),
      });
    });
  };

  return (
    <View style={[styles.container, { backgroundColor: "#f04452" }]}>
      <Text style={styles.text}>{route.params?.message}</Text> // [!code focus]
      // [!code highlight]
      <Text style={styles.text}>{route.params?.date}</Text> // [!code focus] // [!code
      highlight]
      <View style={styles.line} />
      <Text style={styles.text}>Page C</Text>
      <Pressable onPress={handlePressHomeButton}>
        <Text style={styles.buttonLabel}>처음으로 이동하기</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    gap: 16,
    padding: 16,
  },
  text: {
    color: "white",
    fontSize: 24,
  },
  buttonLabel: {
    color: "white",
  },
});
```

### 주요 포인트

* `useRoute` 훅을 사용해 전달받은 데이터에 접근할 수 있어요.

## 라우팅 상태 초기화하기

![navigate-state-1](/assets/navigate-flow.BhUTsx6V.png)

페이지 A → 페이지 B → 페이지 C 순서로 이동한 직후의 상태는 아래와 그림과 같이 같이 나타낼 수 있어요.

![navigate-state-1](/assets/navigate-state-1.CdMco613.png)

페이지 A, 페이지 B, 페이지 C가 순서대로 `routes` 기록에 남아 있고, `index` 값은 마지막으로 이동한 페이지 C의 위치인 2를 가리켜요.

`reset`을 사용하면 화면 이동 기록을 초기화할 수 있어요. 예를 들어, '페이지 A → B → C'로 이동한 후에 '페이지 A'로 돌아가면서 B와 C 기록을 삭제하고 싶다면, [`CommonActions.reset`](https://reactnavigation.org/docs/navigation-actions/#reset)을 사용해요.

```tsx
navigation.dispatch(
  CommonActions.reset({
    index: 0,
    routes: [{ name: "/page-a" }],
  })
);
```

![navigate-state-2](/assets/navigate-state-2.DrROcTxJ.png)

### 주요 포인트

* `CommonActions.reset`으로 특정 화면만 기록에 남기고 나머지 화면 기록을 삭제할 수 있어요.

## 타입 정의하기

프로젝트에 타입스크립트를 적용해서 화면 경로와 파라미터를 타입으로 정의하면, 더 안전하게 코드를 작성할 수 있어요.

```tsx
// src/navigation.d.ts
import type { RouteProp } from "@react-native-bedrock/native/@react-navigation/native";
import type { NativeStackNavigationProp } from "@react-native-bedrock/native/@react-navigation/native-stack";

// 각 화면 경로와 해당 화면에서 받을 파라미터 타입을 정의해요.
type ParamList = {
  "/page-a": undefined; // '페이지 A'는 파라미터가 없어요.
  "/page-b": undefined; // '페이지 B'는 파라미터가 없어요.
  "/page-c": { message: string; date: number }; // '페이지 C'가 받는 파라미터의 타입
};

declare global {
  namespace ReactNavigation {
    interface RootParamList extends ParamList {}
  }
}

declare module "@react-native-bedrock/native/@react-navigation/native-stack" {
  export function useNavigation<T = NativeStackNavigationProp<ParamList>>(): T;
  export function useRoute<T = RouteProp<ParamList>>(): T;
}
```

### 주요 포인트

* 각 화면에서 받을 파라미터의 타입을 정의해두면, `navigate`와 `route` 사용 시 타입 검사를 받을 수 있어 더 안전하게 코드를 작성할 수 있어요.

***

이렇게 React Navigation을 사용하면 화면 간 이동을 쉽게 처리할 수 있고, 데이터를 전달하거나 기록을 조작하는 기능을 통해 다양한 UX를 구현할 수 있어요. 또한 타입스크립트와 함께 사용하면 안전하고 견고한 코드를 작성할 수 있답니다.

## 레퍼런스

* [React Navigation 공식 문서](https://reactnavigation.org/)

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/setSecureScreen.md
---

# 화면 캡처 차단하기

## `setSecureScreen`

`setSecureScreen` 함수는 네이티브 수준에서 화면 캡처를 차단하거나 허용할 수 있어요. 사용자가 화면을 캡처하려고 시도할 때 이를 방지해 보안을 강화할 수 있죠. 이 설정은 화면별로 동작하도록 구현할 수 있어 유연하게 사용할 수 있어요.

민감한 정보를 다루는 애플리케이션에서는 화면 캡처를 차단하거나 필요에 따라 허용하는 기능이 중요해요. 이 기능은 특히 금융 앱, 의료 데이터 앱 등 민감한 정보를 보호해야 할 때 유용해요.

예를 들어 계좌 잔고, 거래 내역 같이 민감한 데이터를 표시할 때 활용할 수 있어요.

## 시그니처

```typescript
function setSecureScreen(options: {
    enabled: boolean;
}): Promise<{
    enabled: boolean;
}>;
```

### 파라미터

### 반환 값

## 구현 가이드

### 캡처 차단과 해제 설정하기

아래 코드는 화면이 표시될 때 캡처를 차단하고, 화면을 벗어날 때 차단을 해제해요.

```tsx
import { useEffect } from "react";
import { View, Text, StyleSheet } from "react-native";
import { createRoute } from '@granite-js/react-native';
import { setSecureScreen } from '@apps-in-toss/framework';

export const Route = createRoute("/secure-screen", {
  component: SecureScreen,
});

function SecureScreen() {
  useEffect(() => {
    // 화면에 진입할 때 캡처 차단 활성화
    setSecureScreen({ enabled: true }); // [!code highlight]
    console.log("화면 캡처 차단 활성화");

    return () => {
      // 화면을 벗어날 때 캡처 차단 해제
      setSecureScreen({ enabled: false }); // [!code highlight]
      console.log("화면 캡처 차단 해제");
    };
  }, []);

  return (
    <View style={styles.container}>
      <Text style={styles.text}>이 화면은 캡처가 차단되어 있습니다.</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    backgroundColor: "#f9f9f9",
  },
  text: {
    fontSize: 18,
    fontWeight: "bold",
    color: "#333",
  },
});
```

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/화면
  제어/setScreenAwakeMode.md
---

# 화면 항상 켜짐 설정하기

## `setScreenAwakeMode`

`setScreenAwakeMode` 함수는 화면이 항상 켜져 있도록 설정하거나 해제하는 기능을 제공해요.
이 기능은 웹툰, 동영상, 문서 읽기 등 화면을 지속해서 켜두어야 하는 상황에서 유용해요.

`enabled` 옵션을 `true`로 설정하면 화면이 꺼지지 않게 유지하고,  `false`로 설정하면 기본 화면 보호기 시간에 따라 화면이 꺼져요.  특히, 이 함수는 앱 전체에 영향을 미치므로 특정 화면에서만 사용하려면 화면을 벗어날 때 이전 상태로 복구하는 추가 작업이 필요해요.

예를 들어, 미디어 콘텐츠 감상 화면에서는 항상 켜짐 모드를 활성화하고, 화면을 떠날 때 설정을 복구해서 불필요한 배터리 소모를 방지할 수 있어요.

다만, 앱에서 벗어나는 상황에서는 항상 켜짐 모드가 비활성화될 수 있으니 주의해야 해요.

## 시그니처

```typescript
function setScreenAwakeMode(options: {
    enabled: boolean;
}): Promise<{
    enabled: boolean;
}>;
```

### 파라미터

`true`로 설정하면 화면이 항상 켜지고, `false`로 설정하면 화면 보호기 시간에 따라 꺼져요.

### 반환 값

## 예제

### 화면 항상 켜짐 모드 설정하기

:::code-group

```tsx[React]
import { Button } from 'react-native';
import { setScreenAwakeMode } from '@apps-in-toss/web-framework';

function SetScreenAwakeMode() {
  return (
    <Button
      title="화면 항상 켜기"
      onPress={() => {
        setScreenAwakeMode({ enabled: true });
      }}
    />
  );
}
```

```tsx[React Native]
import { Button } from 'react-native';
import { setScreenAwakeMode } from '@apps-in-toss/framework';

function SetScreenAwakeMode() {
  return (
    <Button
      title="화면 항상 켜기"
      onPress={() => {
        setScreenAwakeMode({ enabled: true });
      }}
    />
  );
}
```

:::

### 화면 항상 켜짐 모드 복구하기

특정 화면을 벗어날 때 이전 상태로 복구하려면 다음과 같이 `useEffect`를 사용하세요.

:::code-group

```tsx[React]
import { useEffect } from 'react';
import { setScreenAwakeMode } from '@apps-in-toss/web-framework';

function MediaScreen() {
  useEffect(() => {
    setScreenAwakeMode({ enabled: true });

    return () => {
      setScreenAwakeMode({ enabled: false }); // 설정을 이전 상태로 복구해요.
    };
  }, []);

  return <div>미디어 콘텐츠를 감상하는 화면</div>;
}

export default MediaScreen;
```

```tsx[React Native]
import { useEffect } from 'react';
import { Text } from 'react-native';
import { setScreenAwakeMode } from '@apps-in-toss/framework';

function MediaScreen() {
  useEffect(() => {
    setScreenAwakeMode({ enabled: true });

    return () => {
      setScreenAwakeMode({ enabled: false }); // 설정을 이전 상태로 복구해요.
    };
  }, []);

  return <Text>미디어 콘텐츠를 감상하는 화면</Text>;
}

export default MediaScreen;
```

:::

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/환경
  변수/env.md
---

# 환경 변수 설정 (React Native)

`plugin-env`는 프로젝트에 환경 변수를 주입해서\
`import.meta.env` 형태로 쉽게 접근할 수 있도록 도와주는 플러그인이에요.

이 플러그인은 **React Native 환경에서만 사용 가능**하며,\
`@granite-js/react-native` 기반의 설정 파일(`granite.config.ts`)에서 적용할 수 있어요.

## 설치하기

패키지 매니저에 따라 아래 명령어 중 하나를 실행해 설치할 수 있어요.

```bash
# npm을 사용하는 경우
npm install '@granite-js/plugin-env';

# yarn을 사용하는 경우
yarn add '@granite-js/plugin-env';

# pnpm을 사용하는 경우
pnpm add '@granite-js/plugin-env';
```

## 사용 예시

아래는 `plugin-env`를 사용해 React Native 프로젝트에서 환경 변수를 등록하고 사용하는 예제예요.

```tsx [React Native]
// granite config
import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';
import { env } from '@granite-js/plugin-env';

export default defineConfig({
  scheme: 'intoss',
  appName: 'my-granite-app',
  plugins: [
    appsInToss({
      brand: {
        displayName: 'my-granite-app', // 화면에 노출될 앱의 한글 이름으로 바꿔주세요.
        primaryColor: '#3182F6', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
        icon: '', // 화면에 노출될 앱의 아이콘 이미지 주소로 바꿔주세요.
      },
      permissions: [],
    }),
    env({ MY_ENV_VAR: 'Hello, World!' }),
  ],
});

// service
import.meta.env.MY_ENV_VAR; // 'Hello, World!'
```

## 참고사항

* 환경 변수는 런타임에서 변경되지 않고, 빌드 시점에 주입돼요.
* 여러 환경(`staging`, `production`)을 구분해야 한다면
  `env()`에 환경별 객체를 전달하거나 `.env` 파일을 병행해서 사용할 수 있어요.

---

---
url: >-
  https://developers-apps-in-toss.toss.im/bedrock/reference/framework/위치
  정보/useGeolocation.md
---

# 훅으로 위치 사용하기

## `useGeolocation`

`useGeolocation` 는 디바이스의 위치 정보를 반환하는 훅이에요. 위치가 변경되면 값도 변경돼요.
GPS 정보를 활용해 현재 위치를 감지하고, 사용자의 이동에 따라 자동으로 업데이트돼요.
예를 들어, 지도 기반 서비스에서 사용자의 현재 위치를 표시하거나, 배달 앱에서 실시간 이동 경로를 추적할 때 활용할 수 있어요.
위치 정보의 정확도와 업데이트 주기를 조정할 수 있어서 배터리 소모를 최소화하면서도 필요한 수준의 정확도를 유지할 수 있어요.

## 시그니처

```typescript
function useGeolocation({ accuracy, distanceInterval, timeInterval }: UseGeolocationOptions): Location | null;
```

### 파라미터

### 반환 값

## 예제

### 위치 정보 변경 감지하기

```tsx
import React, { useState, useCallback } from 'react';
import { View, Text } from 'react-native';
import { useGeolocation, Accuracy } from '@apps-in-toss/framework';

// 위치 정보 변경 감지하기
function LocationWatcher() {
  const location = useGeolocation({
    accuracy: Accuracy.Balanced,
    distanceInterval: 10,
    timeInterval: 1000,
  });

  if (location == null) {
    return <Text>위치 정보를 가져오는 중이에요...</Text>;
  }

  return (
    <View>
      <Text>위치 정보: {location.latitude}, {location.longitude}</Text>
    </View>
  );
}
```

### 예제 앱 체험하기

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-location-tracking](https://github.com/toss/apps-in-toss-examples/tree/main/with-location-tracking) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.