> For the complete documentation index, see [llms.txt](https://docs.dfinery.ai/developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dfinery.ai/developer-guide/common/specification/ios-push-payload.md).

# iOS 푸시 페이로드

이 문서는 iOS 단말기에서 수신 받는 푸시 페이로드에 대해 서술합니다.

푸시 수신 이벤트는 [UNUserNotificationCenter](https://developer.apple.com/documentation/usernotifications/unusernotificationcenter)의 delegate를 통해 전달됩니다.

Dfinery는 [Apple Push Notification service (APNs)](https://developer.apple.com/documentation/usernotifications) 표준을 따르며, **`aps`** 키와 **`dfn`** 키를 사용하여 푸시 페이로드를 전달합니다.

### 페이로드를 활용한 푸시 전송 테스트

커맨드 라인 툴을 통해 로컬 환경에서 아래의 페이로드를 적용하여 디파이너리 푸시를 테스트 해 볼 수 있습니다.

* [애플의 가이드 문서](https://developer.apple.com/documentation/usernotifications/sending-push-notifications-using-command-line-tools)
* [코드 예시](https://github.com/IGAWorksDev/dfinery-ios-sdk-pushSenderSample)

## Push Payload

iOS 푸시 페이로드의 전체 구조에 대한 명세입니다.

### Root Level

| 이름  | 타입         | 필수 | 설명                         |
| --- | ---------- | -- | -------------------------- |
| aps | Dictionary | ✅  | Apple Push Service 표준 페이로드 |
| dfn | Dictionary | ✅  | Dfinery 커스텀 데이터            |

### APS (Apple Push Service)

| 이름              | 타입         | 필수 | 설명                                        |
| --------------- | ---------- | -- | ----------------------------------------- |
| alert           | Dictionary | ✅  | 알림 표시 정보                                  |
| mutable-content | Number     | ✅  | 알림 서비스 앱 확장 플래그                           |
| sound           | String     |    | 알림음 설정, 재생할 경우 "default", 재생하지 않을 경우 값 없음 |
| category        | String     |    | 버튼을 활용하기 위한 카테고리 키 "DFINERY"로 사용함         |

### Alert

| 이름    | 타입     | 필수 | 설명        |
| ----- | ------ | -- | --------- |
| title | String | ✅  | 알림 제목     |
| body  | String | ✅  | 알림 본문 텍스트 |

### DFN (Dfinery Custom Data)

| 이름         | 타입            | 필수 | 설명               |
| ---------- | ------------- | -- | ---------------- |
| img        | String(URL)   |    | 이미지 URL          |
| is\_f      | Number(1\|0)  |    | 포그라운드 상태일때 표시 여부 |
| is\_test   | Integer(1\|0) | ✅  | 테스트 푸시 여부        |
| c\_id      | String        | ✅  | 캠페인 ID           |
| s\_id      | String        | ✅  | 서비스 ID           |
| u\_id      | String        | ✅  | 통합 ID            |
| click\_act | Dictionary    | ✅  | 푸시 메시지 클릭시 액션 정보 |
| btn        | Array         |    | 푸시 알림 버튼 정보      |

```json
{
   "aps":{
      "alert":{
         "title":"푸시 알림 제목",
         "body":"푸시 알림 내용"
      },
      "mutable-content":1,
      "sound":"default",
      "category":"DFINERY"
   },
   "dfn":{
      "img":"https://sample.com/sampleimage.jpeg",
      "is_f":1,
      "is_test":1,
      "c_id":"campaign_123",
      "s_id":"service_456",
      "u_id":"unifiedid",
      "click_act": {
         "l_id":"1",
         "l_type":"PushMessage",
         "act_type":"Deeplink",
         "uri":"dfinery://homepage"
      },
      "btn":[
         {
            "l_id":"1",
            "l_name":"앱 열기",
            "l_type":"Button",
            "act_type":"AppOpen",
            "uri":null
         },
         {
            "l_id":"2",
            "l_name":"상세보기",
            "l_type":"Button",
            "act_type":"Deeplink",
            "uri":"dfinery://itempage"
         }
      ]
   }
}
```

## Message Click Action

`click_act` Object에 대한 명세입니다.

| 이름        | 타입     | 필수 | 설명                                |
| --------- | ------ | -- | --------------------------------- |
| l\_id     | String | ✅  | Location ID(내부용)                  |
| l\_type   | String | ✅  | Location 타입(내부용)                  |
| act\_type | String | ✅  | 클릭시 액션 타입 (AppOpen \|\| Deeplink) |
| uri       | String |    | 딥링크 URI (AppOpen 타입일시 null)       |

```json
"click_act":{
   "l_id":"1",
   "l_type":"Content",
   "act_type":"Deeplink",
   "uri":"dfinery://homepage"
}
```

## Button

`btn` Array에 대한 명세입니다.

| 이름        | 타입     | 필수 | 설명                                |
| --------- | ------ | -- | --------------------------------- |
| l\_id     | String | ✅  | Location ID(내부용)                  |
| l\_name   | String | ✅  | 버튼 이름                             |
| l\_type   | String | ✅  | Location 타입(내부용)                  |
| act\_type | String | ✅  | 클릭시 액션 타입 (AppOpen \|\| Deeplink) |
| uri       | String |    | 버튼 딥링크 URI (AppOpen 타입일시 null)    |

```json
"btn":[
   {
      "l_id":"1",
      "l_name":"앱 열기",
      "l_type":"Button",
      "act_type":"AppOpen",
      "uri":null
   },
   {
      "l_id":"2",
      "l_name":"상세보기",
      "l_type":"Button",
      "act_type":"Deeplink",
      "uri":"dfinery://itempage"
   }
]
```