NCloud Chat Flutter SDK #

Classic/VPC 환경에서 이용 가능합니다.

목차 #

1. 개요
2. 요구 사양
3. 설치
4. 빠른 시작
5. 푸시 알림 설정
6. 리전 설정
7. 에러 처리
8. 파일 업로드
9. 예제

개요 #

Ncloud Chat은 실시간 채팅 및 메시지 시스템, 여러 사용자가 대화할 수 있는 채널을 구현할 수 있는 서비스입니다. 쉽고 간단하게 채팅 서비스를 구축할 수 있도록 다양한 SDK와 API를 제공합니다.

네이버 클라우드 플랫폼의 Ncloud Chat 서비스를 활용하면 로그인 환경이나 운영 도구를 개발할 필요가 없고, 인프라 관리 및 사용자 관리를 위해 별도의 시스템을 구축하지 않아도 됩니다. 직관적이고 편리한 Ncloud Chat 대시보드에서 통계 분석, 서비스 운영 및 관리가 가능하며 네이버 클라우드 플랫폼의 다양한 서비스와의 연동을 통해 강력한 채팅 환경을 구축할 수 있습니다.

Ncloud Chat이 제공하는 다양한 기능 #

요구 사양 #

Flutter #

• Flutter 2.0 이상
• Dart 2.12 이상 (Null Safety 지원)

Android #

• minSdkVersion 21 이상
• targetSdkVersion 34 권장

iOS #

• iOS 12.0 이상
• Xcode 14.0 이상

지원 플랫폼 #

설치 #

`pubspec.yaml` 파일에 다음을 추가하세요:

```yaml dependencies: nchat: ^0.0.2 ```

🔔 푸시 알림 설정 #

Android 설정 #

1. AndroidManifest.xml 설정

`android/app/src/main/AndroidManifest.xml`에 다음을 추가하세요:

```xml

<application>
    <!-- NChat Notification Receiver -->
    <!-- SDK에 포함되어 있으므로 별도 추가 불필요 -->
</application>

2. 알림 권한 요청 (Android 13+)

```dart import 'package:permission_handler/permission_handler.dart';

// Android 13 이상에서 알림 권한 요청 if (Platform.isAndroid) { final status = await Permission.notification.request(); if (status.isGranted) { print('알림 권한 승인됨'); } } ```

3. 알림 아이콘 설정 (선택)

`android/app/src/main/res/drawable/`에 아이콘 파일 추가:

• `ic_stat_nchat_small.png` - 상태바 알림 아이콘 (권장)
• `ic_stat_nbase_small.png` - 대체 아이콘

iOS 설정 #

1. AppDelegate.swift 설정

```swift import Flutter import UIKit import UserNotifications

@main @objc class AppDelegate: FlutterAppDelegate { private var nchatChannel: FlutterMethodChannel?

override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { GeneratedPluginRegistrant.register(with: self)

// Flutter MethodChannel 설정 (APNs 토큰 전달용)
if let controller = window?.rootViewController as? FlutterViewController {
  nchatChannel = FlutterMethodChannel(
    name: "io.nbase.nchat/apns",
    binaryMessenger: controller.binaryMessenger
  )
}

// APNs 권한 요청
UNUserNotificationCenter.current().delegate = self
UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
  if granted {
    DispatchQueue.main.async {
      application.registerForRemoteNotifications()
    }
  }
}

return super.application(application, didFinishLaunchingWithOptions: launchOptions)

}

// APNs 토큰 수신 override func application( _ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data ) { let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined() print("[AppDelegate] APNs token: (token)") nchatChannel?.invokeMethod("onAPNsToken", arguments: token) }

// 포그라운드 알림 표시 override func userNotificationCenter( _ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void ) { completionHandler([.banner, .sound, .badge]) } } ```

2. Info.plist 설정

```xml ```

3. Capabilities 설정

Xcode에서 `Signing & Capabilities` → `+ Capability` → `Push Notifications` 추가

Flutter 코드에서 푸시 토큰 설정 #

