✦Spectra SDK Docs

Notification JS SDK

Notification JS SDK는 Delivery API를 내부적으로 사용하더라도 사용자에게는 알림 경험으로 보인다.

현재 JS SDK는 이메일 인증 코드 요청/검증과 iOS/Android push device registration을 제공한다.

설치

npm install @spectra-platform/notification-sdk

현재 배포 버전은 0.1.0이다.

API tree

Notification JS SDK
├─ Client setup
│  ├─ new SpectraNotificationClient(config)
│  └─ createSpectraNotificationClient(config)
├─ Email verification
│  ├─ sendEmailCode(options)
│  └─ verifyEmailCode(options)
└─ Push registration
   └─ registerForPush(options)

Auth 객체와 함께 사용

Notification SDK가 호출하는 API는 Auth SDK의 service access token을 사용한다. 기본 Notification SDK 설정은 Secret Key를 요구하지 않고, Auth 객체를 주입한다.

기본 앱 코드는 Delivery endpoint URL을 설정하지 않는다. endpoint override는 로컬 producer 테스트나 Platform CS가 요청한 진단에서만 다룬다.

import { SpectraAuthClient } from "@spectra-platform/auth-sdk";
import { SpectraNotificationClient } from "@spectra-platform/notification-sdk";

const auth = new SpectraAuthClient({
  projectId: "proj_...",
  // Current Auth SDK compatibility field. It is not a primary product key.
  publicClientId: "app_...",
  environment: "test",
  redirectUri: "https://myapp.example.com/auth/callback",
});

const notification = new SpectraNotificationClient({
  projectId: "proj_...",
  environment: "test",
  auth,
});

API detail

new SpectraNotificationClient(config)

Notification client를 만든다.

createSpectraNotificationClient(config)

new SpectraNotificationClient(config)와 같은 결과를 반환하는 factory helper다.

sendEmailCode(options)

이메일 인증 코드를 요청한다. SDK UX Contract v1의 기본은 direct body 입력이다. SDK 내부에서는 Auth 객체에서 필요한 권한을 받아 Delivery email verification API를 호출하지만, 기본 앱 코드는 service token audience나 Delivery endpoint를 알 필요가 없다.

const challenge = await notification.sendEmailCode({
  email: "user@example.com",
  subject: "Your sign-in code",
  text: "Your code is {{code}}.",
  expiresInSeconds: 600,
  metadata: {
    locale: "ko-KR",
  },
});

console.log(challenge.verificationId, challenge.expiresAt);

주요 입력:

templateId와 templateVersion은 관리형 템플릿을 이미 운영하는 팀을 위한 advanced 선택 사항이다. 현재 설치된 package가 아직 direct body 입력을 받지 못하면 소비 앱에 template 생성을 요구하지 말고 SDK/서비스 정렬 작업으로 분리한다.

verifyEmailCode(options)

사용자가 입력한 인증 코드를 검증한다.

const result = await notification.verifyEmailCode({
  verificationId: challenge.verificationId,
  code: "123456",
});

console.log(result.status, result.verifiedAt);

주요 입력:

registerForPush(options)

iOS APNs 또는 Android FCM provider token을 현재 app-user의 device record로 등록한다.

const device = await notification.registerForPush({
  platform: "ios",
  providerToken: apnsToken,
  appIdentifier: "kr.spectra.modo-camp",
  locale: "ko-KR",
});

주요 입력:

권한 경계

Client SDK는 내 이메일 인증, 내 기기 등록, 내 알림 상태처럼 app-user token으로 가능한 작업만 담당한다.

운영성 발송, bulk 발송, 관리자성 push 발송은 기본 browser SDK 예시 범위가 아니다. Secret Key 사용 위치는 소비 프로젝트의 앱 아키텍처 결정이며, 문서는 Secret Key가 환경(test/live)에 묶인 만료일 없는 비밀값이고 최초 발급/재발급 직후 1회만 보여진다는 사실을 전제로 한다.

Console의 기본 key 모델은 환경에 묶인 Project ID + Secret Key이며, Email/Push 사용 가능 여부는 Project dashboard service toggle로 결정한다.

기능별 preset 이름은 새 기본 UX에서 사용하지 않는다.

아직 별도 검증이 필요한 것