# Nitro Cookies > React Native의 native HTTP 쿠키를 관리하세요. iOS, Android, tvOS에서 TypeScript로 sync·async API를 사용합니다. Nitro Cookies 1.3.0 기준 문서입니다. List API, scope를 지정하는 삭제 API, error normalization은 1.3.0부터 지원합니다. 이전 버전을 사용 중이라면 설치 문서와 릴리스 이력을 확인하세요. --- 원문: [설치](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/installation.md) # 설치 Nitro Cookies와 native runtime을 설치한 뒤 React Native 앱을 다시 빌드하세요. 이 가이드는 iOS 또는 Android 빌드가 가능한 기존 React Native 프로젝트를 기준으로 설명합니다. ## 문서 버전 확인 이 문서는 Nitro Cookies **1.3.0**을 기준으로 설명합니다. List API, scope를 지정하는 삭제 API, error normalization, runtime `CookieErrorCode` export는 1.3.0부터 지원합니다. 1.2.1 이하를 사용 중이라면 1.3.0으로 업데이트하고 native 앱을 다시 빌드하세요. Apple request header의 URL 매칭, tvOS 지원, Android WebView 오류 처리 변경은 [1.3.0 릴리스 노트](https://github.com/l2hyunwoo/react-native-nitro-cookies/releases/tag/v1.3.0)에서 확인하세요. ## 패키지 설치 ```sh [npm] npm install react-native-nitro-cookies react-native-nitro-modules ``` ```sh [yarn] yarn add react-native-nitro-cookies react-native-nitro-modules ``` ```sh [pnpm] pnpm add react-native-nitro-cookies react-native-nitro-modules ``` Nitro Cookies 1.3.0에는 `react-native-nitro-modules >=0.35.0 <1.0.0`이 필요합니다. 설치한 Nitro runtime과 호환되는 React Native 버전을 사용하세요. iOS deployment target은 React Native 설정을 따릅니다. Android 라이브러리의 기본 최소 지원 버전은 API 24이며, 앱 설정에 따라 더 높은 버전이 필요할 수 있습니다. ## Native 앱 다시 빌드 iOS에서는 앱의 `ios/` 디렉터리에서 Pod를 설치하세요. ```sh bundle exec pod install ``` Bundler를 사용하지 않는 프로젝트라면 `pod install`을 실행하세요. 이어서 앱을 다시 빌드하고 실행하세요. Metro에서 앱을 reload하는 것만으로는 새 native module을 사용할 수 없습니다. Android는 autolinking을 사용합니다. 패키지를 설치한 뒤 Android 앱도 다시 빌드하고 실행하세요. ## Expo 프로젝트 두 native 패키지를 포함한 development build를 사용하세요. 설치·실행·재빌드 절차는 [Expo development build](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/expo-development-build.md)를 참고하세요. Expo Go에는 이 모듈이 포함되어 있지 않습니다. Native dependency가 바뀌면 development client를 다시 빌드해야 합니다. ## 소스에서 1.3.0 예제 실행 1.3.0 API를 직접 확인하려면 저장소의 예제 앱을 사용하세요. ```sh git clone https://github.com/l2hyunwoo/react-native-nitro-cookies.git cd react-native-nitro-cookies git checkout v1.3.0 corepack enable yarn install --immutable yarn nitrogen ``` 예제 앱의 native 빌드 설정을 마친 뒤 실행하세요. 위 명령은 기여자가 소스를 직접 확인할 때 사용합니다. npm 패키지 설치용 명령은 아닙니다. 설치를 마쳤다면 [첫 쿠키를 저장하고 조회](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/first-cookie.md)해 보세요. 저장소에 설정한 dependency 조합은 [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md#repository-configurations)에서 확인하세요. 설치나 쿠키 작업이 실패하면 [트러블슈팅](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/troubleshooting.md)을 참고하세요. --- 원문: [Expo development build](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/expo-development-build.md) # Expo development build Nitro Cookies와 `react-native-nitro-modules`를 포함한 development build를 사용하세요. Expo Go에는 두 native module이 포함되어 있지 않습니다. JavaScript 패키지를 설치하거나 Metro를 reload해도 Expo Go에 native code를 추가할 수 없습니다. 이 가이드는 Expo SDK 56, React Native 0.85.3, Nitro Modules 0.35.9를 사용합니다. 같은 구성을 재현할 수 있도록 blank TypeScript template의 버전을 고정합니다. 아래 설치 명령은 Nitro Cookies 1.3.0을 사용합니다. API 지원 버전은 [설치 문서](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/installation.md)에서 확인하세요. ## 앱 생성 Node.js 20.19 이상과 대상 플랫폼의 native build 도구를 설치하세요. iOS 로컬 빌드에는 macOS, Xcode 26.4 이상, CocoaPods가 필요합니다. Android 로컬 빌드에는 Android SDK, emulator 또는 기기, 호환되는 JDK가 필요합니다. 아래 검증에는 JDK 17을 사용합니다. 플랫폼 도구 설치는 [Expo 환경 설정](https://docs.expo.dev/get-started/set-up-your-environment/)을 참고하세요. ```sh npx create-expo@4.0.4 cookie-check \ --template expo-template-blank-typescript@56.0.37 --yes --no-install cd cookie-check npm install npx expo install expo-dev-client@56.0.27 npm install --save-exact react-native-nitro-cookies@1.3.0 \ react-native-nitro-modules@0.35.9 ``` 이 구성에는 Nitro Cookies용 config plugin이나 native module 수동 등록이 필요하지 않습니다. Native 패키지는 autolinking을 사용합니다. 설치된 dependency 버전을 유지하려면 생성된 lockfile을 보관하세요. ## Native 프로젝트 생성과 빌드 SDK 56 구성을 재현하려면 native template 버전도 고정하세요. ```sh curl -fsSL https://registry.npmjs.org/expo-template-bare-minimum/-/expo-template-bare-minimum-56.0.37.tgz \ -o expo-template-bare-minimum-56.0.37.tgz npx expo prebuild --template ./expo-template-bare-minimum-56.0.37.tgz ``` 이어서 사용할 플랫폼을 빌드하세요. ```sh npx expo run:ios # Or: npx expo run:android ``` 이 명령은 앱을 빌드하고 설치한 뒤 실행합니다. 먼저 iOS simulator 또는 Android emulator를 준비하세요. 기기를 선택하려면 `--device`를 사용하세요. 실제 iPhone에서는 `app.json`에 고유한 `ios.bundleIdentifier`를 설정하고 Expo의 signing 절차도 따르세요. prebuild를 먼저 실행하지 않아도 native 디렉터리가 없으면 run 명령이 자동으로 생성합니다. ## Native cookie 접근 확인 버튼의 async handler에서 아래 함수를 호출하세요. 성공하면 반환된 문구를, 실패하면 catch한 오류를 화면에 표시하세요. 실행할 때마다 새 값을 사용해 이전에 저장한 쿠키로 검사가 잘못 통과하지 않도록 합니다. ```ts import NitroCookies from "react-native-nitro-cookies"; async function checkCookies(): Promise { const url = "https://expo-cookie-check.example"; const name = "expo_development_check"; const value = String(Date.now()); await NitroCookies.set(url, { name, value, path: "/", secure: true }); for (let attempt = 0; attempt < 20; attempt++) { const cookies = await NitroCookies.get(url); if (cookies[name]?.value === value) { return "PASS: native cookie set/get"; } await new Promise((resolve) => setTimeout(resolve, 100)); } throw new Error("Cookie was not visible within 2 seconds"); } ``` Android의 `set()`은 CookieManager에 쓰기를 요청한 뒤 수락 여부를 기다리지 않고 완료됩니다. `await set()` 직후에는 `get()` 결과가 비어 있을 수 있습니다. 이 검사는 제한된 시간 동안 재조회합니다. API의 완료 조건을 바꾸지는 않습니다. `flush()`도 쓰기 수락을 기다리는 수단이 아닙니다. 예제는 기본 cookie store를 사용하며 HTTP 요청을 보내지 않습니다. 통과하면 native module 로딩과 쿠키 저장·조회를 확인한 것입니다. WebView나 HTTP client의 쿠키 공유를 검증한 결과는 아닙니다. 앱에 WebView 화면이 없어도 Android에는 정상적으로 동작하는 WebView provider가 필요합니다. ## 개발 이어가기 Development build를 설치한 뒤에는 다음 명령으로 Metro를 시작하세요. ```sh npx expo start --dev-client ``` JavaScript만 바뀌면 설치된 client에서 reload할 수 있습니다. Native dependency나 앱의 native 설정이 바뀌면 native 프로젝트를 다시 생성하고 빌드하세요. ```sh npx expo prebuild --clean --template ./expo-template-bare-minimum-56.0.37.tgz npx expo run:ios # Or: npx expo run:android ``` `--clean`은 `ios/`와 `android/`를 삭제하고 다시 만듭니다. 이 디렉터리에서 직접 수정한 내용도 사라집니다. Native 설정 변경을 app config나 config plugin에 옮긴 뒤 사용하세요. Metro 재시작만으로 native dependency가 다시 빌드되지는 않습니다. ## 로컬 소스 변경 사항 테스트 배포된 1.3.0 이후의 로컬 변경 사항을 테스트하려면 source tarball을 설치하세요. 소스를 테스트하려면 저장소 checkout에서 라이브러리를 빌드하고 tarball로 묶으세요. Expo 앱의 native 프로젝트를 생성하기 전에 이 tarball을 설치하세요. ```sh # Repository root: corepack enable yarn install --immutable yarn package prepare yarn package pack --out /tmp/react-native-nitro-cookies-source.tgz # Expo app directory: npm install /tmp/react-native-nitro-cookies-source.tgz ``` `prepare`는 JavaScript, 타입, Nitro binding을 빌드합니다. `pack`은 패키지에 문서를 넣는 단계도 실행합니다. 소스를 테스트할 때 `npm install react-native-nitro-cookies@1.3.0`로 대체하면 npm 배포본이 설치됩니다. 소스를 바꿔 다시 묶을 때는 새 tarball 파일명을 사용하세요. 앱에 다시 설치한 뒤 development client를 재빌드하세요. ## 검증한 구성 Expo `56.0.23`, React Native `0.85.3`, Nitro Modules `0.35.9`, `expo-dev-client` `56.0.27` 조합에서 위 검사를 실행했습니다. iPhone 17 Pro simulator의 iOS 26.5와 Android 15 (API 35) emulator에서 development build를 설치하고 `set()`·`get()` 검사가 통과하는지 확인했습니다. Android 빌드에는 JDK 17을 사용했습니다. 검증 대상은 commit [`827a165`](https://github.com/l2hyunwoo/react-native-nitro-cookies/commit/827a1655ef2f227982f6aefe84f6b08a826e2d62)의 source tarball입니다. 당시 검증에서 npm 1.3.0 배포본을 별도로 실행하지는 않았습니다. 다른 SDK 조합, EAS build, WebView·HTTP client와의 쿠키 공유는 검증 범위에 포함하지 않습니다. ## 참고 자료 - [Expo development build](https://docs.expo.dev/develop/development-builds/introduction/) - [Expo SDK와 React Native 버전](https://docs.expo.dev/versions/latest/) - [Native generation과 clean 동작](https://docs.expo.dev/workflow/continuous-native-generation/) - [Expo CLI의 development client 실행 대상](https://docs.expo.dev/more/expo-cli/#launch-target) --- 원문: [첫 쿠키 저장하기](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/first-cookie.md) # 첫 쿠키 저장하기 Session cookie를 저장하고 다시 읽은 뒤 HTTP request header를 만들어 보세요. 먼저 [설치](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/installation.md)를 마치고 native 앱을 실행하세요. Android에서는 앱에 WebView 화면이 없어도 정상적으로 동작하는 WebView provider가 필요합니다. ## 1. 쿠키 저장 개발용 버튼의 async handler 등 `await`를 사용할 수 있는 곳에서 다음 코드를 실행하세요. ```ts import NitroCookies from "react-native-nitro-cookies"; const url = "https://api.example.com"; await NitroCookies.set(url, { name: "demo_session", value: "demo-token", path: "/", secure: true, }); ``` 이 호출은 기본 cookie store를 사용합니다. Apple에서는 shared cookie store를, Android에서는 CookieManager를 사용합니다. `demo-token`은 예제용 값입니다. 실제 인증에는 서버가 발급한 token을 사용하세요. ## 2. 값 조회 Android의 `set()`은 CookieManager에 쓰기를 요청한 뒤, CookieManager가 이를 수락했는지 기다리지 않고 완료됩니다. 바로 조회하면 결과가 비어 있을 수 있습니다. `await set()`만으로 저장 완료를 판단하지 말고, 인증에 사용하기 전에 쿠키가 조회되는지 확인하세요. ```ts const cookies = await NitroCookies.get(url); const matches = cookies.demo_session?.value === "demo-token"; // 저장한 값이 조회되면 true ``` `get`은 쿠키 이름을 key로 삼는 dictionary를 반환합니다. 일치하는 쿠키가 없으면 `{}`를 반환합니다. 같은 이름의 쿠키를 빠짐없이 조회하려면 [list API](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/reading.md#getlist)를 사용하세요. ## 3. Request header 생성 ```ts const header = await NitroCookies.getCookieHeader(url); // demo_session=demo-token 포함 ``` 실제 요청 URL을 path까지 포함해 전달하세요. `fetch`에 header를 직접 전달하는 예제는 [request header 보내기](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/request-headers.md)에서 확인하세요. 실제 인증 쿠키를 로그에 남기지 마세요. ## 4. 예제용 쿠키 삭제 ```ts await NitroCookies.clearByName(url, "demo_session"); ``` 이 예제에서는 다른 쿠키와 겹치지 않는 이름과 `/` path를 사용합니다. 같은 이름의 쿠키가 여러 scope에 있다면 [scope를 지정해 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/scoped-deletion.md)하세요. 쿠키가 조회되지 않으면 [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md)에서 URL, cookie store, native 앱 재빌드 여부, Android WebView provider 상태를 확인하세요. --- 원문: [Cookie store와 scope](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/concepts/storage.md) # Cookie store와 scope 쿠키를 구분하려면 저장된 cookie store와 scope를 알아야 합니다. 이름만으로는 쿠키 하나를 특정할 수 없습니다. 로그인 상태를 공유하거나 쿠키를 삭제하기 전에 두 개념을 확인하세요. ## Cookie store 선택 | 플랫폼 | 기본 cookie store | `useWebKit: true` | | ------- | ------------------------------ | ---------------------------------------------------------- | | iOS | `HTTPCookieStorage.shared` | `WKWebsiteDataStore.default().httpCookieStore` | | tvOS | `HTTPCookieStorage.shared` | `WEBKIT_UNAVAILABLE`로 실패 | | Android | `android.webkit.CookieManager` | 같은 CookieManager 사용. 이 인자는 동작에 영향을 주지 않음 | Sync 메서드는 기본 cookie store를 사용합니다. iOS WebKit cookie store에 접근하려면 async 메서드를 사용해야 합니다. Cookie store를 선택하는 것만으로는 다른 store와 쿠키가 자동으로 동기화되지 않습니다. 네트워크 라이브러리의 설정도 바뀌지 않습니다. Ephemeral WKWebView는 별도의 data store를 사용하므로 이 API가 접근하는 기본 WebKit cookie store와 다릅니다. ## Name, domain, path로 쿠키 구분 `/`의 `session`과 `/admin`의 `session`은 함께 저장할 수 있습니다. 상위 domain의 쿠키와 host-only 쿠키도 함께 존재할 수 있습니다. Apple의 list 결과에서는 `domain` 앞의 점으로 domain 쿠키와 host-only 쿠키를 구분합니다. 같은 이름의 쿠키를 모두 유지하려면 `getList`를 사용하세요. `get`은 dictionary를 만들면서 같은 이름의 쿠키 중 native 결과에서 마지막에 나온 항목만 남깁니다. Native 결과의 순서를 앱에서 사용할 쿠키의 우선순위로 해석하지 마세요. Android는 저장된 쿠키 객체 전체가 아니라 요청에 사용할 `Cookie` header를 반환합니다. 따라서 URL로 조회한 list에는 `name`과 `value`만 있으며, 확인할 수 없는 scope 필드는 생략합니다. 기존 Android dictionary API가 반환하는 `domain`과 `/` path는 요청 URL을 기준으로 만든 값입니다. 쿠키를 처음 저장한 scope로 간주하면 안 됩니다. ## 조회 결과와 request header의 차이 Apple의 `get`, `getList`와 각각의 sync 메서드는 기존 domain 선택 규칙을 사용합니다. 이 조회 API들은 `getCookieHeader`가 적용하는 요청 path, Secure, 만료 조건을 모두 적용하지는 않습니다. Android의 URL 조회는 CookieManager의 URL 선택 규칙을 따릅니다. 실제 요청에 쿠키를 보낼 때는 [request header API](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/request-headers.md)를 사용하세요. 쿠키의 식별 정보를 확인하거나 [scope를 지정해 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/scoped-deletion.md)하려면 list API를 사용하세요. ## Secure와 HttpOnly `secure`는 HTTPS 요청에만 쿠키를 보내도록 제한합니다. `httpOnly`는 브라우저의 JavaScript가 쿠키에 접근하지 못하게 하는 flag입니다. Native cookie API로는 HttpOnly 쿠키의 값을 React Native 코드에서 읽을 수 있습니다. 두 flag는 쿠키를 암호화하거나 별도의 보안 저장소에 보관하는 기능을 제공하지 않습니다. 인증 값은 로그나 진단 데이터에 남기지 마세요. --- 원문: [Request header 보내기](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/request-headers.md) # Request header 보내기 HTTP 요청에 맞는 `Cookie` header를 만들어 직접 전달하는 방법입니다. 사용 중인 네트워크 라이브러리에 header를 직접 전달해야 할 때 사용하세요. ## Header를 조회한 뒤 요청에 전달 ```ts import NitroCookies from "react-native-nitro-cookies"; const url = "https://api.example.com/admin/profile"; const cookieHeader = await NitroCookies.getCookieHeader(url); const response = await fetch(url, { headers: cookieHeader ? { Cookie: cookieHeader } : {}, }); ``` 요청 URL에는 path 전체를 포함하세요. `/admin` 쿠키는 `/admin/profile`에 일치하지만 `/administrator`에는 일치하지 않습니다. Secure 쿠키를 보내려면 HTTPS를 사용해야 합니다. URL에 일치하는 HttpOnly 쿠키와 이름이 중복된 쿠키도 header에 포함됩니다. 일치하는 쿠키가 없으면 `''`를 반환하므로, 위 예제는 이때 `Cookie` header를 생략합니다. Promise 없이 기본 cookie store를 조회하려면 `getCookieHeaderSync(url)`을 호출하세요. iOS WebKit cookie store를 조회하려면 `getCookieHeader(url, true)`를 호출하세요. ## 요청 URL이 바뀌면 다시 생성 반환된 header는 조회할 때 전달한 URL을 기준으로 만든 값입니다. 요청 URL이 바뀌면 header도 다시 생성하세요. 다른 host로 보내는 요청에 인증 header를 재사용하지 마세요. Redirect 이후 URL에도 같은 header를 보내도 된다고 가정하지 마세요. Redirect와 자동 쿠키 처리는 네트워크 라이브러리의 정책을 따릅니다. Nitro Cookies는 이 정책을 설정하지 않습니다. `get`이나 `getList` 결과로 request header를 직접 만들지 마세요. Apple에서는 두 조회 API의 쿠키 선택 규칙이 request header API와 다릅니다. 전체 signature는 [Cookie header와 응답 쿠키](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/requests.md)에서 확인하세요. ## HTTP client와 연결 위 예제는 React Native `fetch`에 header를 직접 전달합니다. Axios 같은 다른 client에서도 동일한 URL에 보내는 요청의 [headers 옵션](https://axios-http.com/docs/req_config)으로 값을 전달하세요. 요청마다 host와 path가 다를 수 있으므로 인증 header를 전역 기본값으로 설정하지 마세요. Header를 직접 전달해도 Nitro Cookies와 client 사이의 쿠키 공유나 응답 쿠키 저장이 자동으로 이루어지지는 않습니다. 이 패키지는 client의 credentials, redirect 처리, native cookie jar를 설정하지 않습니다. 설치한 client와 플랫폼 버전에서 각각의 동작을 확인하세요. WebView 로그인은 [WebView cookie store 선택](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/webviews.md)을 참고하세요. 로그아웃할 때 [필요한 쿠키만 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/scoped-deletion.md#targeted-logout)할 수 있도록, 로그인에 사용한 cookie store와 쿠키 식별 정보를 보관하세요. --- 원문: [WebView cookie store 사용하기](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/webviews.md) # WebView cookie store 사용하기 iOS에서 기본 WebKit cookie store에 접근하려면 `useWebKit` 인자에 `true`를 전달하세요. WebView에서 페이지를 열기 전에 쿠키 저장이 끝날 때까지 기다리세요. ```ts import NitroCookies from "react-native-nitro-cookies"; const url = "https://example.com"; await NitroCookies.set( url, { name: "session", value: "server-issued-token", secure: true, path: "/", }, true, ); const cookies = await NitroCookies.get(url, true); ``` WebKit cookie store를 선택하는 `useWebKit`은 `set`의 세 번째 인자, `get`의 두 번째 인자입니다. 생략하면 Apple shared cookie store를 사용합니다. 로그인 쿠키를 읽고 저장하고 삭제할 때는 같은 cookie store를 사용하세요. ## WebView 설정 시 확인할 점 이 패키지는 쿠키를 관리합니다. WebView를 생성하거나 설정하지 않으며, store 사이에서 쿠키를 복사하거나 ephemeral WKWebsiteDataStore에 접근하는 기능도 제공하지 않습니다. 사용 중인 WebView 라이브러리에서 data store와 쿠키 옵션을 별도로 설정하세요. Sync 메서드로는 WebKit cookie store에 접근할 수 없습니다. ## Android와 TV Android에서는 항상 CookieManager를 사용합니다. `useWebKit` 인자로 Android의 다른 cookie store를 선택할 수는 없습니다. WebView provider가 없거나, 비활성 상태이거나, 업데이트 중이면 cookie store 작업이 `WEBVIEW_UNAVAILABLE`로 실패할 수 있습니다. 일부 Android TV 기기에는 WebView provider가 없습니다. 이 오류를 감지해도 대체 cookie store를 제공하지는 않습니다. tvOS는 shared cookie store를 지원하지만, 이 라이브러리에는 tvOS용 WebKit 구현이 없습니다. `useWebKit: true`를 요청하면 `WEBKIT_UNAVAILABLE`로 실패합니다. tvOS에서는 기본 cookie store를 사용하세요. 여러 플랫폼에서 같은 코드를 사용하려면 먼저 [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md)을 확인하세요. --- 원문: [Scope를 지정해 쿠키 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/scoped-deletion.md) # Scope를 지정해 쿠키 삭제 같은 이름의 쿠키가 여러 개라면 `clearCookie` API를 사용하세요. 다른 쿠키를 삭제하지 않도록 저장할 때 사용한 `name`, `domain`, `path`를 전달하세요. ## Apple: 조회한 식별 정보 그대로 사용 ```ts import NitroCookies from "react-native-nitro-cookies"; const url = "https://api.example.com/admin"; const cookies = await NitroCookies.getList(url); const target = cookies.find( (cookie) => cookie.name === "session" && cookie.path === "/admin", ); if (target?.path) { await NitroCookies.clearCookie(url, { name: target.name, domain: target.domain, path: target.path, }); } ``` Apple의 list 결과는 `domain` 앞의 점까지 저장된 그대로 유지합니다. 삭제할 때도 이 값을 그대로 전달하세요. iOS WebKit cookie store를 사용한다면 두 async 호출에 모두 `true`를 전달하세요. 일치하는 쿠키가 없으면 다른 쿠키를 변경하지 않고 완료됩니다. ## Android: 저장할 때 scope 보관 Android의 URL 조회 결과에서는 저장된 `domain`과 `path`를 확인할 수 없습니다. 쿠키를 저장할 때 이 필드의 값도 보관하세요. ```ts const url = "https://api.example.com/admin"; const scope = { name: "session", domain: "api.example.com", path: "/admin" }; await NitroCookies.set(url, { ...scope, value: "server-issued-token", secure: true, }); await NitroCookies.clearCookie(url, scope); ``` `domain`을 지정하면 앞의 점 유무와 관계없이 `Domain` attribute를 만듭니다. 기존 Android `set`은 `domain`을 생략해도 URL의 host를 기본값으로 사용해 `Domain` attribute를 만듭니다. 삭제할 때도 이 domain을 전달하세요. `set`에서 `domain`을 생략했다는 이유만으로 host-only 쿠키라고 판단하면 안 됩니다. `Domain`이 없는 raw `Set-Cookie` header처럼, 실제로 host-only로 저장한 쿠키를 삭제할 때만 `domain`을 생략하세요. Secure 쿠키를 삭제하려면 HTTPS를 사용하세요. ## 완료 시점과 입력 검증 Android의 `clearCookieSync`는 쿠키를 만료시키는 쓰기 작업을 요청한 뒤, 수락 여부를 확인하지 않고 반환합니다. `clearCookie`는 CookieManager가 쓰기를 수락할 때까지 기다립니다. 두 메서드 모두 삭제 전에 쿠키가 존재했는지는 알려 주지 않습니다. Apple에서는 선택한 cookie store의 삭제 작업이 끝나면 완료됩니다. 삭제할 쿠키를 지정하려면 유효한 `name`, `/`로 시작하는 절대 `path`, URL과 호환되는 `domain`이 필요합니다. 입력이 잘못되면 쿠키를 변경하기 전에 실패합니다. 자세한 동작은 [쿠키 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/deletion.md)와 [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md)에서 확인하세요. ## 다른 domain을 유지하며 로그아웃 {#targeted-logout} 로그인에 사용한 모든 쿠키의 식별 정보를 보관하세요. 이름이 같아도 path가 다르면 별도 쿠키입니다. Apple에서는 선택한 cookie store도 기억해야 합니다. Android에서는 조회 결과로 scope를 복원하지 못하므로 저장할 때 기록하세요. ```ts import NitroCookies, { type CookieIdentifier, } from "react-native-nitro-cookies"; const url = "https://api.example.com/account"; const identities: CookieIdentifier[] = [ { name: "session", domain: "api.example.com", path: "/" }, { name: "session", domain: "api.example.com", path: "/account" }, ]; for (const identity of identities) { await NitroCookies.clearCookie(url, identity); } ``` 이 예제는 기본 cookie store에서 식별 정보가 일치하는 쿠키만 삭제합니다. iOS WebKit으로 로그인했다면 각 `clearCookie` 호출의 세 번째 인자에 `true`를 전달하세요. 각 domain과 호환되는 URL을 사용해야 합니다. 하나의 URL로 서로 관계없는 domain의 쿠키를 모두 선택할 수는 없습니다. `clearAll`은 관계없는 domain을 포함해 선택한 cookie store 전체를 비웁니다. Store 전체를 초기화하려는 경우에만 사용하세요. 로컬 쿠키를 삭제해도 서버의 session이 무효화되거나 다른 cookie store·HTTP client의 인증 정보가 삭제되지는 않습니다. 앱의 인증 흐름에 맞게 서버 로그아웃과 client별 정리를 함께 처리하세요. --- 원문: [기존 앱 마이그레이션](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/migration.md) # 기존 앱 마이그레이션 Nitro Cookies는 `@react-native-cookies/cookies`와 유사한 async 쿠키 API를 제공합니다. Import를 바꾼 뒤 앱이 사용하는 cookie store와 플랫폼별 동작을 확인하세요. ## Native dependency 교체 [설치 가이드](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/installation.md)에 따라 두 패키지를 설치하세요. 기존 native 쿠키 패키지를 제거한 뒤 앱을 다시 빌드하세요. ```diff - import CookieManager from '@react-native-cookies/cookies'; + import CookieManager from 'react-native-nitro-cookies'; ``` Import한 객체의 이름을 유지하면 호출부의 수정 범위를 줄일 수 있습니다. 다만 기존 패키지와 모든 동작이 같다고 가정하지 마세요. ## 마이그레이션 전 확인할 점 | 앱에서 가정한 동작 | 확인할 내용 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------- | | 같은 이름의 쿠키는 하나뿐이다 | 같은 이름의 쿠키를 모두 다뤄야 한다면 list API를 사용하세요. | | 조회 결과로 원래 scope를 알 수 있다 | Android의 URL 조회로는 알 수 없습니다. 저장할 때 scope를 보관하세요. | | Native 쿠키와 WebView 쿠키는 같은 store를 사용한다 | 필요한 호출에서 iOS WebKit cookie store를 명시하세요. | | 모든 Android 기기에서 cookie store를 사용할 수 있다 | WebView provider가 정상적으로 동작하지 않는 기기에서도 앱이 오류를 처리하도록 구현하세요. | | 이름으로 삭제하면 원하는 쿠키 하나만 지운다 | 같은 이름의 쿠키가 여러 scope에 있다면 `clearCookie`를 사용하세요. | | 모든 플랫폼에서 모든 메서드를 지원한다 | `getAll`, WebKit, 디스크 저장, session cookie의 동작을 확인하세요. | ## 필요한 호출에만 sync 메서드 적용 Sync 메서드는 Promise를 반환하지 않으며 iOS WebKit cookie store에 접근할 수 없습니다. WebKit 접근이나 플랫폼이 작업을 수락했는지 확인해야 하는 곳에서는 async 호출을 유지하세요. Sync 메서드를 제공한다는 이유만으로 모든 async 호출을 바꿀 필요는 없습니다. 지원할 플랫폼에서 인증, 로그아웃, WebView 페이지 이동, 디스크 저장이 의도대로 동작하는지 검증하세요. Error normalization 규칙은 [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md)에서 확인하세요. --- 원문: [트러블슈팅](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/troubleshooting.md) # 트러블슈팅 증상에 맞는 항목에서 native 설정, cookie store, scope를 차례로 확인하세요. 먼저 [플랫폼 지원 표](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md)에서 사용하려는 기능을 지원하는지 확인하세요. ## 메서드를 호출하기 전에 import가 실패할 때 Nitro Cookies는 import 시점에 native HybridObject를 생성합니다. Native module이 없으면 메서드 호출에 적용하는 error normalization이 실행되기 전에 import 자체가 실패할 수 있습니다. 1. Nitro Cookies와 호환되는 Nitro runtime을 함께 설치하세요. 2. Apple 플랫폼에서는 필요한 Pod를 설치한 뒤 native 앱을 다시 빌드하고 실행하세요. 3. Expo에서는 두 native 패키지를 포함한 development build를 사용하세요. Expo Go에서는 이 모듈을 불러올 수 없습니다. 4. Jest에서는 Nitro Cookies를 import하기 전에 native runtime을 mock하세요. 저장소의 [테스트 안내](https://github.com/l2hyunwoo/react-native-nitro-cookies/blob/main/CONTRIBUTING.md)를 참고하세요. Metro에서 앱을 reload하는 것만으로는 native module이 추가되지 않습니다. 자세한 절차는 [설치](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/installation.md)를 참고하세요. ## 문서에 있는 메서드를 찾을 수 없을 때 설치한 패키지 버전과 [릴리스 이력](https://github.com/l2hyunwoo/react-native-nitro-cookies/releases)을 비교하세요. 이 문서는 1.3.0을 기준으로 설명합니다. List API, scope를 지정하는 삭제 API, error normalization은 1.3.0부터 지원합니다. 이전 버전이라면 [설치 절차](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/installation.md)에 따라 업데이트하고 native 앱을 다시 빌드하세요. ## Android에서 WEBVIEW_UNAVAILABLE이 발생할 때 Android cookie store에는 정상적으로 동작하는 WebView provider가 필요합니다. 앱에 WebView 화면이 없어도 마찬가지입니다. 기기에 provider가 설치되어 있고 활성 상태인지, 업데이트가 끝났는지 확인하세요. 앱에서 `WEBVIEW_UNAVAILABLE`을 처리하고 cookie store를 사용할 수 없는 상태임을 사용자에게 안내하세요. 일부 Android TV 기기에는 provider가 없습니다. Nitro Cookies를 설치해도 대체 cookie store가 생기지는 않습니다. 소스 브랜치의 오류 계약은 [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md)에서 확인하세요. ## 저장은 성공했는데 바로 조회하면 비어 있을 때 Android의 `set`과 `setMany`는 CookieManager의 수락 callback을 기다리지 않고 쓰기 작업을 요청합니다. Sync·async 모두 같은 제약이 있습니다. `await set()`도 쓰기가 수락됐다는 뜻은 아닙니다. 인증에 사용하기 전에 원하는 쿠키가 조회되는지 확인하세요. 일정 시간 기다리는 것만으로 완료를 보장할 수는 없습니다. 다음 조건도 확인하세요. - 원하는 host와 path를 포함한 HTTP 또는 HTTPS URL을 사용하세요. Secure 쿠키에는 HTTPS가 필요합니다. - iOS에서는 같은 cookie store에 저장하고 조회하세요. 지원하는 async 메서드의 `useWebKit`으로 기본 WebKit cookie store를 선택합니다. - `setFromResponse`는 Apple shared cookie store에 저장합니다. WebKit을 선택하는 인자는 없습니다. - WebView의 ephemeral store는 이 패키지로 선택할 수 없습니다. - HttpOnly는 브라우저의 `document.cookie` 접근을 제한합니다. 반환된 값을 React Native JavaScript에서 숨기는 기능은 아닙니다. 자세한 동작은 [쿠키 저장](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/writing.md)과 [cookie store와 scope](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/concepts/storage.md)를 참고하세요. ## Dictionary에 쿠키가 안 보이거나 삭제 후에도 남아 있을 때 `get`은 쿠키 이름을 key로 사용하므로 같은 이름의 쿠키 중 하나만 남습니다. 중복 쿠키를 확인하려면 list API를 사용하세요. Android의 URL list는 `name`과 `value`를 제공하지만 원래 `domain`, `path`, flag는 복원하지 못합니다. 조회한 metadata로 scope를 추정하지 마세요. 저장할 때 사용한 scope를 보관하세요. Android의 `clearByName`은 정확한 식별 정보로 삭제할 쿠키를 선택하지 않습니다. 반환값만으로 모든 scope의 쿠키가 삭제됐다고 판단하면 안 됩니다. `clearCookie` API에 원래 `name`, `domain`, `path`를 전달하세요. Apple에서는 저장할 때 사용한 cookie store도 같아야 합니다. 자세한 방법은 [scope를 지정해 쿠키 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/scoped-deletion.md)를 참고하세요. ## 직접 보낸 요청에 예상과 다른 쿠키가 포함될 때 Path를 포함한 실제 요청 URL을 `getCookieHeader`에 전달하세요. Dictionary나 list의 값을 이어 붙여 header를 만들지 마세요. Apple의 일반 조회는 request header와 쿠키 선택 규칙이 다릅니다. 요청 URL이 바뀌면 header를 다시 생성하고, 네트워크 라이브러리의 redirect·자동 쿠키 처리 정책은 별도로 확인하세요. 예제는 [request header 보내기](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/request-headers.md)를 참고하세요. ## 재현 가능한 문제 보고 라이브러리 버전이나 source commit, React Native·Nitro 버전, OS·기기, URL 구조, 선택한 cookie store, 실패한 메서드를 함께 알려 주세요. Android라면 WebView provider 상태도 포함하세요. 재현에는 예제 쿠키를 사용하고 로그에서 인증 토큰을 제거하세요. 최소 재현 코드를 [GitHub Issues](https://github.com/l2hyunwoo/react-native-nitro-cookies/issues)에 등록하세요. --- 원문: [API 개요](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/index.md) # API 개요 `NitroCookies`를 default import하면 23개 메서드를 사용할 수 있습니다. 이 API Reference에 나오는 signature는 모두 `NitroCookies` 객체의 메서드를 나타냅니다. ```ts import NitroCookies, { CookieErrorCode, type Cookie, type CookieIdentifier, type Cookies, type CookieError, } from "react-native-nitro-cookies"; ``` ## 작업별 메서드 | 작업 | 메서드 | 문서 | | ------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------- | | 저장된 쿠키 조회 | `getSync`, `get`, `getListSync`, `getList`, `getAll`, `getAllList` | [쿠키 조회](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/reading.md) | | 쿠키 저장 | `setSync`, `set`, `setManySync`, `setMany`, `setFromResponseSync`, `setFromResponse` | [쿠키 저장](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/writing.md) | | Header 생성·응답 쿠키 조회 | `getCookieHeaderSync`, `getCookieHeader`, `getFromResponse`, `getFromResponseList` | [Cookie header와 응답 쿠키](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/requests.md) | | 쿠키 삭제 | `clearCookieSync`, `clearCookie`, `clearByNameSync`, `clearByName`, `clearAll` | [쿠키 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/deletion.md) | | 디스크 저장·session cookie 삭제 | `flush`, `removeSessionCookies` | [Session cookie와 디스크 저장](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/lifecycle.md) | ## 공통 규칙 - URL 인자에는 전체 HTTP(S) URL을 전달하세요. - `useWebKit`은 생략 가능한 boolean 인자입니다. 옵션 객체를 받지 않으며, 기본값은 `false`입니다. - Sync 메서드는 기본 cookie store를 사용합니다. Async 메서드는 Promise를 반환하지만, 완료 시점은 플랫폼과 작업에 따라 다릅니다. - Dictionary는 쿠키 이름을 key로 사용합니다. List는 이름이 같은 쿠키를 모두 유지합니다. - 공개 wrapper에서 발생한 오류에는 문자열 형태의 `code`가 있습니다. 오류 처리 코드를 작성하기 전에 [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md)를 확인하세요. List API, scope를 지정하는 삭제 API, error normalization은 **1.3.0부터 사용할 수 있습니다**. 지원 버전과 업데이트 절차는 [설치](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/installation.md)에서 확인하세요. 데이터 구조는 [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/types.md), 메서드별 지원 여부는 [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md)에서 확인하세요. ## AI 도구에서 문서 읽기 [llms.txt](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/llms.txt)에서 주제별 Markdown 문서를 찾거나, [llms-full.txt](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/llms-full.txt)에서 한국어 문서 전체를 한 번에 읽을 수 있습니다. 두 파일은 사이트 문서를 바탕으로 자동 생성하며, 릴리스 안내와 플랫폼 제약도 그대로 포함합니다. --- 원문: [쿠키 조회](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/reading.md) # 쿠키 조회 쿠키를 이름으로 찾으려면 dictionary를, 이름이 같은 쿠키를 모두 조회하려면 list를 사용하세요. Apple의 URL 조회는 domain을 기준으로 쿠키를 선택합니다. 실제 요청에 보낼 쿠키가 필요하면 [request header API](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/requests.md)를 사용하세요. `useWebKit`의 기본값은 `false`입니다. `true`를 전달하면 iOS WebKit cookie store를 선택합니다. tvOS에서는 이 요청이 실패하며, Android에서는 이 인자를 무시합니다. 일치하는 쿠키가 없으면 dictionary API는 `{}`, list API는 `[]`를 반환합니다. ## getSync ```ts getSync(url: string): Cookies ``` 기본 cookie store를 sync 방식으로 조회합니다. 쿠키 이름을 key로 사용하므로, 이름이 같으면 native 결과에서 나중에 나온 항목이 앞의 항목을 덮어씁니다. ## get ```ts get(url: string, useWebKit?: boolean): Promise ``` 선택한 cookie store를 async 방식으로 조회합니다. 같은 이름의 쿠키는 기존 dictionary API와 같은 방식으로 처리합니다. Android에서 반환하는 metadata는 실제 저장된 scope가 아니라 URL을 기준으로 만든 값입니다. ## getListSync ```ts getListSync(url: string): Cookie[] ``` **1.3.0부터 지원합니다.** 기본 cookie store를 조회하면서 같은 이름의 쿠키를 모두 유지합니다. Apple은 저장된 `domain`과 `path`를 보존합니다. Android의 URL 조회 결과에는 `name`과 `value`만 있습니다. ## getList ```ts getList(url: string, useWebKit?: boolean): Promise ``` **1.3.0부터 지원합니다.** 선택한 cookie store를 list로 조회합니다. 순서는 native 결과를 따릅니다. Android의 list 항목만으로는 삭제할 쿠키를 특정할 수 없으므로, 저장할 때 사용한 scope가 별도로 필요합니다. ## getAll ```ts getAll(useWebKit?: boolean): Promise ``` Domain과 관계없이 선택한 Apple cookie store의 모든 쿠키를 조회합니다. Dictionary 결과에는 같은 이름의 쿠키 중 하나만 남습니다. Android에서는 `PLATFORM_UNSUPPORTED`로 실패합니다. ## getAllList ```ts getAllList(useWebKit?: boolean): Promise ``` **1.3.0부터 지원합니다.** 선택한 Apple cookie store의 모든 쿠키를 조회합니다. 이름이 같은 쿠키도 빠짐없이 반환하며, 저장된 scope를 유지합니다. Android에서는 `PLATFORM_UNSUPPORTED`로 실패합니다. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md) · [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md) --- 원문: [쿠키 저장](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/writing.md) # 쿠키 저장 `Cookie` 객체를 저장하거나 raw `Set-Cookie` header를 전달합니다. 전체 HTTP(S) URL과 그 host에 호환되는 cookie domain을 사용하세요. `Cookie` 객체를 저장할 때 `path`를 생략하면 `/`, `domain`을 생략하면 URL의 host를 사용합니다. `useWebKit`의 기본값은 `false`입니다. iOS에서 `Cookie` 객체를 저장하는 async 메서드만 WebKit cookie store를 선택할 수 있습니다. Android의 기존 저장 API는 Promise를 반환하더라도 CookieManager가 쓰기를 수락했는지 확인하는 callback 없이 쓰기 작업을 요청합니다. 반환값이 `true`여도 모든 플랫폼에서 디스크 저장까지 끝났다는 뜻은 아닙니다. Android에서 디스크 저장이 필요하면 [flush](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/lifecycle.md#flush)를 사용하세요. ## setSync ```ts setSync(url: string, cookie: Cookie): boolean ``` 기본 cookie store에 쿠키 하나를 저장하도록 요청합니다. Native 메서드가 예외 없이 끝나면 `true`를 반환합니다. ## set ```ts set(url: string, cookie: Cookie, useWebKit?: boolean): Promise ``` 선택한 cookie store에 쿠키 하나를 저장합니다. iOS WebKit에서는 store의 완료 callback을 받은 뒤 Promise가 resolve됩니다. Android에서는 쓰기를 요청한 뒤 resolve되며, 수락 여부는 확인하지 않습니다. ## setManySync ```ts setManySync(url: string, cookies: Cookie[]): boolean ``` 기본 cookie store에 여러 쿠키를 저장하도록 요청합니다. 쓰기를 시작하기 전에 domain을 검증합니다. 저장 중 오류가 나더라도 이미 저장한 쿠키를 transaction처럼 rollback한다고 보장하지는 않습니다. ## setMany ```ts setMany(url: string, cookies: Cookie[], useWebKit?: boolean): Promise ``` 선택한 cookie store에 여러 쿠키를 저장합니다. Apple WebKit에서는 완료 callback을 기다립니다. 작업이 예외 없이 끝나면 `true`로 resolve됩니다. Android에서는 쓰기 요청이 끝났다는 뜻이며, 수락 여부는 확인하지 않습니다. ## setFromResponseSync ```ts setFromResponseSync(url: string, value: string): boolean ``` Raw `Set-Cookie` 문자열을 파싱하거나 native API에 전달해 기본 cookie store에 저장합니다. `value`에는 응답의 `Set-Cookie` header를 전달하세요. 요청의 `Cookie` header를 받는 인자가 아닙니다. 파싱 방식은 플랫폼을 따릅니다. ## setFromResponse ```ts setFromResponse(url: string, value: string): Promise ``` Raw `Set-Cookie` header를 저장하는 async 메서드입니다. `useWebKit` 인자는 없습니다. `Expires` 값에는 쉼표가 들어갈 수 있으므로, 여러 `Set-Cookie` header를 쉼표로 합치지 마세요. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md) · [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md) --- 원문: [Cookie header와 응답 쿠키](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/requests.md) # Cookie header와 응답 쿠키 `getCookieHeader*`는 cookie store에서 요청에 보낼 header를 만듭니다. `getFromResponse*`는 native `GET` 요청을 보내고 응답에서 쿠키를 파싱합니다. 앱이 전달한 `Response` 객체를 파싱하는 메서드는 아닙니다. 실제로 요청을 보낼 HTTP(S) URL을 사용하세요. 일치하는 쿠키가 없으면 header API는 `''`, 응답 조회 API는 `{}` 또는 `[]`를 반환합니다. ## getCookieHeaderSync ```ts getCookieHeaderSync(url: string): string ``` 기본 cookie store에서 요청에 바로 사용할 수 있는 `Cookie` header를 만듭니다. Apple에서는 host, path, Secure, 만료 조건을 적용합니다. Android에서는 CookieManager의 URL 선택 규칙을 따릅니다. 이름이 같아도 URL에 일치하는 쿠키는 모두 header에 포함됩니다. ## getCookieHeader ```ts getCookieHeader(url: string, useWebKit?: boolean): Promise ``` `Cookie` header를 async 방식으로 조회합니다. `useWebKit`의 기본값은 `false`이며, iOS WebKit cookie store를 선택할 수 있습니다. tvOS에서는 WebKit 접근이 실패합니다. 반환된 header에는 HttpOnly 쿠키도 포함될 수 있습니다. ## getFromResponse ```ts getFromResponse(url: string): Promise ``` Native `GET` 요청을 보내고 응답에서 파싱한 쿠키를 이름별로 반환합니다. 별도의 request header나 body를 전달하는 인자는 없습니다. 범용 HTTP client로 사용하거나, 응답 쿠키를 모든 플랫폼의 cookie store에 동일하게 저장해 주는 API로 간주하지 마세요. ## getFromResponseList ```ts getFromResponseList(url: string): Promise ``` **1.3.0부터 지원합니다.** `getFromResponse`와 같은 native 요청을 보내지만, 이름이 같은 쿠키도 빠짐없이 list로 반환합니다. 파싱한 metadata도 유지합니다. Redirect 처리와 자동 쿠키 저장 등 부수 효과는 native 네트워크 구현을 따릅니다. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md) · [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md) --- 원문: [쿠키 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/deletion.md) # 쿠키 삭제 쿠키 하나를 정확히 삭제하려면 scope를 지정하세요. 기존에 이름만으로 삭제하던 API는 플랫폼별 동작을 그대로 유지합니다. `useWebKit`의 기본값은 `false`입니다. 이 인자를 받는 메서드에서는 iOS WebKit cookie store를 선택할 수 있습니다. `CookieIdentifier`에는 `name`과 `/`로 시작하는 절대 `path`가 필요합니다. Host-only 쿠키를 삭제할 때만 `domain`을 생략하세요. `domain`을 지정하면 그 scope의 쿠키를 선택합니다. 식별 정보가 잘못되면 `PARSE_ERROR`, URL과 domain이 호환되지 않으면 `DOMAIN_MISMATCH`로 실패합니다. 쿠키를 변경하기 전에 이 조건들을 검증합니다. ## clearCookieSync ```ts clearCookieSync(url: string, identifier: CookieIdentifier): void ``` **1.3.0부터 지원합니다.** 기본 cookie store에서 식별 정보가 일치하는 쿠키를 삭제합니다. 반환형은 `void`입니다. Apple에서는 일치하는 쿠키가 없으면 아무 작업도 하지 않습니다. Android에서는 쿠키를 만료시키는 쓰기를 요청하며, 쓰기의 수락 여부나 쿠키의 존재 여부는 확인하지 않습니다. ## clearCookie ```ts clearCookie(url: string, identifier: CookieIdentifier, useWebKit?: boolean): Promise ``` **1.3.0부터 지원합니다.** 선택한 cookie store에서 식별 정보가 일치하는 쿠키를 삭제합니다. Android에서는 CookieManager가 쓰기를 수락할 때까지 기다립니다. CookieManager가 쓰기를 거절하면 오류로 처리합니다. 삭제 전에 쿠키가 존재했는지는 알 수 없습니다. Secure 쿠키를 삭제하려면 HTTPS를 사용하세요. ## clearByNameSync ```ts clearByNameSync(url: string, name: string): boolean ``` 기본 cookie store에서 이름만으로 삭제하는 기존 메서드입니다. Apple에서는 이름이 일치하는 첫 번째 쿠키를 삭제합니다. Android에서는 `Path=/`와 URL host의 `Domain` attribute를 사용해 쿠키 만료를 시도합니다. Boolean 반환값만으로 원하는 scope의 쿠키가 삭제됐다고 판단하지 마세요. ## clearByName ```ts clearByName(url: string, name: string, useWebKit?: boolean): Promise ``` 이름만으로 삭제하는 기존 API의 async 메서드입니다. iOS WebKit cookie store를 선택하는 인자를 받습니다. 이름이 같은 쿠키가 여러 path나 domain에 있다면 `clearCookie`를 사용하세요. ## clearAll ```ts clearAll(useWebKit?: boolean): Promise ``` 선택한 cookie store 전체를 비웁니다. 앱이 요청하는 domain 외의 쿠키도 삭제하며, URL 인자는 받지 않습니다. Apple에서는 완료 후 `true`를 반환하고, Android에서는 CookieManager가 쿠키를 하나라도 삭제했는지 반환합니다. Cookie store 전체를 비우려는 경우에만 사용하세요. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md) · [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md) --- 원문: [Session cookie와 디스크 저장](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/lifecycle.md) # Session cookie와 디스크 저장 이 메서드들은 Android에서만 쿠키를 변경하거나 디스크에 저장합니다. Apple에서는 기존 API와의 호환성을 위해 아무 작업도 하지 않습니다. URL을 지정하거나 WebKit cookie store를 선택하는 인자는 받지 않습니다. ## flush ```ts flush(): Promise ``` Android에서는 `CookieManager.flush()`를 호출해 현재 쿠키를 디스크에 저장합니다. Promise는 값을 반환하지 않고 resolve됩니다. iOS와 tvOS에서는 아무 작업 없이 완료되며, WebKit cookie store도 flush하지 않습니다. ## removeSessionCookies ```ts removeSessionCookies(): Promise ``` Android에서는 만료 시각이 없는 session cookie를 삭제하고, 플랫폼이 알려 주는 삭제 여부를 반환합니다. iOS와 tvOS에서는 쿠키를 삭제하지 않고 `false`를 반환합니다. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md) · [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md) --- 원문: [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/types.md) # Types 타입은 패키지 루트에서 import하세요. Native 조회 결과에는 일부 optional 필드가 빠질 수 있습니다. ## Cookie ```ts interface Cookie { name: string; value: string; path?: string; domain?: string; version?: string; expires?: string; secure?: boolean; httpOnly?: boolean; } ``` | 필드 | 설명 | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name`, `value` | `Cookie` 객체를 저장할 때 필수입니다. | | `path` | 저장할 때 기본값은 `/`입니다. Android의 URL list 결과에는 없습니다. | | `domain` | 저장할 때 기본값은 URL의 host입니다. Apple list는 저장된 값 앞의 점도 유지합니다. Android의 URL list 결과에는 없습니다. | | `version` | 기존 API에서 제공하는 optional 필드입니다. 모든 플랫폼에서 같은 동작을 보장하지는 않습니다. | | `expires` | ISO 8601 timestamp입니다. `2030-01-01T00:00:00.000Z`처럼 소수 초와 시간대를 포함하세요. 생략하면 session cookie이며, 수명은 cookie store의 정책을 따릅니다. | | `secure` | HTTPS 요청에만 쿠키를 전송하도록 제한합니다. | | `httpOnly` | 브라우저의 JavaScript 접근을 제한하는 flag입니다. Native API로는 쿠키를 읽을 수 있습니다. | 이 interface에는 `SameSite`와 `Max-Age` 필드가 없습니다. Raw `Set-Cookie` 처리 방식은 플랫폼을 따르며, `Cookie` 객체가 header의 모든 attribute를 표현하지는 않습니다. ## Cookies ```ts type Cookies = Record; ``` Dictionary의 key는 쿠키 이름입니다. Native 결과에 같은 이름의 항목이 여러 개면 나중 항목이 앞의 항목을 덮어씁니다. 같은 이름의 쿠키를 모두 유지하려면 `Cookie[]`를 반환하는 list API를 사용하세요. ## CookieIdentifier **1.3.0부터 지원합니다.** `clearCookie`와 `clearCookieSync`에서 사용합니다. ```ts interface CookieIdentifier { name: string; path: string; domain?: string; } ``` `path`는 필수이며 `/`로 시작해야 합니다. `domain`을 생략하면 URL host의 host-only 쿠키를 삭제합니다. `domain`을 지정하면 그 scope의 쿠키를 선택합니다. Android에서는 호출자가 저장할 때 사용한 scope를 보관해야 합니다. URL 조회 결과만으로는 원래 scope를 알 수 없습니다. Android의 저장 기본값과 삭제 인자의 차이는 [scope를 지정해 쿠키 삭제](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/scoped-deletion.md)에서 확인하세요. ## CookieError ```ts interface CookieError extends Error { code: CookieErrorCode | string; cause?: unknown; url?: string; cookieName?: string; } ``` `CookieError`는 TypeScript interface입니다. Runtime class가 아니므로 `instanceof CookieError`로 검사할 수 없습니다. 공개 wrapper는 원래 던진 값을 `cause`에 넣고, 원래 메시지와 stack이 있으면 보존합니다. Runtime enum과 기본 오류 코드 선택 규칙은 [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md)에서 확인하세요. --- 원문: [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md) # Errors **1.3.0부터 적용되는 오류 처리 규칙입니다.** 23개 공개 메서드에서 발생한 오류는 문자열 `code`가 있는 `Error`로 전달됩니다. Sync 호출은 이 오류를 throw하고, async 호출은 이 오류로 Promise를 reject합니다. 알려진 오류 코드를 처리할 때는 패키지가 export하는 runtime enum을 사용하세요. ```ts import NitroCookies, { CookieErrorCode } from "react-native-nitro-cookies"; try { await NitroCookies.get("https://example.com"); } catch (error) { if (error instanceof Error && "code" in error) { if (error.code === CookieErrorCode.WEBVIEW_UNAVAILABLE) { // Cookie store를 사용할 수 없다는 안내를 표시하세요. } } } ``` ## 오류 코드별 대응 | 코드 | 의미 | 확인할 내용 | | ---------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `INVALID_URL` | Protocol이 없거나 URL이 잘못되었습니다. | 전체 HTTP(S) URL을 전달하세요. | | `DOMAIN_MISMATCH` | 쿠키 또는 삭제할 쿠키의 domain이 URL과 호환되지 않습니다. | Host와 원래 쿠키의 scope를 확인하세요. | | `PLATFORM_UNSUPPORTED` | 현재 플랫폼에서 지원하지 않는 메서드입니다. | 지원 표를 확인하고, 지원하지 않는 호출을 피하세요. | | `WEBKIT_UNAVAILABLE` | tvOS 등에서 요청한 WebKit cookie store를 사용할 수 없습니다. | Shared cookie store로 처리할 수 있는 작업인지 확인하세요. | | `WEBVIEW_UNAVAILABLE` | Android의 WebView 기반 cookie store를 초기화할 수 없습니다. | WebView provider 상태를 확인하고, cookie store를 사용할 수 없는 경우를 처리하세요. | | `PARSE_ERROR` | Header 파싱이나 쿠키 식별 정보 검증에 실패했습니다. | 입력과 필수 필드를 확인하세요. | | `NETWORK_ERROR` | 응답 조회에 실패했거나, 응답 조회 중 분류하지 못한 오류가 발생했습니다. | 요청 URL과 네트워크 연결을 확인하세요. | | `STORAGE_ERROR` | Cookie store 작업에 실패했거나, 다른 메서드에서 분류하지 못한 오류가 발생했습니다. | 원래 오류와 cookie store 상태를 확인하세요. | WebView provider가 없다는 사실을 감지해도 WebView를 설치하거나 대체 cookie store를 만들지는 않습니다. ## 오류에 포함되는 정보 Wrapper는 새 `Error`를 만들고 원래 throw한 값을 `cause`에 담습니다. 원래 메시지와 stack이 있으면 함께 보존합니다. 호출할 때 전달한 `url`도 추가합니다. 쿠키 하나를 저장하거나 삭제하는 작업에서는 `cookieName`도 추가합니다. Wrapper가 쿠키 값을 오류 정보에 추가하지는 않습니다. 다만 원래 오류 메시지나 URL에는 앱 데이터가 포함될 수 있습니다. 원래 오류에 비어 있지 않은 문자열 `code`가 있으면, 알려지지 않은 코드여도 그대로 유지합니다. 코드를 분류할 수 없는 `getFromResponse`·`getFromResponseList` 오류는 `NETWORK_ERROR`로, 다른 메서드의 오류는 `STORAGE_ERROR`로 처리합니다. Bridge 메시지는 Nitro 0.35.9의 형식을 기준으로 파싱합니다. Bridge가 바뀌면 파싱 규칙도 수정해야 할 수 있습니다. ## 초기화 실패 Import 시점에 HybridObject를 생성하는 과정에는 위 error normalization 규칙을 적용하지 않습니다. Native module을 찾을 수 없다면 먼저 설치 상태를 확인하고 앱을 다시 빌드하세요. 그다음 쿠키 메서드의 동작을 확인하세요. --- 원문: [플랫폼 지원](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/platforms.md) # 플랫폼 지원 Nitro Cookies는 iOS, Android, tvOS의 native React Native 앱에서 사용합니다. Android TV도 Android 구현을 사용하며, cookie store 작업에는 정상적으로 동작하는 WebView provider가 필요합니다. 웹과 Expo Go에서는 이 native module을 사용할 수 없습니다. ## 플랫폼별 지원 기능 | 기능 | iOS | tvOS | Android / Android TV | | ---------------------------------------- | -------------------------------------- | -------------------------- | -------------------------------------- | | 기본 cookie store 조회·저장·header·삭제 | Shared cookie store | Shared cookie store | CookieManager. WebView provider 필요 | | `useWebKit: true` | 기본 WebKit cookie store. Async만 지원 | `WEBKIT_UNAVAILABLE` | 인자 무시 | | List 조회 | 저장된 metadata 포함 | 저장된 metadata 포함 | URL list는 `name`과 `value`만 제공 | | `getAll`, `getAllList` | 지원 | 기본 cookie store에서 지원 | `PLATFORM_UNSUPPORTED` | | Scope를 지정한 삭제 | 저장된 식별 정보로 삭제 | 저장된 식별 정보로 삭제 | 호출자가 지정한 scope에 쿠키 만료 요청 | | `getFromResponse`, `getFromResponseList` | Native 네트워크 요청 | Native 네트워크 요청 | Native 네트워크 요청 | | `flush` | 아무 작업도 하지 않음 | 아무 작업도 하지 않음 | CookieManager의 쿠키를 디스크에 저장 | | `removeSessionCookies` | 삭제 없이 `false` 반환 | 삭제 없이 `false` 반환 | 플랫폼의 삭제 callback 사용 | Android의 기본 최소 지원 버전은 API 24입니다. Apple deployment target은 React Native와 Nitro의 요구사항에도 영향을 받습니다. WebKit API를 iOS 11부터 사용할 수 있다는 이유로 앱도 iOS 11을 지원한다고 판단하면 안 됩니다. 라이브러리 podspec에는 tvOS 지원을 선언했지만, 사용하는 React Native tvOS 버전이 더 높은 deployment target을 요구할 수 있습니다. ## 저장소의 검증 구성 {#repository-configurations} 아래 표는 현재 예제 앱과 native fixture에 설정한 버전입니다. 모든 React Native 버전과의 호환성을 보장하지는 않습니다. 플랫폼 변경을 검토할 때는 해당 CI 실행 결과도 확인하세요. | 프로젝트 | React Native | Nitro Modules | 추가 설정 | | ----------------------- | ---------------------------- | ------------- | ---------------------------------------------------- | | iOS / Android 예제 앱 | `0.85.3` | `0.35.9` | `react-native-webview 13.16.1`. Android 앱 minSdk 24 | | iOS native fixture | `0.85.3` | `0.35.9` | `test-apple.sh ios`로 XCTest 실행 | | tvOS native fixture | `react-native-tvos 0.85.3-3` | `0.35.9` | `test-tvos.sh`로 XCTest 실행 | | Android instrumentation | 예제 앱의 dependency 사용 | `0.35.9` | CI API 35, `google_apis`, x86_64 | Android CI는 phone 이미지를 사용합니다. WebView provider가 없는 경우의 테스트는 그 실패 경로를 확인하는 데 그치며, Android TV system image에서의 검증을 대신하지는 않습니다. Nitro의 peer 범위는 `react-native-nitro-modules >=0.35.0 <1.0.0`입니다. `react-native: *`라는 peer 선언도 모든 React Native 버전에서 검증했다는 뜻은 아닙니다. Expo에서는 native 패키지를 포함한 development build를 사용하세요. 자세한 설정은 [설치](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/start/installation.md)와 [CI workflow](https://github.com/l2hyunwoo/react-native-nitro-cookies/blob/main/.github/workflows/ci.yml)를 참고하세요. ## 쿠키가 조회되지 않을 때 1. 두 패키지를 설치한 뒤 native 앱을 다시 빌드했는지 확인하세요. 2. 전체 URL, HTTPS 조건, domain, 요청 path를 확인하세요. 3. iOS에서는 읽기와 저장에 같은 cookie store를 사용하세요. 4. Android에서는 WebView provider가 설치되어 있고 활성 상태인지 확인하세요. 5. 같은 이름의 쿠키가 여러 개라면 list로 조회하세요. Android에서는 저장할 때 사용한 scope를 별도로 보관하세요. WebView가 없는 Android TV 기기에서 이 패키지를 설치해도 cookie store가 생기지는 않습니다. `WEBVIEW_UNAVAILABLE`이 발생하면 cookie store를 사용할 수 없는 상태로 처리하세요. 플랫폼별 동작 차이는 [cookie store와 scope](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/concepts/storage.md), 오류 처리 방법은 [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/reference/errors.md)에서 확인하세요. 증상별 확인 순서는 [트러블슈팅](https://l2hyunwoo.github.io/react-native-nitro-cookies/ko/guides/troubleshooting.md)을 참고하세요.