푸시 알림 (`push`)

🚀 추가된 버전 : v1.0.0 v1.0.0 v1.0.0
🔔 최신화 일자: 2025-09-25

개요

push 네임스페이스는 푸시 알림 관련 기능을 제공합니다.

푸시 토큰을 nachocode 서버에 등록 및 삭제
로컬 푸시 알림을 예약 및 취소
푸시 토픽 구독 및 취소
디바이스의 구독된 토픽 조회

푸시 알림 사용법을 더 자세히 알아보려면 아래 가이드를 참고해보세요.

푸시 알림 상세 가이드

➡️ 푸시 토큰 가이드 보러가기

➡️ 개인화 푸시 가이드 보러가기

➡️ 토픽 푸시 가이드 보러가기

필수 선행 작업

nachocode SDK로 푸시 알림 기능을 사용하기 위해서는 nachocode 대시보드의
[ 앱 기능 > 푸시 알림 > 설정 ] 탭에서 푸시 알림 설정이 모두 완료된 후 빌드된 경우에만 작동합니다.

푸시 알림 설정하기

➡️ 유저 가이드를 따라 nachocode 푸시 알림 설정을 완료하세요.

타입 정의

`PushTokenResult`

since : v1.6.3

export declare type PushTokenResult =
  | {
      status: 'success';
      statusCode: 201;
      message: string;
    }
  | {
      status: 'error';
      statusCode: number;
      message: string;
      desc: string;
      code: string;
    };

속성명	타입	필수 여부	설명
`status`	`'success' \| 'error'`	✅	푸시 토큰 요청 성공 여부
`statusCode`	`number`	✅	푸시 토큰 결과 상태 코드
`message`	`string`	✅	결과 상세 메시지. (에러 발생 시 사유 반환)
`desc`	`string`	❌	*(optional)* 오류 상세 내용 (에러 발생 시)
`code`	`string`	❌	*(optional)* 오류 코드 (에러 발생 시)

`PushTopicResult`

since : v1.6.0
lastupdated : v1.6.1

export declare type PushTopicResult =
  | {
      status: 'success';
      /**
       * 푸시 토픽 구독 결과 상태 코드
       * - `200` : 성공
       * - `201` : 이미 토픽 구독 중
       * - `202` : 이미 구독 취소된 토픽
       * - `203` : FCM 구독 성공, nachocode 서버 저장 실패
       */
      statusCode: 200 | 201 | 202 | 203;
      message: string;
    }
  | {
      status: 'error';
      /**
       * 푸시 토픽 구독 결과 상태 코드
       * - `400` : 잘못된 요청
       * - `401` : 구독 실패
       * - `402` : 구독 취소 실패
       * - `500` : 내부 오류
       */
      statusCode: 400 | 401 | 402 | 500;
      errorCode: string; // 실패 시 에러 반환
      message: string; // 실패 시 에러 상세 사유 반환
    };

속성명	타입	필수 여부	설명
`status`	`'success' \| 'error'`	✅	푸시 토픽 구독 요청 성공 여부
`statusCode`	`number`	✅	푸시 토픽 구독 결과 상태 코드
`errorCode`	`string`	❌	*(optional)* 오류 코드 (에러 발생 시)
`message`	`string`	✅	결과 상세 메시지. (에러 발생 시 사유 반환)

`LocalPushPayload`

since : v1.4.1

export declare type LocalPushPayload = {
  title: string;
  content?: string;
  link?: string; // link willing to move when clicked
  usingAppIcon?: boolean; // default : true
  scheduledTime?: Date; // sends instantly if not set
  id?: number; // generates if not set
};

속성명	타입	필수 여부	설명
`title`	`string`	✅	푸시 알림의 제목
`content`	`string`	❌	*(optional)* 푸시 알림의 본문 메시지 (지정하지 않으면 제목만 노출)
`link`	`string`	❌	*(optional)* 클릭 시 이동할 URL (지정하지 않으면 앱 열기)
`usingAppIcon`	`boolean`	❌	*(optional)* 앱 아이콘을 푸시 아이콘으로 사용할지 여부 (기본값: `true`)
`scheduledTime`	`Date`	❌	*(optional)* 예약된 발송 시각 (지정하지 않으면 즉시 발송됨)
`id`	`number`	❌	*(optional)* 예약된 푸시를 식별할 ID (지정하지 않으면 자동 생성)

`LocalPushResult`

since : v1.4.1