import 'package:nchat/nchat.dart';
import 'dart:io';
import 'package:flutter/services.dart';

final _nchat = NChat();

// 초기화 후 푸시 설정
Future<void> setupPush() async {
  // Android: SDK가 자동으로 FCM 토큰 발급 및 등록
  // iOS: AppDelegate에서 APNs 토큰 수신 후 아래와 같이 처리
  
  if (Platform.isIOS) {
    const apnsChannel = MethodChannel('io.nbase.nchat/apns');
    apnsChannel.setMethodCallHandler((call) async {
      if (call.method == 'onAPNsToken') {
        final token = call.arguments as String;
        _nchat.setPushToken(token);
      }
    });
  }
}

// 푸시 상태 설정
Future<void> configurePush() async {
  await _nchat.setPushState(PushState(
    push: true,    // 푸시 알림 활성화
    night: true,   // 야간 알림 허용
    ad: false,     // 광고 알림 비허용
  ));
}

빠른 시작 #

import 'package:nchat/nchat.dart';
import 'package:flutter/material.dart';

class ChatScreen extends StatefulWidget {
  @override
  State<ChatScreen> createState() => _ChatScreenState();
}

class _ChatScreenState extends State<ChatScreen> implements ChatHandler {
  final _nchat = NChat();

  @override
  void initState() {
    super.initState();
    _nchat.addHandler('main', this);
    _initializeChat();
  }

  Future<void> _initializeChat() async {
    // 1. SDK 초기화
    await _nchat.initialize(
      projectId: 'your-project-id',
      region: 'kr',
    );

    // 2. 사용자 연결
    final user = await _nchat.connect(
      userId: 'user-001',
      name: '홍길동',
    );

    // 3. 채널 생성
    final channel = await _nchat.createChannel(
      name: '일반',
      type: 'public',
    );

    // 4. 메시지 전송
    await _nchat.sendMessage(
      channelId: channel.id,
      content: '안녕하세요!',
    );
  }

  // ChatHandler 구현
  @override
  void onMessageReceived(Message message) {
    print('새 메시지: ${message.content}');
    setState(() {
      // UI 업데이트
    });
  }

  @override
  void onConnected() {
    print('서버에 연결됨');
  }

  @override
  void onDisconnected(String reason) {
    print('연결 해제: $reason');
  }

  @override
  void dispose() {
    _nchat.removeHandler('main');
    super.dispose();
  }
}
```;
  }
}
\`\`\`

---

## 리전 설정

| 리전 | 설명 |
|------|------|
| \`kr\` | 한국 프로덕션 서버 |
| \`beta\` | 베타 서버 |
| \`dev\` | 개발 서버 (기본값) |
| \`alpha\` | 알파 서버 |
| \`local\` | 로컬 서버 (localhost:4000) |

---

## 에러 처리

```dart
try {
  await nchat.sendMessage(
    channelId: 'channel-id',
    content: '안녕하세요',
  );
} on ChatException catch (e) {
  print('에러 코드: ${e.code}');
  print('에러 메시지: ${e.message}');
}

파일 업로드 #

final file = File('/path/to/image.jpg');

final message = await nchat.sendFile(
  channelId: 'channel-id',
  file: file,
  message: '이미지 업로드',
  onProgress: (sent, total) {
    print('진행률: ${(sent / total * 100).toStringAsFixed(1)}%');
  },
);

Troubleshooting #

자주 발생하는 문제 #

디버깅 팁 #

1. 로그 확인: debugPrint()로 SDK 응답 로그 확인
2. 네트워크 상태: 인터넷 연결 및 방화벽 설정 확인
3. 리전 설정: 올바른 리전이 설정되었는지 확인
4. SDK 버전: 최신 버전 사용 권장

예제 #

완전한 샘플 앱은 example 디렉토리를 참조하세요.

라이선스 #

Proprietary License - 자세한 내용은 LICENSE 파일을 참조하세요.

이 소프트웨어는 NBase의 독점 소프트웨어이며 NBase 서비스와 연결해서만 사용할 수 있습니다.