🎯 프로젝트 구조 이해하기

Capacitor 프로젝트의 기본 구조를 살펴보자:

myApp/
├── src/                    # 웹 앱 소스 코드
│   ├── components/         # 컴포넌트들
│   ├── pages/             # 페이지들
│   └── App.tsx            # 메인 앱 컴포넌트
├── public/                # 정적 파일들
├── ios/                   # iOS 네이티브 프로젝트
├── android/               # Android 네이티브 프로젝트
├── capacitor.config.ts    # Capacitor 설정 파일
└── package.json           # npm 패키지 설정

중요한 건 src 폴더야. 여기서 대부분의 개발이 이루어져. ios와 android 폴더는 Capacitor가 자동으로 관리해주니까 직접 건드릴 일은 많지 않아!

📸 카메라 플러그인 사용하기

사진을 찍거나 갤러리에서 이미지를 선택하는 기능을 추가해보자!

# Camera 플러그인 설치
npm install @capacitor/camera

# 플랫폼에 동기화
npx cap sync

import { Camera, CameraResultType, CameraSource } from '@capacitor/camera';
import { useState } from 'react';

const PhotoCapture = () => {
  const [photo, setPhoto] = useState('');

  const takePicture = async () => {
    try {
      const image = await Camera.getPhoto({
        quality: 90,
        allowEditing: false,
        resultType: CameraResultType.Uri,
        source: CameraSource.Camera
      });

      // 이미지 URL을 state에 저장
      setPhoto(image.webPath);
    } catch (error) {
      console.error('사진 촬영 실패:', error);
    }
  };

  const pickFromGallery = async () => {
    try {
      const image = await Camera.getPhoto({
        quality: 90,
        allowEditing: false,
        resultType: CameraResultType.Uri,
        source: CameraSource.Photos
      });

      setPhoto(image.webPath);
    } catch (error) {
      console.error('갤러리 선택 실패:', error);
    }
  };

  return (
    <div>
      <button onClick={takePicture}>📷 사진 찍기</button>
      <button onClick={pickFromGallery}>🖼️ 갤러리에서 선택</button>
      
      {photo && (
        <img src={photo} alt="촬영한 사진" style={{maxWidth: '100%'}} />
      )}
    </div>
  );
};

정말 간단하지? JavaScript 함수 하나로 네이티브 카메라를 제어할 수 있어! 😍

📍 위치 정보(Geolocation) 사용하기

사용자의 현재 위치를 가져오는 기능도 쉽게 구현할 수 있어!

# Geolocation 플러그인 설치
npm install @capacitor/geolocation

# 동기화
npx cap sync

import { Geolocation } from '@capacitor/geolocation';
import { useState } from 'react';

const LocationTracker = () => {
  const [position, setPosition] = useState(null);
  const [error, setError] = useState('');

  const getCurrentPosition = async () => {
    try {
      const coordinates = await Geolocation.getCurrentPosition();
      
      setPosition({
        latitude: coordinates.coords.latitude,
        longitude: coordinates.coords.longitude,
        accuracy: coordinates.coords.accuracy
      });
      
      console.log('현재 위치:', coordinates);
    } catch (err) {
      setError('위치 정보를 가져올 수 없어요 😢');
      console.error(err);
    }
  };

  // 실시간 위치 추적
  const watchPosition = async () => {
    const watchId = await Geolocation.watchPosition({}, (position, err) => {
      if (err) {
        console.error('위치 추적 오류:', err);
        return;
      }
      
      console.log('위치 업데이트:', position);
      setPosition({
        latitude: position.coords.latitude,
        longitude: position.coords.longitude,
        accuracy: position.coords.accuracy
      });
    });

    // 추적 중지하려면: Geolocation.clearWatch({ id: watchId });
  };

  return (
    <div>
      <button onClick={getCurrentPosition}>📍 현재 위치 확인</button>
      <button onClick={watchPosition}>🔄 실시간 추적 시작</button>
      
      {position && (
        <div>
          <p>위도: {position.latitude}</p>
          <p>경도: {position.longitude}</p>
          <p>정확도: {position.accuracy}m</p>
        </div>
      )}
      
      {error && <p style={{color: 'red'}}>{error}</p>}
    </div>
  );
};

🔔 푸시 알림 구현하기

푸시 알림은 앱의 재방문율을 높이는 강력한 도구야! Capacitor에서도 쉽게 구현할 수 있어.

# Push Notifications 플러그인 설치
npm install @capacitor/push-notifications

# 동기화
npx cap sync

import { PushNotifications } from '@capacitor/push-notifications';
import { useEffect } from 'react';

