앱인토스 기능성 푸시, 3주 동안 밟은 시행착오 정리

앱인토스 미니앱에는 서버 없이도 쓸 수 있는 기능성 정기 푸시가 있습니다. “매일 저녁 8시에 오늘의 퍼즐이 준비됐어요” 같은 알림을 토스가 대신 보내 주고, 광고성이 아니라 무료입니다. 재방문을 만들기에 이보다 싼 수단이 없어서 8월 중순부터 앱마다 붙이고 있었는데, 3주 동안 꽤 여러 번 넘어졌습니다. 오늘 마지막(이라고 믿는) 사고를 하나 더 고치면서, 처음부터 알았으면 한 번에 끝났을 것들을 정리해 둡니다.

대상은 주스 스피너·병 돌리기 같은 모임 앱부터 스도쿠·탭 버드 등 미니게임 18종까지입니다.

구조부터: 동의문과 템플릿은 다른 물건이다

콘솔에서 정기 푸시를 만들려면 두 가지가 필요합니다.

1. 알림동의문: “매일 저녁 8시에 오늘의 스도쿠 알림을 보내드릴까요?”라는 약관. 사용자가 앱 안에서 이 문구에 동의해야 발송 대상이 됩니다.
2. 템플릿(발송 그룹): 실제로 나가는 메시지. 제목·내용·랜딩 링크·요일·시각을 갖고, 어느 동의문의 동의자에게 보낼지를 가리킵니다.

발송 대상은 세그먼트를 따로 고르는 게 아니라 동의문이 곧 세그먼트입니다. 여기서 이 글의 결론이 미리 나옵니다. 동의문과 템플릿을 아무리 예쁘게 만들어도, 앱이 사용자에게 동의를 물어보지 않으면 대상은 0명입니다.

1차 시행착오 (8월): 콘솔 규칙에 부딪히기

주스 스피너에 “월~토 저녁 8시” 모임 알림을 붙이던 때입니다.

• 같은 요일·시각의 동의문은 두 번 만들 수 없습니다. 시행착오로 금요일 20시 동의문을 하나 만들고 나서 월~토로 바꾸려니 “이미 등록된 알림동의문과 발송 시점이 유사해요”로 막혔습니다. 요일 조합을 바꿔서 새로 만들어야 했고, 처음 만든 동의문은 아무 앱도 참조하지 않는 고아가 됐습니다. 무해하지만 지울 수는 없습니다.
• 승인된 템플릿은 수정도 취소도 안 됩니다. “이미 승인된 메시지는 수정할 수 없어요.” 시각을 바꾸려면 새 템플릿을 만들고, 옛 것은 콘솔 웹에서 비활성화해야 합니다.
• 발송 코드는 재사용 불가, 그리고 앱 이름 접두어가 필수입니다. juice-spinner-처럼 appName으로 시작하지 않으면 거부됩니다. 이 코드가 뒤에서 한 번 더 중요해집니다.
• AI 검수는 비결정적입니다. 같은 문구가 앱 A에서는 통과하고 앱 B에서는 “명령형 어미” 지적으로 반려됐습니다. 반려 사유를 읽고 문구를 조금 바꿔 다시 넣으면 대개 통과합니다. 같은 페이로드를 그대로 다시 넣어도 통과하는 경우가 있었을 정도라, 반려 한 번에 설계를 뒤집지 않는 게 맞습니다.
• 정기 템플릿은 기본 목록 조회에 안 나옵니다. 스마트 메시지 필터를 켜고 기능성 타입으로 조회해야 보입니다. 처음엔 “만든 게 사라졌나” 하고 한참 찾았습니다.

2차 시행착오 (9월 초): 문구 규칙 외우기

미니게임 6종에 “매일 저녁 8시” 알림을 한 번에 붙이면서 입력 규칙이 굳었습니다.

• 제목은 7자 이내, 마침표로 끝낼 수 없음.
• 내용은 25자 이내, 반드시 “요.”로 끝나야 하고, 개행·느낌표·물결·이모지 금지.
• 그룹 코드와 그 안의 템플릿 코드는 똑같이 넣어야 합니다. 다르면 “동일하게 입력”, 비우면 “발송 코드 입력”으로 거부.
• 동의문의 발송 시점 문구에 시각을 명시해야 합니다. “오늘의 퍼즐이 준비되었을 때”만 쓰면 “동의문에 발송 시각 미명시”로 반려됐고, “매일 저녁 8시, 오늘의 퍼즐이 준비되었을 때”로 바꾸자 통과했습니다.
• 첫 발송 시각은 반드시 미래여야 하고, 승인되면 그 자체로 예약이 잡힙니다. 별도 “발송” 버튼을 찾지 마세요.

