pushpia 사용상의 필요한 Data의 획득 혹은 발송 등을 URL을 통해서 가능하게 도와준다.
Method 호출, 입력 URL 에 따라 원하는 요청을 수행하니 규칙에 맞게 잘 호출하도록 한다. 사용방법으로 크게 URL / Parameters / Return 의 4가지 용어에 대한 이해한다면, 각 요청 별 매뉴얼에 대한 이해를 하는데도 도움이 많이 될 것이다.
실질적으로 원하는 요청을 수행하기 위해서 HTTP를 이용한 URL 호출방식을 수행하고 있다. 각 요청 별로 그에 맞는 URL 호출규칙이 있으니, 해당 규칙을 준수하여 호출하도록 하자.
l ASP 페이지의 기본호출 URL : 아래와 같은 URL뒤에 각 요청 별로 추가 URL 이 붙는다.
- https://api.pushpia.com:444/~
부가적인 정보를 입력하기 위해서 사용한다. URL 의 뒷부분에 아래 예시와 같이 ‘?’ 와 ‘&’ 를 이용하여 입력 값을 전달받는다. 기본 URL 호출시의 parameter 값의 규칙과 마찬가지로 ‘?’ 는 parameter가 시작됨을, ‘&’ 는 추가적인 parameter가 시작됨을 의미한다.
l Parameter 가 사용된 예 (JSON 배열로 BIZ ID를 전달하는 경우)
- https://api.pushpia.com:444/send/realtime?d={"bizId":"aaa0669e23ac415ca3a8b0e30062ca8c"}
URL을 이용하여 요청을 하면 해당내용에 대한 결과도 필요하다. 이를 위해 결과를 반환하고 있으며, 발송요청을 수행한 경우 성공 실패여부를 반환하도록 하고 있다.
l 발송요청이 성공한 경우
{"bizId":"aaa0669e23ac415ca3a8b0e30062ca8c","reqUid":"pushpia_20150420094700", "custId":"userid","code":"000","msg":"SUCCESS"} |
l 발송요청이 실패한 경우 (파라미터가 부족한 경우)
{"code":"100","msg":"param is null"} |
URL 상에는 요구에 따라 입력하는 Parameter 이외에도 필수입력 값이 필요한 경우도 있다. 필수 값은 Parameter 의 입력과는 다르게 {JSON array} 와 같은 형식으로 매뉴얼에 표현되었으니, 실제로는 JSON array 에 해당되는 실제 값을 넣어주면 된다. 헷갈린다면 아래예시를 참고하자.
l 매뉴얼상에 표시된 URL
https://api.pushpia.com:444/send/realtime?d={JSON array} |
l 실제 호출 URL
https://api.pushpia.com:444/send/realtime?d={ "bizId": "aaa0669e23ac415ca3a8b0e30062ca8c", "msgType": "T", "pushTime": 1800, "pushTitle": "title", "pushMsg": "push message", "pushKey": "l", "pushValue": "http://www.pushpia.com", "reserveTime": "20150417101700", "reqUid": "pushpia_20150417101700", "custId": "userid" } |
전반적으로 정의된 URL 호출방식을 정의하고 있으며, 실제 사용시 알맞은 요청을 찾아 사용방법을 참고하면 된다.
실시간 발송요청에 대한 상세내용을 정의한다.
실시간 발송을 이용하여 실질적인 Push 발송작업을 수행한다. 요청이 들어오는 순간, 해당 어플리케이션을 사용하고 있는 사용자 중 단일 사용자 혹은 다수의 사용자에게 Push 메시지를 전달한다.
실시간 Push를 발송하기 위해 bizId, msgType, pushTime, pushMsg, reserveTime, reqUid, custId 가 필수 사항이며, inappContent와 pushKey, pushValue를 추가정보로 입력할 수 있다. 또한, 동보 Push 메시지의 경우 infoNA, infoCP를 추가정보로 입력할 수 있다.
Push 메시지 발송을 위한 파라미터는 변수 d에 JSON 형식으로 전달하게 되는데, 개인화 메시지 혹은 동보 메시지 여부에 따라 JSON 배열의 구성이 달라지게 된다.
l URL
https://api.pushpia.com:444/send/realtime?d={JSON array} |
l Method
GET/POST |
l Parameters
파라미터명 |
파라미터의 의미 |
필수/선택 여부 |
bizId |
발송하려는 실시간 Push의 BIZ ID |
필수 |
msgType |
Push 메시지 타입 (T : Text, H : HTML) |
필수 |
pushTime |
발송 유효시간 |
필수 |
pushTitle |
수신 Push의 제목 |
필수 |
popupContent |
수신 Push의 팝업 메시지 |
선택 |
pushMsg |
수신 Push 의 상태창 메시지 |
필수 |
inappContent |
앱 내 메시지함에서 보여줄 메시지 내용 |
선택 |
pushKey |
고정 값 (소문자 l로 고정되어야 하며 변경 시 발송 불가) |
선택 |
pushValue |
페이로드에 넘겨줄 주소 |
선택 |
reserveTime |
예약발송시간 |
필수 |
reqUid |
발송 식별 값 |
필수 |
custId |
메시지 수신자 |
필수 |
infoNA |
수신자 이름 |
선택 |
infoCP |
수신자 휴대전화번호 |
선택 |
mktFlag |
마케팅 푸시 여부 ( Y : 마케팅용 푸시, N : 정보용 푸시 ) |
선택 |
l Examples
[개인화 Push 메시지의 경우] { "bizId":"aaa0669e23ac415ca3a8b0e30062ca8c", "msgType":"T", "pushTime":1800, "pushTitle":"title", "pushMsg":"push message", "inappContent":"inapp content", "pushKey":"l", "pushValue":"http://www.pushpia.com", "reserveTime":"20150417101700", "reqUid" : "pushpia _20150417101700", "custId" : "userid" }
[동보 Push 메시지의 경우] { "bizId":"aaa0669e23ac415ca3a8b0e30062ca8c", "msgType":"T", "pushTime":1800, "pushTitle":"title", "pushMsg":"push message", "inappContent":"inapp content", "pushKey":"l", "pushValue":"http://www.pushpia.com", "reserveTime":"20150417202800", "list":[ { "reqUid" : "pushpia_20150417202800", "custId" : "userid" "infoNA" : "username", "infoCP" : "01012345678" } ] } |
코드 |
결과메시지 |
상태 |
000 |
SUCCESS |
성공 |
100 |
param is null request is null |
파라미터 부족 파라미터 없음 |
101 |
Wrong size {paramName} |
잘못된 파라미터 크기 |
102 |
Invalid BizId |
잘못된 데이터 입력 |
110 |
occured error, to update app user |
내부오류 |
120 |
executeInternal error |
기타오류 |
[참고사항]
- 개인화 메시지는 수신자별로 메시지 내용을 다르게 하여 발송하고 싶은 경우 사용한다.
- 동보 메시지는 같은 내용의 메시지를 다수의 수신자에게 발송하고 싶은 경우 사용한다.
- 개인화 및 동보 Push 메시지의 pushKey와 pushValue, 그리고 동보 Push 메시지의 infoNA, infoCP 항목은 선택 입력사항이다.
- 동보 Push 발송 시 수신자로 지정하고 싶은 만큼 list 항목을 추가하면 된다.
- reqUid는 테이블에 삽입되는 레코드마다(발송 한 건마다) 모두 달라야 한다.
- 발송 유효시간은 전원이 꺼져있거나 네트워크에 연결되지 않아 Push 메시지를 받지 못한 경우, 재발송을 위해 메시지를 보관하는 시간을 말한다.
- pushKey의 필수 값인 "l"은 소문자 L 이다.
- pushValue에 넘겨주는 값은 멀티 푸시 작성 시 버튼링크 항목에 넘겨주는 값과 같은 역할을 한다.
- 코드 101에 대한 실제 결과메시지에는 해당 파라미터의 최대 크기도 함께 나타낸다.
- 코드 110에 대한 결과메시지는 대표사례 하나에 대해 표기한 것이며, 상황에 따라 메시지 내용이 달라질 수 있다.