웹훅 캠페인으로 푸시 알림함 구현하기

이 페이지에서는 웹훅 캠페인을 활용해 서비스 내 푸시 알림함을 구현하는 방법을 설명합니다.

웹훅 캠페인을 활용하면, 실제로 발송된 푸시 메시지 정보를 당사 서버로 전달하여 서비스 내 푸시 알림함을 구성할 수 있습니다.

사전 작업

푸시 알림함 구현 전 아래 사항이 준비되어 있어야 합니다.

• Push Notification 연동이 완료되어 있어야 합니다.

• 푸시 캠페인을 생성 및 발송할 수 있어야 합니다.

• 웹훅을 수신할 당사 서버 API가 준비되어 있어야 합니다.

• 알림함 데이터를 저장할 DB 또는 저장소가 준비되어 있어야 합니다.

1. 웹훅 캠페인 생성

푸시 알림함에 저장할 데이터를 서버로 전달하기 위해 웹훅 캠페인을 생성합니다. 웹훅 캠페인 생성 시 아래와 같이 설정합니다.

1-1. 스케줄

웹훅 캠페인의 발송 방식은 이벤트 기반 발송으로 설정합니다.

트리거 이벤트는 메시지 발송 이벤트로 설정합니다.

추가 조건은 아래와 같이 설정합니다.

• 캠페인 타입: 푸시

• 캠페인 발송 결과 여부: O

즉, 푸시 메시지가 실제 발송된 경우에만 웹훅 캠페인이 실행되도록 설정합니다.

기본값으로 세팅되어 있는 캠페인 피로도 관리 조건을 해제합니다.

1-2. 타겟

타겟은 전체로 설정합니다.

이 문서의 방식에서는 실제 필터링은 원본 푸시 캠페인에서 이루어지고, 웹훅 캠페인은 푸시 발송 결과 이벤트를 받아 후처리하는 역할을 합니다.

1-3. 본문

본문에서는 웹훅 캠페인에서 호출할 당사 서버 API를 입력합니다.

// 예시
POST https://example.com/api/push-inbox/webhook

당사 서버에서는 이 API를 통해 푸시 알림함에 저장할 데이터를 전달받게 됩니다.

웹훅 Body에는 푸시 알림함에 저장할 데이터를 Liquid 문법으로 작성합니다. 일반적으로 아래와 같은 정보들을 함께 전달하는 것을 권장합니다.

아래 예시는 자주 사용하는 Liquid 변수 예시입니다.

연동에 필요한 다른 변수가 있는 경우 마켓탭 서비스 지원팀을 통해서 안내 요청을 부탁드립니다.

liquid 변수	설명
user.user_id	유저 식별자
event.mkt_title	푸시 제목
event.mkt_body	푸시 내용
event.mkt_deepLink	푸시 클릭 링크
event.mkt_imageUrl	푸시 이미지
event.event_datetime	푸시 발송 시각 (UTC)
event.mkt_unique_send_id	중복 제거를 위한 키

Example

{
    "userId": "{{user.user_id}}",
    "title": "{{event.mkt_title}}",
    "content": "{{event.mkt_body}}",
    "link": "{{event.mkt_deeplink}}",
    "imageUrl": "{{event.mkt_imageUrl}}",
    "datetime": "{{event.event_datetime}}",
    "dedupeKey": "{{event.mkt_unique_send_id}}"
}

웹훅 캠페인 설정이 완료되면 캠페인을 생성한 뒤 실행합니다.

이후 푸시가 실제로 발송될 때마다, 설정한 조건에 따라 웹훅 캠페인이 함께 실행되며 당사 서버 API가 호출됩니다.

당사 서버에서는 전달받은 데이터를 저장한 뒤, 앱 또는 웹에서 푸시 알림함 형태로 노출할 수 있습니다.

2. 중복 제거

중복 제거는 왜 필요한가요?

푸시 토큰은 앱 업데이트와 같은 상황에서 변경될 수 있습니다. 이 경우 일시적으로 기존 토큰이 유효한 상태로 남아있을 수 있습니다.

대부분의 경우 오래된 토큰은 실제로는 무효한 토큰이기 때문에 발송 실패로 남지만, 일시적으로는 발송 성공으로 보일 수 있어 같은 유저에 대해 웹훅이 두 번 트리거될 수 있습니다.

따라서 웹훅으로 호출되는 고객사 서버 API에서는 중복 제거 처리를 해주시는 것을 권장드립니다. 별도의 중복 제거 로직이 없다면 푸시 알림함에 동일한 메시지가 여러 개 저장될 수 있습니다.

중복 제거 처리 방법

1-3의 Liquid 변수 중 event.mkt_unique_send_id 를 이용하면 중복 제거를 할 수 있습니다.

같은 유저에 대해 해당 값이 존재하는 경우 저장하지 않도록 구현해주시면 됩니다.

같은 유저에 대해 여러 개의 푸시가 발송되는 경우에는 일반적으로 거의 동시에 발송이 되기 때문에 DB에 유니크 제약을 걸어두는 것을 권장드립니다.

예를 들어, 아래와 같이 유니크 키를 둘 수 있습니다.

UNIQUE(user_id, unique_send_id)

이렇게 하면 동일 요청이 동시에 여러 번 들어와도 DB 레벨에서 중복 저장을 방지할 수 있습니다.