React Native Device Data Module

@boostbrothers/react-native-device-data-module — iOS UserDefaults와 Android SharedPreferences에 대한 통합 인터페이스를 제공하는 네이티브 스토리지 모듈. 플랫폼별 스토리지 키 차이를 단일 통합 키 시스템으로 추상화합니다.

When to Apply

Reference this skill when:

• 네이티브 스토리지(UserDefaults/SharedPreferences)에 접근할 때
• 플랫폼 간 키 매핑이 필요할 때
• 동적 키(userId 기반) 사용 시
• 토큰, 디바이스 ID 등 저장된 값을 읽을 때

Architecture

App Code
  ↓
UnifiedDeviceDataModule
  ↓
Platform Key Mapping
  ↓ Platform Detection
  ├── iOS → UserDefaults
  └── Android → SharedPreferences
        ↓ Value Transform (JSON 파싱)
        ↓ Timestamp 통일

중요: 모든 통합 키(UnifiedKey)는 내부적으로 현재 플랫폼에 맞는 실제 스토리지 키로 변환됩니다. 플랫폼별 키 이름을 직접 사용할 필요가 없습니다.

Key Features

Feature	Description
Unified Key System	iOS/Android 단일 키 이름
Platform Key Mapping	레거시 키 완전 호환
Dynamic Key Support	런타임 파라미터(userId 등)
Value Transform	Android JSON 자동 파싱
Timestamp Unification	플랫폼 간 시간 표준화

Key Mapping Summary

Unified Key	용도
requirePermissionSuccessScreen	권한 요청 성공 화면
deviceId	기기 고유 ID
userSSN	주민번호 (동적 키: userId 필요)
familyReceiptPopUp	가족 접수 팝업
kidsGrowthOverAgePopUp	아이 성장 나이 초과
appReviewPopUp	앱 리뷰 유도
accessToken	액세스 토큰
refreshToken	리프레시 토큰
expiresTimestamp	토큰 만료 시각
fcmRegisterId	FCM ID (Android 전용)
familyEditAuthPopUp	가족 수정 인증
noLoginADPushAllowed	광고 푸시 허용 (JSON 변환)
noLoginADPushAllowedTime	광고 푸시 변경 시각 (JSON 변환)

전체 플랫폼 매핑 테이블: rules/platform-key-mapping.md

Critical Edge Cases

1. 동적 키: userSSN

Android에서 userId 파라미터로 키 생성:

// userId='12345' → Android 키: 'USER_SSN_12345'
const ssn = await getDeviceData('userSSN', { userId: '12345' });

⚠️ params 없으면 USER_SSN_undefined 생성됨

2. Android 전용: fcmRegisterId

iOS에서 호출하면 빈 문자열 반환:

import { Platform } from 'react-native';
if (Platform.OS === 'android') {
  const fcmId = await getDeviceData('fcmRegisterId');
}

3. JSON 변환 키: noLoginADPushAllowed / noLoginADPushAllowedTime

Android 저장 형식:

{ "enablePush": true, "changedDate": "2024-01-15T10:30:00.000Z" }

• noLoginADPushAllowed → enablePush 필드 추출 (boolean)
• noLoginADPushAllowedTime → changedDate 밀리초 변환 (number)

⚠️ iOS는 개별 값으로 저장, Android는 JSON 객체로 저장 — 모듈이 자동 변환

4. 타임스탬프 통일

모든 타임스탬프를 밀리초 단위로 정규화:

• 밀리초 숫자 (>1,000,000,000,000): 그대로
• 초 단위: ×1000
• ISO 문자열: new Date(value).getTime()

Troubleshooting

키를 찾을 수 없음: UnifiedKey 이름이 올바른지 확인. 플랫폼별 실제 키 이름은 rules/platform-key-mapping.md 참조.

타입 불일치: iOS/Android에서 같은 키가 다른 타입을 반환할 수 있음 (예: noLoginADPushAllowed — iOS: string, Android: boolean). 모듈의 Value Transform이 이를 처리하지만, 타입 단언 주의.

동적 키 undefined: params 객체에 필수 파라미터를 전달했는지 확인. userSSN은 { userId } 필수.

Android JSON 파싱 실패: SharedPreferences에 저장된 값이 유효한 JSON인지 확인.

How to Use

Read the platform key mapping file for full mapping details:

rules/platform-key-mapping.md  — iOS/Android 키 매핑 전체 테이블, 엣지 케이스 상세

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md