문제 해결

일반적인 문제

getItem이 항상 null을 반환합니다

원인 1: 값이 저장되지 않은 키를 조회하는 경우

해당 키에 값이 저장된 적이 없으면 null이 반환됩니다. 먼저 setItem으로 값을 저장했는지 확인하세요.

원인 2: 동적 키에 params를 전달하지 않은 경우

userSSN 등 동적 키는 params가 없으면 빈 문자열 키로 조회하게 됩니다.

// 잘못된 예 - params 없이 동적 키 조회
const ssn = await UnifiedDeviceDataModule.getItem({
  unifiedKey: 'userSSN', // userId 파라미터 없음
});

// 올바른 예
const ssn = await UnifiedDeviceDataModule.getItem({
  unifiedKey: 'userSSN',
  params: { userId: currentUserId },
});

원인 3: iOS/Android 간 플랫폼이 다른 경우

시뮬레이터와 실제 기기, 또는 플랫폼이 달라지면 저장된 키가 다릅니다. 동일한 플랫폼에서 저장/조회가 이루어지는지 확인하세요.

Unknown unified key 오류가 발생합니다

PLATFORM_KEY_MAPPING에 정의되지 않은 키를 사용할 때 발생합니다.

Error: Unknown unified key: myCustomKey

UnifiedKey 타입에 정의된 키만 사용할 수 있습니다. 타입스크립트를 사용하는 경우 컴파일 시점에 잘못된 키를 감지할 수 있습니다.

// 사용 가능한 키 확인
import type { UnifiedKey } from '@boostbrothers/react-native-device-data-module';

네이티브 모듈을 찾을 수 없습니다 (NativeModuleNotFound)

원인: 네이티브 빌드가 완료되지 않았거나 pod install이 실행되지 않은 경우

해결:

# iOS
cd ios && pod install && cd ..
npx react-native run-ios

# Android
npx react-native run-android

# Expo
npx expo run:ios
npx expo run:android

Metro 번들러 캐시를 초기화합니다.

npx react-native start --reset-cache

Android에서 noLoginADPushAllowed 값이 예상과 다릅니다

Android는 ALLOWED_AD_PUSH 키에 JSON 형식으로 데이터를 저장하고, 모듈이 내부적으로 파싱하여 반환합니다. iOS는 단순 문자열로 저장됩니다.

const allowed = await UnifiedDeviceDataModule.getItem({
  unifiedKey: 'noLoginADPushAllowed',
});

// 크로스 플랫폼 호환 코드
const isAllowed = allowed === true || allowed === 'true';

fcmRegisterId를 iOS에서 사용하면 빈 문자열이 반환됩니다

fcmRegisterId는 Android 전용 키입니다. iOS에는 매핑이 없어 getPlatformKey가 빈 문자열을 반환합니다.

import { Platform } from 'react-native';

// 플랫폼 확인 후 사용
if (Platform.OS === 'android') {
  const fcmId = await UnifiedDeviceDataModule.getItem({
    unifiedKey: 'fcmRegisterId',
  });
}

레거시 키 마이그레이션

기존에 플랫폼별 키를 직접 사용하던 코드를 통합 키 시스템으로 마이그레이션하는 방법입니다.

// 기존 코드 (AsyncStorage 또는 직접 네이티브 접근)
// key: 'accessToken'

// 마이그레이션 후
import UnifiedDeviceDataModule from '@boostbrothers/react-native-device-data-module';

const token = await UnifiedDeviceDataModule.getItem({
  unifiedKey: 'accessToken',
});
// 내부적으로 iOS의 'accessToken' 키를 사용합니다

// 기존 코드
// key: 'DDOC_DOC_TOKEN'

// 마이그레이션 후
import UnifiedDeviceDataModule from '@boostbrothers/react-native-device-data-module';

const token = await UnifiedDeviceDataModule.getItem({
  unifiedKey: 'accessToken',
});
// 내부적으로 Android의 'DDOC_DOC_TOKEN' 키를 사용합니다

FAQ

Q: getAllKeys()에서 반환된 키로 getItem을 사용할 수 있나요?

아니요. getAllKeys()는 플랫폼별 실제 스토리지 키를 반환하며, getItem은 통합 키(UnifiedKey)만 허용합니다. getAllKeys()는 디버깅 목적으로만 사용하세요.

Q: useGetPlatformKey: false는 언제 사용하나요?

레거시 코드나 테스트 목적으로 통합 키 이름을 그대로 스토리지 키로 사용하고 싶을 때 사용합니다. 일반적인 사용에서는 기본값(true)을 유지하세요.

Q: 동시에 여러 값을 저장/조회할 수 있나요?

각 함수가 독립적으로 Promise를 반환하므로 Promise.all로 병렬 처리할 수 있습니다.

const [token, refreshToken] = await Promise.all([
  UnifiedDeviceDataModule.getItem({ unifiedKey: 'accessToken' }),
  UnifiedDeviceDataModule.getItem({ unifiedKey: 'refreshToken' }),
]);

Q: 앱 삭제 시 저장된 데이터는 어떻게 되나요?

• iOS UserDefaults: 앱 삭제 시 함께 삭제됩니다.
• Android SharedPreferences: 앱 삭제 시 함께 삭제됩니다.

민감한 데이터(액세스 토큰 등)는 보안 스토리지(iOS Keychain, Android Keystore)에 저장하는 것을 고려하세요. 민감 데이터 보안 저장이 필요하다면 react-native-kms-module을 참고하세요.