5. 단일 건 발송
개요
특정 대상 즉 Token에 맵핑 될 단일 식별자(identity)에게 메시지를 보내는 방법입니다.
단, 과도한 단일건 발송 API 호출로 서비스의 트래픽을 발생시킬 경우 사전경고 없이 서비스의 제약을 받을 수 있습니다.
API Server URL: https://api-v2.fingerpush.com/rest/sts/v4/setSTSpush.jsp
발송 방법 및 전송/수신 파라미터 정의
HTTPS Parameters
SSL Protocol을 이용하여 파라미터들을 API Server에 전달합니다.
API Server로 전달해야 할 파라미터들은 아래 표를 참조해 주세요.
[표 4.1] 단일 건 발송 HTTPS, Parameters
파라미터명 | 필수 여부 | Byte 수 | 설명 |
---|---|---|---|
appkey | 필수 | - | Application key |
appsecret | 필수 | - | Application Secret |
customerkey | 필수 | - | Customer key |
msg | 필수 | 1000 | 보낼 푸시 메시지 |
identity | 필수 | 50 | 대상자 식별자 값 |
isa | 선택 | - | Y: 안드로이드 기기 대상 발송(default) N: 안드로이드 기기를 전송 대상에서 제외 ※ 해당 값이 빈 상태로 서버로 전달될 경우, 기본 값인 Y로 처리 |
asnd | 선택 | 50 | 안드로이드 기기의 푸시 수신 사운드 ※ 핑거푸시 Android API 적용을 기준으로 효과음 지정 |
abdg | 선택 | - | 안드로이드 푸시 배지 처리 파라미터, number type. ex) 1 ~ ※ 핑거푸시 Android API 적용을 기준으로 배지 효과 지정 |
isi | 선택 | 1 | Y: IOS 기기 대상 발송(default) N: IOS 기기를 전송 대상에서 제외 ※ 해당 값이 빈 상태로 서버로 전달될 경우, 기본 값인 Y로 처리 |
ibdg | 선택 | - | IOS 푸시 배지 처리 파라미터, number type. ex) 1 ~ ※ 핑거푸시 IOS API 적용을 기준으로 배지 효과 지정 |
isnd | 선택 | 50 | IOS 기기의 푸시 수신 사운드 ※ 핑거푸시 IOS API 적용을 기준으로 효과음 지정 |
ck1 | 선택 | 100 | 커스텀 키 1(App 개발 시 반영된 값) deep link > app link > custom key 1 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값 |
ck2 | 선택 | 100 | 커스텀 키 2(App 개발 시 반영된 값) deep link > app link > custom key 2 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값 |
ck3 | 선택 | 100 | 커스텀 키 3(App 개발 시 반영된 값) deep link > app link > custom key 3 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값 |
cv1 | 선택 | 200 | 커스텀 값 1(App 개발 시 반영된 값) deep link > app link > custom value 1 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값 |
cv2 | 선택 | 200 | 커스텀 값 2(App 개발 시 반영된 값) deep link > app link > custom value 2 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값 |
cv3 | 선택 | 200 | 커스텀 값 3(App 개발 시 반영된 값) deep link > app link > custom value 3 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값 |
link | 선택 | 256 | deep link > web link ex) https://www.kissoft.co.kr ※ 해당 링크에 정의된 값이 있으면 푸시 메시지에 해당 링크 제공(핑거푸시 APP API가 적용되어 있어야 함) |
fnm | 선택 | 256 | 첨부 이미지 링크 -안드로이드 폰에서 첨부된 이미지 표현 가능 -도메인을 포함한 전체 경로 입력 ex)http://www.kissoft.co.kr/images/img.jpg |
send_state | 선택 | 4 | 0001: 바로 발송(default) 0002: 예약발송 |
senddate | 선택 | 12 | send_stat 값이 0002(예약발송)으로 처리된 경우 예약 발송 날자 및 시간 입력 ex) yyyymmdd24hmin -> 202109172113 |
title | 선택 | 100 | 푸시 수신 시 메시지 제목 |
lcode | 선택 | 10 | 라벨 코드 |
bgcolor | 선택 | 7 | 배경색 ex) #FFFFFF |
fcolor | 선택 | 7 | 폰트 색상 ex) #000000 |
isetiquette | 선택 | - | 에티켓 시간 적용 여부 Y: 적용(default) N: 적용 안함 |
etiquette_stime | 선택 | - | 에티켓 적용 시작시간 -Number type(1~ 24) -default: 21(오후 9시) |
etiquette_etime | 선택 | - | 에티켓 적용 종료시간 -Number type(1~24) -default: 8(오전 8시) |
and_priority | 선택 | - | 안드로이드용 메시지 우선순위 H: 높음 M: 중간(default) |
optagree | 선택 | - | 0000: 광고 수신 동의 여부에 관계없이 푸시 수신자 모두에게 발송(default) 1000: 광고 수신 동의한 디바이스에만 메시지 발송 |
Response JSON
API서버에서 전달 받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다.
[표 4.2] 발송 JSON 결과
값 | 설명 |
---|---|
result | 결과 코드 |
msgIdx | 메시지 번호 |
processCode | 메시지 처리 단계 |
message | 결과 메시지 |
ratelimit-limit | 분당 허용되는 최대 요청 횟수 |
ratelimit-remaining | 잔여 분(minute) 동안 가능한 요청 횟수 |
retry-after | 요청 갱신 시간까지 남은 초(second) - ratelimit를 초과한 경우에만 _code: 429와 함께 반환 |
처리결과에 따른 result 값은 아래와 같습니다.
[표 4.3] 발송 JSON 결과의 result code 유형
코드 | 내용 | 비고 |
---|---|---|
200 | 정상처리 됨 |
|
4031 | 유효하지 않은 appkey 혹은 appsecret |
|
4032 | Server to Server 서비스 이용권한 없음 |
|
4040 | 존재하지 않는 식별자 | 수집되지 않았거나, 삭제된 식별자 |
429 | 분당 호출 수 초과 | |
500 | 서버 에러 | |
503 | 필수 값이 누락됨 | Message에 누락된 필수값 표시됨 |
504 | 발송 대상 처리 중 에러 | 발송 대상 데이터 확인 |
505 | 메시지 허용 byte 수 초과 | 1000 byte 제한 |
processCode는 푸시 메시지 처리 단계를 표시하는 코드입니다. 단일 발송에서는 큰 의미가 없으나, 500건 이상의 메시지 발송에서는 각 단계별 처리를 위한 코드로 사용됩니다.
처리결과에 따른 result 값은 아래와 같습니다.
[표 4.4] JSON 결과의 processCode code 유형
코드 | 내용 | 비고 |
---|---|---|
20001 | 푸시 메시지 등록 정상 처리 | 메시지 아이디가 반환됨 |
20002 | 발송대상자 등록 정상 처리 |
|
20003 | 푸시 메시지 등록 완료 |
|
샘플 소스 설명
HTTPS로 미리 정의된 파라미터들을 전달하고 JSON으로 결과 데이터를 읽을 수 있도록 작업해 주시면 됩니다.
JAVA용 샘플의 경우 Apache common의 HttpClient(http://hc.apache.org/)를 이용하여 파라미터를 전송하도록 하였으므로 해당 library가 필요합니다. 샘플 소스는 GitHub를 통해 확인 가능 합니다.
JSP 샘플의 경우, 샘플 메소드를 이용한 직접 발송이 가능합니다. 혹, 사용자 환경에 맞도록 수정이 필요하면 class(com.fingerpush.push.FingerpushDaoImpl)내에 구성되어 있는 메소드를 참조해 주시기 바랍니다.
해당 샘플에 대한 설명은 파라미터 전달 및 API URL에 대해 클래스 내에 구현되어 있는 로직 위주로 설명 드립니다.
JAVA Version
Github에 올려져 있는 샘플소스는 아래 설명된 내용 중 중복된 부분들을 method화 하여 처리하므로 약간의 차이가 있을 수 있으나, 기본 발송 방식의 설명이므로 해당 중복되는 부분을 풀어서 설명하도록 하겠습니다.
1) 파라미터를 담을 List 객체를 선언해 전달할 값들을 셋팅 합니다.
2) 필수값들을 셋팅 합니다.
3) 선택 값들을 셋팅 합니다. (선택) 해당 내용들은 Application 개발 시 반영된 내용을 기준으로 처리합니다.
4) 해당 메시지를 받은 대상자를 셋팅 합니다.
5) 기존 HttpClient의 DefaultHttpClient를 이용한 원격 접속 방식이 deprecated 된 이유로 HttpsURLConnection을 이용하여 접속합니다. 물론 deprecated 되었다고 해서 DefaultHttpClient 방식이 동작하지 않는 것은 아닙니다. 해당 방식 역시 github에 올려져 있는 샘플 소스에 구현되어 있습니다.
예제: FingerpushDaoImpl.sendHttpsExe(String callUrl, List <BasicNameValuePair> params))
전달하는 파라미터는 UTF-8로 인코딩 하여 전달해야 합니다.
예제: 샘플의 FingerpushDaoImpl.sendHttpsUrlConExe(String callUrl, List <BasicNameValuePair> params)
API Server URL: https://api-v2.fingerpush.com/rest/sts/v4/setSTSpush.jsp
6) 받은 결과는 JSON 타입의 String 이므로 결과에 맞게 변환하여 사용하시는 UI에 적용하시면 됩니다. 받은 jsonString은 앞서 설명한 ‘Response JSON’ 부분을 참조해 주세요.
※ JAVA Version 단일 건 발송 샘플
소스 주소 | |
class | com.fingerpush.push.FingerpushDao com.fingerpush.push.FingerpushDaoImpl com.fingerpush.push.PushVO |
jsp | JSP/sendTargetOne.jsp |
PHP Version
Github에 올려져 있는 샘플 소스는 아래 설명된 내용 중 중복된 부분들을 method화 하여 처리하므로 약간의 차이가 있을 수 있으나, 기본 발송 방식의 설명이므로 해당 중복되는 부분을 풀어서 설명하도록 하겠습니다.
1) 기본 앱 정보를 세팅합니다.
2) 메시지 발송에 사용되는 필수값과 선택값을 세팅합니다.
3) 앱 기본정보와 옵션값을 URL 인코드 한 쿼리 문자열로 생성합니다.
4) PHP cURL 라이브러리를 이용하여 핑거푸시 API와 통신합니다.
PHP cURL 라이브러리: https://www.php.net/manual/en/book.curl.php
일괄발송 API URL: https://api-v2.fingerpush.com/rest/sts/v4/setSTSpush.jsp
cURL을 아래와 같이 HTTPS 통신으로 세팅합니다.
5) 전달 받은 JSON 문자열 결과값을 PHP 변수로 변환합니다.
Last updated