여기까지 하고 나서 여섯 앱의 템플릿이 전부 승인되고 상태가 “발송 완료”로 바뀌는 것을 보며 끝났다고 생각했습니다.

3차, 가장 큰 사고 (오늘): 발송은 됐는데 받은 사람이 없다

오늘 새로 출시 준비 중인 10종에 같은 작업을 하다가 문득 확인했습니다. 지난 6종은 매일 20시에 “발송 완료” 상태였는데, 실제로 동의한 사용자가 몇 명인가? 답은 0명이었습니다.

이유는 단순했습니다. 동의 시트를 띄우는 코드가 게임 어디에도 없었습니다. 주스 스피너와 병 돌리기는 처음 만들 때 SDK의 동의 요청 함수를 호출하는 코드를 넣었지만, 그 뒤에 만든 미니게임들은 공용 브릿지를 복사해 쓰면서 그 부분이 빠졌고, 콘솔에서 템플릿이 승인되는 것만 보고 넘어갔습니다. 콘솔은 대상이 0명이어도 “발송 완료”라고 표시합니다.

고친 방법은 이렇습니다.

• 공용 패키지에 createPushConsent() 하나를 추가했습니다. 게임은 판이 끝나는 지점에서 noteRun() 한 줄만 부릅니다.
• 안에서 세션 3판 이상 + 3분 경과 뒤에, 기기당 한 번만 동의 시트를 띄웁니다. 앱에 들어오자마자 시트를 띄우면 검수에서 반려되기 때문에(실제로 반려된 적이 있습니다), 충분히 놀아 본 사람에게만 묻습니다.
• 어떤 동의문을 물어볼지는 콘솔 템플릿의 그룹 코드로 지정합니다. 위에서 “발송 코드가 한 번 더 중요해진다”고 한 이유입니다. 이 코드는 래퍼의 작은 JSON 파일로 빼서, 게임 코드는 앱 이름을 몰라도 되게 했습니다.
• 토스가 아닌 환경(Google Play, 웹)이나 브릿지가 동의 요청을 지원하지 않는 경우엔 아무 동작도 하지 않습니다.

18종에 일괄 이식하고 번들을 다시 올렸습니다. 라이브 8종은 검수 중이고, 신규 10종은 첫 출시 번들에 포함됩니다.

출시 전 앱에도 미리 해 둘 수 있는 것

신규 10종을 준비하면서 확인한 순서입니다.

• 알림동의문은 앱 심사 전에도 만들 수 있습니다. 앱 정보가 검토 중인 상태에서 10개 전부 생성됐습니다.
• 템플릿은 앱이 운영중(OPEN) 상태여야 만들 수 있습니다. 그래서 템플릿 코드만 먼저 정해 앱 코드에 넣어 두고, 출시 후 같은 코드로 템플릿을 만들면 됩니다.
• 광고성 스마트 발송(세그먼트 캠페인)은 API가 없어 콘솔 웹에서만 됩니다. 이것도 출시 후의 일입니다.

체크리스트

다음에 새 앱을 붙일 때 이 순서면 한 번에 끝납니다.

1. 동의문 생성: 요일·시각 고정, 발송 시점 문구에 시각 명시. 앱 심사 전에 해도 됨.
2. 템플릿 코드 확정: 앱이름-용도_시각 형태로 정하고 앱 코드(래퍼 JSON)에 먼저 넣기.
3. 게임에 동의 요청 훅 넣기: 판 종료 시 호출, 3판+3분 게이트, 기기당 1회.
4. 앱 출시(OPEN) 후 템플릿 생성: 제목 7자·내용 25자·”요.” 종결, 그룹 코드 = 템플릿 코드 = 2번의 코드.
5. 반려되면 사유대로 문구만 고쳐 재시도. 승인되면 예약 완료.
6. 며칠 뒤 동의자 수를 확인. “발송 완료”는 대상이 0명이어도 뜬다.

콘솔에서 승인 뱃지를 보는 순간이 끝이 아니라, 사용자 폰에서 동의 시트가 뜨는 순간이 끝이었습니다. 이 한 줄을 3주 만에 배웠습니다.