const NotificationSetup = () => {
  useEffect(() => {
    // 푸시 알림 권한 요청
    const requestPermission = async () => {
      const result = await PushNotifications.requestPermissions();
      
      if (result.receive === 'granted') {
        // 권한이 승인되면 등록
        await PushNotifications.register();
      }
    };

    // 등록 성공 리스너
    PushNotifications.addListener('registration', (token) => {
      console.log('푸시 토큰:', token.value);
      // 이 토큰을 서버에 저장해야 해!
    });

    // 등록 실패 리스너
    PushNotifications.addListener('registrationError', (error) => {
      console.error('푸시 등록 실패:', error);
    });

    // 푸시 알림 수신 리스너 (앱이 포그라운드일 때)
    PushNotifications.addListener('pushNotificationReceived', (notification) => {
      console.log('알림 수신:', notification);
      alert(`새 알림: ${notification.title}`);
    });

    // 푸시 알림 클릭 리스너
    PushNotifications.addListener('pushNotificationActionPerformed', (notification) => {
      console.log('알림 클릭:', notification);
      // 특정 페이지로 이동하는 로직 추가 가능
    });

    requestPermission();

    // 클린업
    return () => {
      PushNotifications.removeAllListeners();
    };
  }, []);

  return <div>푸시 알림이 설정되었습니다! 🔔</div>;
};

중요한 포인트: 푸시 알림을 완전히 구현하려면 백엔드 서버도 필요해. Firebase Cloud Messaging (FCM)이나 Apple Push Notification Service (APNS)를 사용하면 돼. 이 부분은 조금 복잡할 수 있는데, 재능넷 같은 플랫폼에서 관련 전문가를 찾아보는 것도 좋은 방법이야! 💡

🌐 웹 브라우저에서 디버깅

개발 초기에는 웹 브라우저에서 테스트하는 게 가장 빨라!

# 개발 서버 시작
ionic serve

# 또는 특정 포트로 실행
ionic serve --port=8100

# 브라우저가 자동으로 열리고 Hot Reload 지원!

Chrome DevTools를 활용하면 다음을 할 수 있어:
• Console에서 로그 확인
• Network 탭에서 API 요청 모니터링
• Elements 탭에서 DOM 구조 확인
• Performance 탭에서 성능 분석
• Application 탭에서 Storage 확인

📱 실제 디바이스에서 디버깅

네이티브 기능을 테스트하려면 실제 디바이스가 필요해!

iOS 디버깅: 🍎

# 앱 빌드 및 동기화
ionic build
npx cap sync ios

# Xcode에서 실행
npx cap open ios

# Xcode에서:
# 1. 상단에서 실제 디바이스 선택
# 2. Run 버튼 클릭 (⌘ + R)
# 3. 디바이스에 앱이 설치되고 실행됨

Safari Web Inspector로 디버깅:
1. iPhone에서 설정 → Safari → 고급 → 웹 속성 활성화
2. Mac의 Safari에서 개발자 메뉴 활성화
3. 개발자 → [디바이스 이름] → [앱 이름] 선택
4. 웹 인스펙터가 열리면 Console, Network 등 확인 가능!

Android 디버깅: 🤖

# 앱 빌드 및 동기화
ionic build
npx cap sync android

# Android Studio에서 실행
npx cap open android

# Android Studio에서:
# 1. 디바이스를 USB로 연결 (USB 디버깅 활성화 필요)
# 2. 상단에서 디바이스 선택
# 3. Run 버튼 클릭

Chrome DevTools로 디버깅:
1. Android 디바이스를 USB로 연결
2. Chrome에서 chrome://inspect 접속
3. 디바이스와 앱이 목록에 표시됨
4. 'inspect' 클릭하면 DevTools 열림!

🧪 자동화된 테스트

수동 테스트만으로는 한계가 있어. 자동화된 테스트를 작성하자!

1. 유닛 테스트 (Jest):

// NewsService.test.ts
import { fetchNews } from './NewsService';

describe('NewsService', () => {
  test('뉴스를 성공적으로 가져온다', async () => {
    const news = await fetchNews();
    
    expect(news).toBeDefined();
    expect(news.length).toBeGreaterThan(0);
    expect(news[0]).toHaveProperty('title');
  });

  test('API 오류를 적절히 처리한다', async () => {
    // Mock API 오류
    global.fetch = jest.fn(() =>
      Promise.reject(new Error('Network error'))
    );

    await expect(fetchNews()).rejects.toThrow('Network error');
  });
});

2. 컴포넌트 테스트 (React Testing Library):

// NewsCard.test.tsx
import { render, screen } from '@testing-library/react';
import NewsCard from './NewsCard';

test('뉴스 카드가 올바르게 렌더링된다', () => {
  const news = {
    title: '테스트 뉴스',
    description: '테스트 설명'
  };

  render(<NewsCard news={news} />);

  expect(screen.getByText('테스트 뉴스')).toBeInTheDocument();
  expect(screen.getByText('테스트 설명')).toBeInTheDocument();
});

3. E2E 테스트 (Cypress):

