NCloud Chat Flutter SDK

pub package

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

목차

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

개요

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

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

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

기능 설명
편리한 대시보드 모바일에서도 접속할 수 있는 NCloud Chat 대시보드 화면에서 메시지 통계, 채팅 채널 관리, 악성 사용자 차단, 욕설 및 비속어 필터링, 채팅 메시지 다운로드 및 검색 가능
1:1 채팅 특정 사용자에게 알림 메시지 전달 가능, 사용자 간 1:1 채팅 시스템을 안정적으로 지원
다국어 메시지 실시간 자동 번역 다양한 나라의 사람들과 편하게 대화할 수 있도록 네이버의 강력한 AI 번역 솔루션인 파파고와 연동 기능 제공, 자동 번역 기능을 활용하여 글로벌 사용자와 쉽게 커뮤니티 구축 가능
비속어 차단 및 악성 사용자 차단 건강한 채팅 환경 구성을 위해 욕설 및 비속어가 포함된 메시지 필터링 및 삭제 가능, 악성 사용자(플레이어)는 일정 기간 동안 채팅을 이용할 수 없도록 설정 가능
실시간 분석 지표 사용자 접속 현황, 메시지 전달 현황 등을 분석할 수 있도록 다양한 분석 지표 제공
푸시 알림 FCM (Android) / APNs (iOS) 지원으로 오프라인 사용자에게도 메시지 알림 전송

요구 사양

Flutter

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

Android

  • minSdkVersion 21 이상
  • targetSdkVersion 34 권장

iOS

  • iOS 12.0 이상
  • Xcode 14.0 이상

지원 플랫폼

플랫폼 지원 상태
Android ✅ 정식 지원
iOS ✅ 정식 지원
Web ⚠️ 제한적 지원
Windows/macOS/Linux ⚠️ 실험적 지원

설치

`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

자주 발생하는 문제

문제 원인 해결 방법
연결 실패 잘못된 Project ID 대시보드에서 Project ID 확인
메시지 전송 실패 채널 미구독 subscribe() 호출 후 메시지 전송
푸시 알림 미수신 토큰 미등록 또는 권한 없음 setPushToken() 호출 및 알림 권한 확인
iOS 푸시 미동작 APNs 인증서 미설정 Apple Developer Console에서 인증서 등록
Android 푸시 미동작 FCM 설정 누락 google-services.json 파일 확인

디버깅 팁

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

예제

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

라이선스

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

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

Libraries

nchat