회원 연결과 서버 발송 | 메시지, 인앱, 푸시 마케팅 | Appbox SDK 가이드
회원 연결과 서버 발송
전체 흐름
- 1. 회원이 로그인하면 웹 페이지에서 회원 ID 를 앱박스에 알립니다(setSegment). 콘솔의 회원 ID 조건 발송과 기기 찾기에 쓰입니다.
- 2. 같은 때 웹 페이지에서 기기 정보(getDeviceInfo)를 받아 고객사 서버에 저장합니다.
- 3. 고객사 서버는 저장한 푸시 토큰으로 앱박스 서버 API(/api/v1/push/individual)를 부릅니다.
회원 ID 알리기: setSegment
Javascript
1 async function linkMember(memberId) {
2 if (!AppboxSDK.application.isAppBoxSDK()) return;
3 try {
4 const res = await AppboxSDK.message.setSegment({
5 segment: { memberId: String(memberId) },
6 });
7 if (res.ack === false) {
8 console.warn("회원 연결 실패", res.code, res.error);
9 }
10 } catch (err) {
11 console.warn("입력값 오류", err.code, err.message);
12 }
13 }
- 키 이름은 정확히 memberId 입니다(대소문자 그대로). 콘솔의 회원 ID 조건 발송과 기기 찾기가 이 키로 찾습니다.
- segment 는 { 키: 값 } 객체여야 합니다. 아니면 VALIDATION 으로 reject 됩니다.
- 값은 모두 문자열로 바뀌어 저장됩니다. null 이나 undefined 는 빈 문자열이 됩니다.
- 키에 공백, 점(.), $ 를 넣을 수 없고, 값이 JSON 객체나 배열 모양 문자열이면 서버가 받지 않습니다.
- 같은 호출에 다른 세그먼트(예: grade)를 함께 넣어도 됩니다. 콘솔 › 사용자 관리 › 세그먼트에 등록한 변수여야 메시지 개인화에 쓸 수 있습니다.
기기 정보 받기: getDeviceInfo
Javascript
1 async function readDevice() {
2 if (!AppboxSDK.application.isAppBoxSDK()) return null;
3 const info = await AppboxSDK.getDeviceInfo();
4 if (!info.deviceUserId || !info.pushToken) return null;
5 const bridge = AppboxSDK.env().bridge;
6 return {
7 deviceUserId: info.deviceUserId,
8 pushToken: info.pushToken,
9 osType: bridge === "ios" ? "IOS" : "AOS",
10 };
11 }
| 필드 | 뜻 |
|---|---|
| deviceUserId | 앱박스가 기기마다 만든 식별값 |
| pushToken | 푸시 토큰. 서버 API 의 data[].token 에 넣는 값 |
| message | 늘 빈 문자열 |
- 실패해도 오류가 오지 않습니다. 앱 밖이거나 아직 토큰이 없으면 값이 빈 문자열 "" 입니다. 빈 값을 서버로 보내지 않도록 위처럼 꼭 확인하세요.
- 결과에 ack 가 없습니다. 다른 함수와 다르니 info.ack 로 판정하지 마세요.
- OS 는 getDeviceInfo 에 없습니다. AppboxSDK.env().bridge("android", "ios")로 정해 서버 API 의 os_type(AOS, IOS)으로 저장하세요.
고객사 서버에 저장하기 (권장)
Javascript
1 async function onLogin(memberId) {
2 await linkMember(memberId);
3 const device = await readDevice();
4 if (!device) return;
5 await fetch("/my-api/push-devices", {
6 method: "POST",
7 headers: { "Content-Type": "application/json" },
8 body: JSON.stringify({ memberId: memberId, ...device }),
9 });
10 }
| 상황 | 권장 |
|---|---|
| 한 회원이 기기를 여러 대 씀 | 회원 하나에 기기 여러 행. deviceUserId 를 기준으로 덮어쓰기 |
| 토큰이 바뀜 | 로그인할 때마다, 그리고 앱을 열 때마다 다시 보내 최신 값으로 덮어쓰기 |
| 로그아웃 | 고객사 서버에서 그 기기 행을 지우거나 끊음 표시 |
| 기기를 다른 회원이 이어서 씀 | 새 회원 로그인 때 같은 deviceUserId 행을 새 회원으로 옮김 |
서버에서 보내기: 개별 푸시 API
HTTP
1 POST https://api.appboxapp.com/api/v1/push/individual
2 Authorization: Basic base64(<인증키>:<앱 코드>)
3 Content-Type: application/json
JSON
1 {
2 "campaign_name": "주문 완료 안내 1234",
3 "data": [
4 {
5 "token": "<저장한 pushToken>",
6 "os_type": "AOS",
7 "title": "주문이 완료됐습니다",
8 "contents": "주문번호 1234 가 접수됐습니다."
9 }
10 ]
11 }
- 미리 준비할 것 두 가지: 콘솔 › 메시지 발송 › 푸시 메시지 › API 설정에서 인증키 생성과 서버 공인 IP 등록. 하나라도 빠지면 HTTP 401 입니다. 등록할 IP 는 호출하는 서버에서 확인한 공인 IPv4 입니다.
- 인증키는 고객사 서버에만 두세요. 웹 페이지나 앱에 넣으면 안 됩니다.
- os_type 을 함께 보내세요. 빼면 앱박스가 토큰으로 기기를 찾는데, 등록되지 않은 토큰이 하나라도 있으면 요청 전체가 거절(본문 code 422)됩니다.
- 성공과 실패는 HTTP 상태가 아니라 본문의 success, code 로 구분합니다.
- 같은 요청을 다시 보내면 다시 발송되고 다시 차감됩니다. 응답을 못 받았다면 콘솔 › 성과 분석 › 푸시 발송 이력에서 나갔는지 먼저 확인하세요.
- 자세한 항목과 오류는 앱 설정 가이드 "서버 API" 문서를 보세요.