`Notification.requestAgreement`가 `NOTIFICATION_AGREEMENT_FAILED`로 실패합니다 (문서에 없는 에러 코드)

개발
1

이 글의 성격은 무엇인가요?

질문 / 문제 해결

내용을 설명해주세요

안녕하세요. 미니앱 알림 동의 요청이 문서에 정의되지 않은 에러 코드로 실패해
문의드립니다. SDK 시그니처가 서로 다른 미니앱 두 개에서 같은 증상이 나서
클라이언트 구현 문제가 아닐 가능성을 보고 있습니다.

증상

1) 하루 한 장 타로 — miniAppId 58816

동의 요청이 아래 에러로 실패합니다.

NOTIFICATION_AGREEMENT_FAILED: 알림 동의에 실패하였습니다.
  • SDK: @apps-in-toss/web-framework의 requestNotificationAgreement
  • templateCode: one-card-tarot-today-reminder / termsId: 117248
  • 재현: 실기기(SM-S948N, 토스 앱 5.275.0) → 미니앱 설정 화면 →
    “리마인더 알림받기” 탭
  • 에러 확인용 진단 배포(라이브 아님):
    deploymentId 01a05ab8-f6cd-7f87-b280-805d57b79bb0,
    versionName 20260901-7 (2026-09-01)

2) 나만 이래? — miniAppId 60265

동의 요청이 타로와 완전히 같은 에러로 실패합니다.

NOTIFICATION_AGREEMENT_FAILED: 알림 동의에 실패하였습니다.
  • SDK: Notification.requestAgreement (@apps-in-toss/web-framework 3.0.2,
    isSupported() 가드를 통과한 뒤 onError 콜백에서 위 코드를 받음)
  • templateCode: is-it-daily-reminder / termsId: 117077
  • 라이브 번들 20260825-23 (APPROVED, lastDeployedAt 2026-08-31 08:26)
  • 동의 요청 코드는 실제로 실행되고 있습니다 — 자체 이벤트 로그가 9건
    기록됐습니다(8/25 2건, 8/31 3건, 9/1 4건).
  • 에러 확인용 진단 배포(라이브 아님): deploymentId
    01a06ac9-b369-7cb4-a7a7-ab12ecbe571c, versionName 20260904-24
    (2026-09-04)

여쭙고 싶은 것

  1. NOTIFICATION_AGREEMENT_FAILED의 정의와 발생 조건을 알려주실 수 있을까요?
    개발자센터 문서에는 UNSUPPORTED_APP_VERSION만 정의돼 있고 이 코드는 어디에도
    설명이 없습니다.
  2. 위 두 앱은 SDK 시그니처가 다르고(requestNotificationAgreement vs
    Notification.requestAgreement) 구현도 별개인데 결과가 동일합니다.
    클라이언트 쪽에서 더 확인해볼 지점이 있을까요?

이미 확인한 것 (중복 안내는 생략해 주세요)

  • 클라이언트 코드: 콘솔에 등록한 templateCode와 코드 상수가 일치하고,
    isSupported()를 통과한 뒤 onError 경로에서 위 코드를 받습니다.
  • 콘솔 등록: push_notification_agreement_list로 termsId와 발송 시각이 코드
    설정과 일치함을 확인했습니다.
  • OS 알림 권한: 허용 상태입니다.
  • 토스 앱 버전: 테스트 기기 5.275.0. 두 미니앱 실사용자 앱 버전 분포도 최저
    5.251.0(타로) / 5.268.0(is-it)이라 MIN_TOSS_APP_VERSION 5.255.0 요건은
    사실상 전원 충족합니다.
  • miniapp_release_status: releaseDecision: ALLOWED.

감사합니다.

2

안녕하세요 :slight_smile:
NOTIFICATION_AGREEMENT_FAILED 는 잘못된 템플릿 코드를 사용할 경우 발생할 수 있습니다.
확인해보니, 나만 이래? 앱의 템플릿 코드는 is-it-daily-reminder-default 로 확인됩니다.

하루 한장 타로앱의 템플릿 코드는 one-card-tarot-today-reminder-v1 로 생성해주셨네요.
참고 부탁드립니다.

3

답변 주셔서 감사합니다. 알려주신 대로 templateCode를 정확히 그 값으로 맞춰 재검증했고, 결과를 공유드립니다. 먼저 정정할 게 있습니다 — 첫 글에서 "SDK 시그니처가 다른 두 앱이 같은 에러를 낸다"를 근거로 들었는데,

저희가 다시 코드를 보니 두 앱 모두 결국 같은 브릿지 메서드 (`requestNotificationAgreement`)를 호출하고 있어서 이 관측 자체가 의미 있는 근거는 아니었습니다. 이 부분은 무시해 주세요.

## 적용한 수정과 재검증 결과

| 미니앱 | 기존 코드 값 | 알려주신 값 (적용함) | 콘솔 "스마트 발송 → 기능성 탭"에서 직접 확인한 값 |

|—|—|—|—|

| 하루 한 장 타로 | `one-card-tarot-today-reminder` | `one-card-tarot-today-reminder-v1` | `one-card-tarot-today-reminder-v1` (일치) |

| 나만 이래? | `is-it-daily-reminder` | `is-it-daily-reminder-default` | `is-it-daily-reminder-default` (일치) |

알려주신 값 그대로 코드에 반영해 재빌드 후 실기기로 재검증했는데, 두 앱 다 **여전히 같은 에러**가 재현됐습니다. 이후 저희가 직접 콘솔 화면에서 발송 코드 원문을 대조해봤는데 코드 값과 정확히 일치했습니다 — templateCode 오타는 아니었던 것으로 최종 확인됐습니다.

- 하루 한 장 타로 — 재검증 배포(라이브 아님): deploymentId

`01a06b39-e0c3-763b-82bc-da28207ecb24`, versionName `20260904-8`

- 나만 이래? — 재검증 배포(라이브 아님): deploymentId

`01a06b3d-d48d-7b97-bcfa-516b410e40c7`, versionName `20260904-26`

추가로 확인한 게 있습니다 — 콘솔의 캠페인 발송 로그를 보니 두 캠페인 모두 “발송됨”(활성) 상태로, 생성일(8/24~25)부터 오늘까지 **하루도 빠짐없이 정확히 스케줄대로 발동**하고 있었습니다. 다만 매일 "발송 완료: 0 | 발송 실패: 0"으로, **발송 대상이 매번 0명**이었습니다. 즉 캠페인 설정 문제는 아니고, **동의(consent) 등록 자체가 11일 동안 단 한 건도 성공한 적이 없다**는 쪽으로 원인이 좁혀졌습니다. 이 부분은 콘솔· 계정 쪽 문의라 채널톡에도 별도로 올렸습니다.

감사합니다.