export declare type LocalPushResult = {
  status: 'success' | 'error';
  statusCode?: string; // error code when failed
  message?: string; // error message when failed
  id?: number; // push notification id
};

속성명	타입	필수 여부	설명
`status`	`'success' \| 'error'`	✅	푸시 알림 예약 성공 여부
`statusCode`	`string`	❌	*(optional)* 오류 발생 시 반환되는 코드
`message`	`string`	❌	*(optional)* 오류 발생 시 반환되는 메시지
`id`	`number`	❌	*(optional)* 예약된 푸시 알림의 ID (취소할 때 사용 가능)

메서드 목록

메서드	설명	추가된 버전
`subscribePushTopic(topic)`	푸시 토픽을 구독합니다.	v1.6.0
`unsubscribePushTopic(topic)`	푸시 토픽 구독을 취소합니다.	v1.6.0
`getSubscriptionList(callback)`	디바이스의 현재 구독 중인 푸시 토픽 목록을 조회합니다.	v1.6.0
`sendLocalPush(payload, callback?)`	로컬 푸시 알림을 예약합니다.	v1.4.1
`cancelLocalPush(id)`	예약된 로컬 푸시 알림을 취소합니다.	v1.4.1
`registerPushToken(userId)`	nachocode 서버에 푸시 토큰을 등록합니다.	v1.0.0
`deletePushToken(userId?)`	nachocode 서버에서 푸시 토큰을 삭제합니다.	v1.0.0

메서드 상세

since : v1.6.0
lastupdated : v1.6.1

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

지정한 푸시 토픽을 구독합니다. 구독이 성공하면 nachocode 서버 API를 통해서 발송하거나 FCM에서 해당 토픽으로 직접 발송한 메시지를 수신할 수 있습니다.

이름	타입	필수 여부	설명
`topic`	`string`	✅	구독할 토픽 이름

타입	설명
`Promise<PushTopicResult>`	구독 성공 또는 실패 정보를 포함함

try {
  const result = await Nachocode.push.subscribePushTopic('event-promotion');
  if (result.status === 'success') {
    console.log('토픽 구독 성공');
  } else {
    console.error('토픽 구독 실패:', result.message);
  }
} catch (err) {
  console.error('토픽 구독 중 오류 발생:', err);
}

`unsubscribePushTopic(topic: string): Promise<PushTopicResult>`

since : v1.6.0
lastupdated : v1.6.1

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

지정한 푸시 토픽 구독을 해지합니다. 이후 해당 토픽으로 발송된 메시지를 더 이상 수신하지 않게 됩니다.

매개변수

이름	타입	필수 여부	설명
`topic`	`string`	✅	해지할 토픽 이름

반환 값

타입	설명
`Promise<PushTopicResult>`	구독 해지 성공 또는 실패 정보를 포함

사용 예제

try {
  const result = await Nachocode.push.unsubscribePushTopic('event-promotion');
  if (result.status === 'success') {
    console.log('토픽 구독 해지 성공');
  } else {
    console.error('토픽 구독 해지 실패:', result.message);
  }
} catch (err) {
  console.error('토픽 구독 해지 중 오류 발생:', err);
}

`getSubscriptionList(callback)`

since : v1.6.0

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

