RNWW Plugin Background

React Native WebView 백그라운드 실행 플러그인 (Expo Native Module)

Headless WebView를 사용하여 앱 종료 후에도 JavaScript를 독립적으로 실행합니다.

⚠️ 필수 설정

본 프로젝트(RN-Expo-WebApp-Wrapper-Template)에서 npm run config를 실행하여 플러그인 설정에서 **"Enable Headless Bridge"**를 체크해야 정상적으로 동작합니다.

이 옵션을 활성화하면:

• Headless WebView에 Bridge 스크립트가 자동으로 주입됩니다
• Headless WebView에서 AppBridge API를 사용할 수 있습니다
• 기존 Bridge 핸들러와 연동됩니다

설치

npm install rnww-plugin-background

빠른 시작

// 태스크 등록 - callback은 .toString()으로 전달해야 함!
await AppBridge.call('backgr:registerTask', {
  taskId: 'my-task',
  triggers: ['app_foreground', 'app_background'],
  callback: function(trigger, data) {
    // ⚠️ Headless WebView에서 실행됨 (Foreground WebView와 별개 context)
    console.log('Trigger:', trigger);
    
    if (trigger === 'init') {
      // 초기화 - TaskData에서 이전 상태 복원
      AppBridge.call('backgr:getTaskData', { taskId: data.taskId })
        .then(function(result) {
          window.__counter = result?.data?.counter || 0;
        });
    }
  }.toString(),  // ⚠️ 반드시 .toString() 사용!
  notification: {
    title: '백그라운드 실행 중',
    body: '서비스가 실행 중입니다'
  }
});

// 태스크 시작
await AppBridge.call('backgr:startTask', { taskId: 'my-task' });

핵심 개념

두 개의 분리된 WebView Context

이 플러그인의 핵심은 Foreground WebView와 Headless WebView가 완전히 별개의 context라는 점입니다.

┌─────────────────────────────────────────────────────────────────┐
│                    Native (React Native)                        │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   Bridge Handlers                          │  │
│  │   backgr:setTaskData, backgr:getTaskData, api:*, ...      │  │
│  └───────────────────────────────────────────────────────────┘  │
│                    ▲                ▲                           │
│                    │                │                           │
│         postMessage│      postMessage│                          │
│                    │                │                           │
│  ┌─────────────────┴──┐  ┌─────────┴────────────────────────┐  │
│  │ Foreground WebView │  │      Headless WebView            │  │
│  │                    │  │                                  │  │
│  │ • 실제 웹 페이지    │  │ • 빈 페이지 (스크립트만 실행)    │  │
│  │ • 사용자 인터랙션   │  │ • 백그라운드 콜백 실행           │  │
│  │ • window.AppBridge │  │ • window.AppBridge               │  │
│  │   (인스턴스 A)      │  │   (인스턴스 B)                   │  │
│  │                    │  │                                  │  │
│  │ 동일한 코드 주입    │  │ 동일한 코드 주입                 │  │
│  └────────────────────┘  └──────────────────────────────────┘  │
│       앱과 함께 종료           Foreground Service로 유지        │
└─────────────────────────────────────────────────────────────────┘

Context 특징 비교

| 항목 | Foreground WebView | Headless WebView | |------|-------------------|------------------| | 용도 | 실제 웹페이지 렌더링 | 백그라운드 스크립트 실행 | | DOM | 전체 HTML/CSS 렌더링 | 빈 페이지 | | window 객체 | 독립 인스턴스 | 독립 인스턴스 | | AppBridge | 동일한 API (인스턴스 A) | 동일한 API (인스턴스 B) | | 변수 공유 | ❌ 불가 | ❌ 불가 | | localStorage | 앱 종료 시 유지 | 서비스 종료 시 초기화 | | 생명주기 | 앱과 함께 | 서비스와 함께 (앱 종료 후에도 유지) |

AppBridge - 같은 코드, 다른 인스턴스

두 WebView에 동일한 Bridge 클라이언트 코드가 주입되므로:

• 같은 API 사용 가능: AppBridge.send(), AppBridge.call(), AppBridge.on() 등
• 같은 Native 핸들러 호출 가능: backgr:setTaskData, api:* 등
• 하지만 변수, 리스너, 상태는 공유되지 않음

