# 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"
   }
]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dfinery.ai/developer-guide/common/specification/ios-push-payload.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.