// cypress/integration/news.spec.js
describe('뉴스 페이지', () => {
  beforeEach(() => {
    cy.visit('/news');
  });

  it('뉴스 목록이 표시된다', () => {
    cy.get('ion-card').should('have.length.greaterThan', 0);
  });

  it('뉴스를 클릭하면 상세 페이지로 이동한다', () => {
    cy.get('ion-card').first().click();
    cy.url().should('include', '/news/');
  });

  it('새로고침이 작동한다', () => {
    cy.get('ion-refresher').trigger('ionRefresh');
    cy.get('ion-card').should('exist');
  });
});

✨ 네이티브 느낌을 주는 인터랙션

1. 햅틱 피드백 (진동) 📳

import { Haptics, ImpactStyle } from '@capacitor/haptics';

// 버튼 클릭 시
const handleClick = async () => {
  await Haptics.impact({ style: ImpactStyle.Light });
  // 실제 동작 수행
};

// 성공 알림
const showSuccess = async () => {
  await Haptics.notification({ type: 'SUCCESS' });
};

// 오류 알림
const showError = async () => {
  await Haptics.notification({ type: 'ERROR' });
};

2. Pull-to-Refresh 🔄

import { IonRefresher, IonRefresherContent } from '@ionic/react';

const RefreshableList = () => {
  const handleRefresh = async (event: CustomEvent) => {
    // 데이터 새로고침
    await fetchNewData();
    
    // 완료 표시
    event.detail.complete();
  };

  return (
    <IonContent>
      <IonRefresher slot="fixed" onIonRefresh={handleRefresh}>
        <IonRefresherContent
          pullingIcon="arrow-down"
          pullingText="당겨서 새로고침"
          refreshingSpinner="circles"
          refreshingText="새로고침 중..."
        />
      </IonRefresher>
      
      {/* 리스트 내용 */}
    </IonContent>
  );
};

3. 스와이프 제스처 👆

import { IonItemSliding, IonItemOptions, IonItemOption } from '@ionic/react';

const SwipeableItem = ({ item }) => {
  return (
    <IonItemSliding>
      <IonItem>
        <IonLabel>{item.title}</IonLabel>
      </IonItem>

      <IonItemOptions side="end">
        <IonItemOption color="danger" onClick={() => deleteItem(item.id)}>
          삭제
        </IonItemOption>
        <IonItemOption onClick={() => archiveItem(item.id)}>
          보관
        </IonItemOption>
      </IonItemOptions>
    </IonItemSliding>
  );
};

4. 로딩 상태 표시 ⏳

import { IonLoading, IonSpinner } from '@ionic/react';

const LoadingExample = () => {
  const [showLoading, setShowLoading] = useState(false);

  return (
    <>
      {/* 전체 화면 로딩 */}
      <IonLoading
        isOpen={showLoading}
        message="로딩 중..."
        duration={5000}
        onDidDismiss={() => setShowLoading(false)}
      />

      {/* 인라인 스피너 */}
      {loading && (
        <div style={{textAlign: 'center', padding: '20px'}}>
          <IonSpinner name="crescent" />
        </div>
      )}
    </>
  );
};

📊 Google Analytics 연동

사용자 행동을 추적하고 분석하자!

# Firebase 플러그인 설치
npm install @capacitor-firebase/analytics
npx cap sync

# Firebase 프로젝트 생성 후 google-services.json (Android)과
# GoogleService-Info.plist (iOS) 파일을 프로젝트에 추가

import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

// 화면 조회 추적
const logScreenView = async (screenName: string) => {
  await FirebaseAnalytics.logEvent({
    name: 'screen_view',
    params: {
      screen_name: screenName,
      screen_class: screenName
    }
  });
};

// 커스텀 이벤트 추적
const logCustomEvent = async (eventName: string, params: any) => {
  await FirebaseAnalytics.logEvent({
    name: eventName,
    params
  });
};

// 사용 예시
useEffect(() => {
  logScreenView('NewsPage');
}, []);

const handleArticleClick = (articleId: string) => {
  logCustomEvent('article_click', {
    article_id: articleId,
    category: 'news'
  });
};

🐛 크래시 리포팅

앱이 크래시되면 자동으로 리포트를 받자!

# Sentry 설치
npm install @sentry/capacitor @sentry/react
npx cap sync

// App.tsx
import * as Sentry from '@sentry/capacitor';
import * as SentryReact from '@sentry/react';

Sentry.init({
  dsn: 'YOUR_SENTRY_DSN',
  integrations: [
    new SentryReact.BrowserTracing(),
  ],
  tracesSampleRate: 1.0,
  environment: process.env.NODE_ENV
});

// 에러 수동 리포트
try {
  // 위험한 작업
} catch (error) {
  Sentry.captureException(error);
}

📚 유용한 라이브러리 추천