모바일 푸시 구독 API
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
인증된 사용자의 할 일 항목에 대한 푸시 알림을 받도록 모바일 디바이스를 등록합니다. 알림 전달은 사용자 환경설정 API (mobile_push_working_hours_*)를 통해 근무 시간으로 제한할 수 있습니다.
히스토리
- GitLab 19.3에서
mobile_push_registration_api라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. - 알림 전달이 GitLab 19.3에서
mobile_push_notifications_dispatch와mobile_push_notifications라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. - 배지 전용 업데이트가 GitLab 19.6에서
mobile_push_badge_sync라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. - 기능 플래그
mobile_push_notifications가 GitLab 19.6에서 제거되었습니다.
인증된 사용자의 할 일 항목에 대한 푸시 알림을 받도록
모바일 디바이스를 등록합니다. 모든 푸시 알림은 할 일 항목 하나에
대응합니다.
디바이스를 등록하는 것만으로는 알림이 전달되지 않습니다. 알림 전달은
mobile_push_notifications_dispatch 기능 플래그로 인스턴스에 대해
별도로 활성화합니다.
알림 전달은 사용자 환경설정 API
(mobile_push_working_hours_*)를 통해 근무 시간으로 제한할 수 있습니다. 근무 시간 밖에
생성된 할 일은 개별적으로 전송되지 않으며, 근무 시간이 시작될 때
등록된 모든 디바이스에 요약 알림 하나가 전송됩니다.
모든 알림은 사용자의 대기 중인 할 일 수를 앱 배지로 포함합니다.
mobile_push_badge_sync 기능 플래그도 활성화되어 있으면, 할 일 항목을 만들지 않고
이 수를 바꾸는 변경(할 일 항목 완료 처리 또는 복원, 일시 중지,
대상 삭제)이 있을 때 몇 초 뒤에 배지 전용 알림이 전송됩니다. 알림 문구와 소리 없이
새 수만 담깁니다. 변경이 영향을 준 할 일 항목이 몇 개든
사용자와 변경 구간당 배지 전용 알림 하나만 전송됩니다.
디바이스 등록#
인증된 사용자의 디바이스 토큰을 등록합니다. 이 엔드포인트는
멱등성을 가진 upsert입니다. 이미 있는 토큰을 다시 등록하면 해당 토큰의
속성과 last_seen_at 타임스탬프가 갱신되므로, 클라이언트는 애플리케이션을
시작할 때마다 다시 등록합니다. 토큰이 이미 등록되어 있을 때 요청에서 생략한 속성은
저장된 값을 유지합니다. 다른 사용자에게 속한 토큰을 등록하면
인증된 사용자에게 재할당됩니다.
각 사용자는 최대 20개의 디바이스를 등록할 수 있습니다. 90일 동안 확인되지 않은 구독은 자동으로 제거됩니다.
POST /user/push_subscriptions
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
device_token |
string | 예 | 16진수 APNs 디바이스 토큰. |
platform |
string | 아니요 | 디바이스 플랫폼. ios 또는 macos입니다. 새 등록의 기본값은 ios입니다. |
apns_environment |
string | 아니요 | 토큰이 발급된 APNs 환경: production 또는 sandbox. 기본값: production. |
bundle_id |
string | 아니요 | 애플리케이션 번들 식별자. |
device_name |
string | 아니요 | 사람이 읽을 수 있는 디바이스 이름. |
app_version |
string | 아니요 | 설치된 애플리케이션 버전. |
locale |
string | 아니요 | 디바이스 로케일. |
payload_mode |
string | 아니요 | full은 푸시 페이로드에 알림 콘텐츠를 담아 보냅니다. id_only는 콘텐츠 없는 페이로드를 위해 레코드 식별자만 보냅니다. 새 등록의 기본값은 full입니다. |
요청 예시:
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--data "device_token=abcdef0123456789abcdef0123456789" \
--data "apns_environment=sandbox" \
--url "https://gitlab.example.com/api/v4/user/push_subscriptions"
성공하면 201과 다음
응답 속성을 반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
id |
integer | 구독의 ID. |
created_at |
string | 구독이 생성된 날짜와 시간(ISO 8601 형식). |
응답 예시:
{
"id": 1,
"created_at": "2026-07-30T18:15:31.189Z"
}
디바이스 등록 해제#
히스토리
- GitLab 19.6에서 디바이스 토큰에 대해 다른 사용자가 등록한 구독도 삭제하도록 변경되었습니다.
다른 사용자가 등록한 구독을 포함해 디바이스 토큰의 모든 구독을 삭제합니다.
예를 들어 사용자가 로그아웃할 때 이 엔드포인트를 호출합니다.
이전 사용자의 로그아웃 요청이 GitLab에 도달하지 못했다면 이 호출로 해당 사용자의 디바이스 알림도 중지됩니다.
토큰이 액세스 로그에 나타나지 않도록 URL이 아니라 요청 본문으로 전달합니다.
성공하면 204 No Content를 반환하고, 토큰에 대한 구독이 없으면 404 Not Found를 반환합니다.
DELETE /user/push_subscriptions
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
device_token |
string | 예 | 16진수 APNs 디바이스 토큰. |
요청 예시:
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--data "device_token=abcdef0123456789abcdef0123456789" \
--url "https://gitlab.example.com/api/v4/user/push_subscriptions"