TaskData를 통한 Context 동기화

두 WebView 간 데이터 공유는 TaskData API를 통해서만 가능합니다:

Foreground WebView  ←→  Native TaskData Storage  ←→  Headless WebView
     setTaskData() →      [JSON 데이터 저장]       ← setTaskData()
     getTaskData() ←                              → getTaskData()

// Headless에서 데이터 저장
AppBridge.call('backgr:setTaskData', {
  taskId: 'my-task',
  data: { counter: 10, lastUpdate: Date.now() }
});

// Foreground에서 데이터 읽기 (앱 재시작 시)
const result = await AppBridge.call('backgr:getTaskData', { taskId: 'my-task' });
// result.data = { counter: 10, lastUpdate: ... }

트리거 시스템

트리거 종류

| 트리거 | 호출 시점 | 자동 호출 | 설명 | |--------|----------|----------|------| | init | 태스크 시작 직후 | ✅ 항상 | 초기화 로직 실행 | | terminate | 태스크 종료 직전 | ✅ 항상 | 상태 저장, 리소스 정리 | | app_foreground | 앱 포그라운드 전환 | ❌ triggers 배열 필요 | 데이터 동기화, UI 갱신 | | app_background | 앱 백그라운드 전환 | ❌ triggers 배열 필요 | 상태 저장, 네트워크 요청 |

callback 함수 작성 주의사항

⚠️ callback은 반드시 .toString()으로 전달해야 합니다!

// ✅ 올바른 방법
const myCallback = function(trigger, data) {
  console.log(trigger);
};

await AppBridge.call('backgr:registerTask', {
  taskId: 'my-task',
  callback: myCallback.toString(),  // ✅ .toString() 필수!
  notification: { title: 'Service', body: 'Running' }
});

// ❌ 잘못된 방법 - JSON 직렬화 불가
await AppBridge.call('backgr:registerTask', {
  taskId: 'my-task',
  callback: myCallback,  // ❌ 함수는 JSON으로 전달 불가!
  notification: { title: 'Service', body: 'Running' }
});

완전한 callback 예시

const BACKGROUND_CALLBACK = function(trigger, data) {
  // ⚠️ 이 코드는 Headless WebView에서 실행됨!
  // window, AppBridge, fetch 등 Web API 사용 가능

  if (trigger === 'init') {
    // TaskData에서 이전 상태 복원
    AppBridge.call('backgr:getTaskData', { taskId: data.taskId })
      .then(function(result) {
        if (result && result.data && typeof result.data.counter === 'number') {
          window.__counter = result.data.counter;
        } else {
          window.__counter = 0;
        }
        
        // 주기적 작업 시작
        window.__interval = setInterval(function() {
          window.__counter++;
          
          // TaskData에 상태 저장
          AppBridge.call('backgr:setTaskData', {
            taskId: data.taskId,
            data: { counter: window.__counter, updatedAt: Date.now() }
          });
          
          // 알림 업데이트
          AppBridge.call('backgr:updateNotification', {
            taskId: data.taskId,
            title: 'Counter: ' + window.__counter,
            body: 'Running...'
          });
        }, 1000);
      });
  }

  if (trigger === 'terminate') {
    // 종료 전 정리
    if (window.__interval) {
      clearInterval(window.__interval);
      window.__interval = null;
    }
  }
};

await AppBridge.call('backgr:registerTask', {
  taskId: 'counter-task',
  triggers: ['app_foreground', 'app_background'],
  callback: BACKGROUND_CALLBACK.toString(),
  notification: { title: 'Counter', body: 'Starting...' }
});

Bridge Handlers

모든 핸들러는 backgr: 네임스페이스를 사용합니다.

태스크 생명주기

| 핸들러 | 설명 | |--------|------| | backgr:registerTask | 태스크 등록 | | backgr:unregisterTask | 태스크 해제 | | backgr:startTask | 태스크 시작 | | backgr:stopTask | 태스크 중지 | | backgr:stopAllTasks | 모든 태스크 중지 |

상태 조회

| 핸들러 | 설명 | |--------|------| | backgr:getTaskStatus | 특정 태스크 상태 조회 | | backgr:getAllTasksStatus | 전체 태스크 상태 조회 |

알림 (Android)

| 핸들러 | 설명 | |--------|------| | backgr:updateNotification | 알림 내용 업데이트 |