현재 디바이스에서 구독 중인 푸시 토픽 목록을 조회합니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(subscriptionList: string[]) => void`	✅	구독된 토픽 이름 목록을 콜백으로 수신

사용 예제

Nachocode.push.getSubscriptionList(list => {
  console.log('현재 구독 중인 토픽 목록:', list);
});

`sendLocalPush(payload, callback?)`

since : v1.4.1

설명

로컬 푸시 알림을 예약하고, 특정 시각(scheduledTime)에 디바이스에서 푸시 알림을 표시할 수 있습니다. 즉시 발송하거나 예약 발송이 가능하며, 예약된 알림은 id 값을 사용해 취소할 수도 있습니다.

매개변수

이름	타입	필수 여부	설명
`payload`	`LocalPushPayload`	✅	예약할 로컬 푸시 데이터
`callback`	`(result: LocalPushResult) => void`	❌	예약 성공 여부를 반환하는 콜백

반환 값

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

사용 예제

// 1. 즉시 발송 (예약 시간 없이)
// `scheduledTime`을 지정하지 않으면 즉시 발송됩니다.
Nachocode.push.sendLocalPush(
  {
    title: '깜짝 쿠폰 발송!',
    content: '지금 바로 앱에서 확인해보세요!.',
    link: 'https://nachocode.io/pricing',
  },
  result => {
    if (result.status === 'success') {
      console.log(`푸시 알림이 즉시 발송되었습니다.`);
    } else {
      console.error(`푸시 알림 발송 실패: ${result.message}`);
    }
  }
);

// 2. 예약 발송
// `scheduledTime`을 지정하면 해당 시각에 알림이 표시됩니다.
Nachocode.push.sendLocalPush(
  {
    title: '미팅 알림',
    content: '회의 시작 10분 전입니다.',
    scheduledTime: new Date('2025-03-01T10:00:00Z'),
    id: 101,
  },
  result => {
    if (result.status === 'success') {
      console.log(`푸시 알림이 예약되었습니다. (ID: ${result.id})`);
    } else {
      console.error(`푸시 예약 실패: ${result.message}`);
    }
  }
);

`cancelLocalPush(id: number)`

since : v1.4.1

설명

예약된 로컬 푸시 알림을 취소합니다. 취소하려는 푸시 알림의 id 값을 전달해야 합니다.

sendLocalPush에서 반환된 id를 사용합니다.

매개변수

이름	타입	필수 여부	설명
`id`	`number`	✅	취소할 예약된 푸시 알림의 ID

반환 값

해당 메서드는 반환 값을 가지지 않습니다.

사용 예제

// 예약된 푸시 알림 취소
Nachocode.push.cancelLocalPush(101);
console.log('푸시 알림이 취소되었습니다.');

`registerPushToken(userId: string): Promise<PushTokenResult>`

since : v1.0.0
lastupdated : 반환 타입 변경, 내부 로직 최적화 v1.6.3

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

nachocode 서버에 현재 디바이스의 푸시 토큰을 등록합니다. 이때, 특정 사용자(userId)를 식별자로 사용하여 푸시 알림을 해당 사용자에게 전송할 수 있도록 설정합니다.

토큰 등록에 대한 상세 정보

재등록 시 덮어쓰기 동작

같은 디바이스에서 registerPushToken을 다시 호출하면 가장 마지막으로 전달된 userId로 매핑이 덮어씌워집니다
로그아웃 후 다른 계정으로 재로그인 시 호출한다면, 새로운 userId로 자동 업데이트됩니다

userId 매개변수의 유연성

서비스 서버의 실제 사용자 ID가 아니어도 상관없습니다
구별 가능한 고유한 식별자라면 어떤 값이든 사용할 수 있습니다 (ex. 이메일, 닉네임, 커스텀 ID, UUID 등)

디바이스별 관리가 필요한 경우

한 사용자가 여러 디바이스를 사용하는 환경에서 디바이스별로 푸시를 관리하고 싶은 경우
1. UUID로 유니크한 식별자를 생성 후 사용자와 매칭하여 저장 ( 1:N )
2. 서비스 서버의 userId + 고유한 디바이스 ID를 조합하여 유니크한 식별자를 생성 ( 1:N )
  - ex. "user123_device_abc", "user123_ios_main" 등의 형태로 전달

푸시 토큰이란?

푸시 토큰 가이드에서 상세 설명을 확인해보세요.

매개변수

이름	타입	필수 여부	설명
`userId`	`string`	✅	푸시 토큰을 연결할 사용자 ID

반환 값

타입	설명
`Promise<PushTokenResult>`	푸시 토큰 등록 요청의 처리 결과

사용 예제

// ex. 유저의 로그인 성공 시 호출되는 콜백함수
function onLoginSuccess(userId) {
  // ex. userId : "nacho123"
  // "nacho123" 사용자 식별자로 푸시토큰을 nachocode 서버에 등록합니다.
  Nachocode.push.registerPushToken(userId).then(result => {
    if (result.status === 'success') {
      console.log('푸시 토큰이 성공적으로 등록되었습니다.');
    } else {
      console.error(`푸시 토큰 등록 실패: ${result.message}`);
    }
  });
}

`deletePushToken(userId?: string): Promise<PushTokenResult>`

since : v1.0.0
lastupdated : 반환 타입 변경, 내부 로직 최적화 v1.6.3

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

nachocode 서버에서 해당 사용자(userId)와 연결된 푸시 토큰을 삭제합니다.

토큰 삭제 시점에 대한 고려사항

삭제하지 않는 경우

로그아웃된 유저에게도 시스템 알림, 이벤트 알림 등 개인화된 푸시 알림을 전송해야 하는 UX인 경우
registerPushToken 함수는 같은 디바이스에서 다시 호출될 때 가장 마지막 userId로 매핑을 덮어씌우므로, 로그아웃 후 다른 계정으로 재로그인 시 자동으로 새로운 계정으로 매핑됩니다.

삭제하는 경우

푸시 알림 수신 거부 설정 시 토큰 매핑을 삭제하여 알림을 완전히 차단
로그아웃된 유저에게 개인화 푸시 알림을 보내지 않는 UX이거나 보내면 안 되는 경우 매핑을 삭제하여 실수로 발송되는 것을 방지
앱 탈퇴나 계정 삭제 시 개인정보 보호를 위한 토큰 매핑 제거

대부분의 경우 로그아웃 시마다 토큰을 삭제할 필요는 없으며, 앱의 UX 정책에 따라 선택적으로 사용하세요.

푸시 토큰이란?

푸시 토큰 가이드에서 상세 설명을 확인해보세요.

매개변수

이름	타입	필수 여부	설명
`userId`	`string`	❌	삭제할 푸시 토큰이 연결된 사용자 ID

반환 값

타입	설명
`Promise<PushTokenResult>`	푸시 토큰 삭제 요청의 처리 결과

사용 예제

// 현재 디바이스 토큰 삭제 (userId 생략 가능)
Nachocode.push.deletePushToken().then(result => {
  if (result.status === 'success') {
    console.log('현재 디바이스의 푸시 토큰이 삭제되었습니다.');
  } else {
    console.error(`푸시 토큰 삭제 실패: ${result.message}`);
  }
});

// ex. 유저의 로그아웃 시 호출되는 콜백함수
function onLogout(userId) {
  // ex. userId : "nacho123"
  // "nacho123" 사용자 식별자에 해당하는 푸시 토큰을 삭제합니다.
  Nachocode.push.deletePushToken(userId).then(() => {
    if (result.status === 'success') {
      console.log('유저 푸시 토큰이 성공적으로 삭제되었습니다.');
    } else {
      console.error(`푸시 토큰 삭제 실패: ${result.message}`);
    }
  });
}

개요​

필수 선행 작업​

타입 정의​

PushTokenResult​

PushTopicResult​

LocalPushPayload​

LocalPushResult​

메서드 목록​

메서드 상세​

subscribePushTopic(topic: string): Promise<PushTopicResult>​

설명​

매개변수​

반환 값​

사용 예제​

unsubscribePushTopic(topic: string): Promise<PushTopicResult>​

설명​

매개변수​

반환 값​

사용 예제​

getSubscriptionList(callback)​

설명​

매개변수​

사용 예제​

sendLocalPush(payload, callback?)​

설명​

매개변수​

반환 값​

사용 예제​

cancelLocalPush(id: number)​

설명​

매개변수​

반환 값​

사용 예제​

registerPushToken(userId: string): Promise<PushTokenResult>​

설명​

재등록 시 덮어쓰기 동작​

userId 매개변수의 유연성​

디바이스별 관리가 필요한 경우​

매개변수​

반환 값​

사용 예제​

deletePushToken(userId?: string): Promise<PushTokenResult>​

설명​

삭제하지 않는 경우​

삭제하는 경우​

매개변수​

반환 값​

사용 예제​

개요

필수 선행 작업

타입 정의

`PushTokenResult`

`PushTopicResult`

`LocalPushPayload`

`LocalPushResult`

메서드 목록

메서드 상세

`subscribePushTopic(topic: string): Promise<PushTopicResult>`

설명

매개변수

반환 값

사용 예제

`unsubscribePushTopic(topic: string): Promise<PushTopicResult>`

설명

매개변수

반환 값

사용 예제

`getSubscriptionList(callback)`

설명

매개변수

사용 예제

`sendLocalPush(payload, callback?)`

설명

매개변수

반환 값

사용 예제

`cancelLocalPush(id: number)`

설명

매개변수

반환 값

사용 예제

`registerPushToken(userId: string): Promise<PushTokenResult>`

설명

재등록 시 덮어쓰기 동작

userId 매개변수의 유연성

디바이스별 관리가 필요한 경우

매개변수

반환 값

사용 예제

`deletePushToken(userId?: string): Promise<PushTokenResult>`

설명

삭제하지 않는 경우

삭제하는 경우

매개변수

반환 값

사용 예제