Apache-2.0 · 셀프호스트

토큰이 아니라
사람에게 보내는 푸시

Notikit 은 FCM 위에 사용자 identity 레이어를 얹은 푸시 알림 툴킷입니다. 기기 토큰을 관리하는 대신 “유저 X 에게” 보내면, 그 사람의 모든 기기로 갑니다. 서버·콘솔·SDK 를 우리 인프라에 그대로 띄웁니다.

로컬에서 띄워 보기 GitHub 에서 보기

왜 토큰이 아니라 사람인가

FCM 은 기기 토큰 단위로 동작합니다. 사용자가 폰을 바꾸거나, 태블릿을 추가하거나, 로그아웃하는 순간 “이 토큰은 누구 것인가”를 앱이 직접 관리해야 합니다.

FCM 만 쓸 때

// 이 사람의 토큰을 전부 찾아서, 죽은 건 골라내고…
for (const token of await findTokens(userId)) {
  await messaging.send({ token, notification })
}

Notikit

// 사람에게 보낸다. 기기는 Notikit 이 안다
await notikit.send({
  type: "single", target: "user-42",
  title: "주문이 출발했어요", body: "{{name}}님, 내일 도착 예정입니다"
})

한 번에 갖춰진 것

발송 API 만이 아니라, 운영하면서 결국 만들게 되는 것들까지.

유저 · 멀티디바이스

계정 하나에 여러 기기를 묶고, identity_hash(HMAC)로 남의 계정에 기기를 붙이는 것을 막습니다. 무효 토큰은 발송 응답을 보고 자동 정리합니다.

개인 · 토픽 · 전체 발송

예약 발송, 받는 사람 현지 시각 발송, 조용한 시간, 딥링크, 언어별 문구, {{name}} 같은 개인화 변수.

세그먼트

유저 속성 규칙과 “최근 7일 안에 눌렀다” 같은 행동 규칙으로 대상을 고릅니다. 수신 거부 목록은 항상 먼저 걸러집니다.

저니 · A/B

이벤트로 시작하는 자동화 흐름, “눌렀는가”에 따른 분기, 스텝별 성과. A/B 는 표본 발송 후 승자를 자동으로 본발송합니다.

도달 · 참여 분석

발송·수신·클릭·전환을 캠페인과 스텝 단위로. 대조군(홀드아웃)으로 푸시가 실제로 만든 차이를 봅니다.

멀티테넌트 콘솔

조직 → 프로젝트, 환경 분리, 프로젝트별 Firebase 자격증명을 AES-GCM 으로 격리 저장. 감사 로그와 역할 권한. 25개 언어.

플랫폼별 SDK

SDK 는 플랫폼마다 저장소가 따로 있습니다. 모두 Apache-2.0 입니다.

플랫폼	설치	상태
iOS (Swift)	Swift Package Manager `https://github.com/mintsoft-opensource/notikit-ios`	사용 가능
Android (Kotlin)	JitPack `com.github.mintsoft-opensource:notikit-android:0.1.0`	사용 가능
React Native	`@notikit/react-native` + `@react-native-firebase/messaging` iOS · Android 한 코드로. 백그라운드 수신 보고까지	npm 배포 예정
Web	`@notikit/web-sdk` — 브라우저 Web Push, 서비스 워커 포함	npm 배포 예정
React · Next.js	`@notikit/react` — Provider 와 hooks	npm 배포 예정
Flutter (Dart)	`notikit`	pub.dev 배포 예정

시작하기

Docker 만 있으면 됩니다. Firebase 자격증명이 없으면 실제 발송 대신 로그만 남기는 모드로 돌아서, 먼저 둘러보기에 좋습니다.

1받고 설정하기

비밀값 세 개만 채우면 됩니다: 암호화 키(32자 이상), 관리자 토큰, DB 비밀번호.

git clone https://github.com/mintsoft-opensource/notikit
cd notikit
cp .env.example .env

2띄우기

마이그레이션 → 웹 → 워커 순으로 올라옵니다. 웹이 DB 준비까지 확인해야 healthy 가 됩니다.

docker compose up -d --build
docker compose ps

3콘솔 열기

첫 관리자 계정을 만들고 프로젝트를 추가하면 API 키가 나옵니다. API 문서는 콘솔의 /docs 에 있습니다.

open http://localhost:3000

운영 서버에는 소스 빌드 대신 서명된 이미지(ghcr.io/mintsoft-opensource/notikit)와 docker-compose.prod.yml 을 씁니다. 자세한 절차는 README 를 보세요.

토큰이 아니라사람에게 보내는 푸시