권한

| 핸들러 | 설명 | |--------|------| | backgr:checkBackgroundPermission | 백그라운드 권한 확인 | | backgr:requestBackgroundPermission | 배터리 최적화 예외 요청 | | backgr:checkNotificationPermission | 알림 권한 확인 (Android 13+) | | backgr:requestNotificationPermission | 알림 권한 요청 (Android 13+) |

TaskData (Context 동기화)

| 핸들러 | 설명 | 앱 종료 후 | |--------|------|-----------| | backgr:setTaskData | 데이터 저장 | ✅ 동작 | | backgr:getTaskData | 데이터 조회 | ✅ 동작 | | backgr:removeTaskData | 데이터 삭제 | ✅ 동작 |

WebView 제어 (레거시)

| 핸들러 | 설명 | |--------|------| | backgr:attachWebView | WebView 수동 연결 | | backgr:detachWebView | WebView 연결 해제 | | backgr:evaluateInMainWebView | Main WebView에서 JS 실행 |

앱 종료 후 동작

앱이 완전히 종료되어도 Foreground Service 내의 Headless WebView는 계속 동작합니다.

앱 종료 후에도 동작하는 것

• ✅ callback 함수 (Headless WebView에서 실행)
• ✅ backgr:* 핸들러 (Native에서 직접 처리)
• ✅ Web API (fetch, setTimeout, setInterval 등)
• ✅ TaskData 저장/조회

앱 종료 후 동작하지 않는 것

• ❌ React Native 핸들러 (api:*, auth:* 등)
• ❌ Foreground WebView와의 직접 통신

Foreground에서 백그라운드 상태 동기화

앱을 다시 열었을 때 백그라운드 상태와 동기화하는 패턴:

// Foreground WebView에서 (앱 재시작 시)
async function syncWithBackground() {
  const TASK_ID = 'my-task';
  
  // 1. 실행 중인 태스크 확인
  const statusResult = await AppBridge.call('backgr:getTaskStatus', { taskId: TASK_ID });
  
  if (statusResult?.status?.isRunning) {
    console.log('🔄 실행 중인 백그라운드 태스크 발견!');
    
    // 2. TaskData에서 현재 상태 읽기
    const dataResult = await AppBridge.call('backgr:getTaskData', { taskId: TASK_ID });
    
    if (dataResult?.data) {
      // 3. UI 업데이트
      setCounter(dataResult.data.counter);
      setLastUpdate(dataResult.data.updatedAt);
      console.log('UI 복원 완료:', dataResult.data);
    }
  }
}

// 앱 로드 시 호출
useEffect(() => {
  syncWithBackground();
}, []);

알림 설정 (Android)

notification: {
  title: string;              // 필수
  body: string;               // 필수
  icon?: string;              // drawable 리소스명
  color?: string;             // '#4CAF50'
  priority?: 'min' | 'low' | 'default' | 'high' | 'max';
  ongoing?: boolean;          // 기본값: true (스와이프 불가)
  silent?: boolean;           // 기본값: false
  channelId?: string;         // Android 8.0+
  channelName?: string;
  channelDescription?: string;
}

에러 타입

| 에러 | 설명 | 해결 방법 | |------|------|----------| | TASK_NOT_FOUND | 미등록 태스크 | registerTask 먼저 호출 | | TASK_ALREADY_EXISTS | 중복 등록 | unregisterTask 후 재등록 | | TASK_ALREADY_RUNNING | 이미 실행 중 | getTaskStatus로 확인 | | NOTIFICATION_PERMISSION_DENIED | 알림 권한 없음 | requestNotificationPermission 호출 | | WEBVIEW_INIT_TIMEOUT | Headless 초기화 실패 | 앱 재시작 또는 스크립트 확인 | | INVALID_INPUT | 잘못된 입력 | 유효한 taskId 확인 |

플랫폼별 설정

Android

AndroidManifest.xml에 자동 추가:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />

Android 13+ (API 33): POST_NOTIFICATIONS 런타임 권한 필수

iOS

Info.plist에 추가:

<key>UIBackgroundModes</key>
<array>
  <string>fetch</string>
  <string>processing</string>
</array>

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>expo.modules.custombackground.refresh</string>
</array>

라이선스

MIT