> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Declarations Library Item 구성

> Iru Endpoint에서 Custom Declarations Library Item을 구성합니다. 기본 제공 Library Item이 없는 Apple 선언형 기기 관리 구성을 배포합니다.

이 Library Item은 Mac 컴퓨터, iPhone, iPad, Apple TV 및 Apple Vision Pro에서 사용할 수 있습니다

Apple이 새로운 선언형 기기 관리(DDM) 구성을 출시하면 전용 Library Item 대신 **Custom Declarations** Library Item으로 배포할 수 있습니다. 선언 JSON을 추가하고, 설치 위치를 선택한 다음, Blueprint로 Library Item을 할당합니다. Iru는 Apple의 스키마를 기준으로 JSON을 검사하고, 기기에 전달하며, 각 선언의 상태를 표시합니다. 나중에 Iru가 동일한 구성에 대한 전용 Library Item을 추가하면 유효성 검사 패널의 **권장 사항** 결과에 해당 항목에 대한 링크가 표시됩니다.

Iru는 선언의 구조를 검증합니다. 기기가 선언을 적용할 때 Apple 소프트웨어가 어떻게 동작하는지는 테스트하지 않습니다. 광범위하게 할당하기 전에 모든 선언을 파일럿 기기에서 테스트하십시오.

> [!NOTE]
>
> 선언에 대한 배경 정보는 Apple의 [선언형 기기 관리 문서](https://developer.apple.com/documentation/devicemanagement/declarative-management)를 참조하십시오.

## Custom Declarations Library Item 생성

시작하기 전에 선언 JSON을 준비하십시오. 대신 `.mobileconfig` 프로필을 배포하려면 [Custom Profile](https://docs.iru.com/ko/endpoint/library/library-items-profiles/custom-profiles-overview.md)을 사용하십시오.

**파일 업로드**와 **수동 입력**은 서로 대체되는 옵션입니다. 선언 JSON을 추가할 때 둘 중 하나만 사용하고, 둘 다 사용하지 마십시오.

**1. Library 열기**

**Library**로 이동합니다.

**2. Library Item 추가**

**Library Item 추가**를 선택한 다음 **Custom Declarations**를 선택합니다.

**3. Library Item 제목 설정**

Library Item의 제목을 입력합니다.

**4. 설치 대상 선택**

**설치 대상**에서 이 Library Item이 적용될 플랫폼을 선택합니다. Iru는 선택한 플랫폼 중 각 선언의 유형을 지원하는 플랫폼에만 해당 선언을 보냅니다.

**5. Assignment Maps 할당**

이 Library Item을 받을 Assignment Maps를 할당합니다. [Blueprint 구성](https://docs.iru.com/ko/endpoint/getting-started/blueprints-and-library/configuring-blueprints.md)을 참조하십시오.

**6. 옵션 1: 파일 업로드**

선언이 `.json` 파일로 저장되어 있는 경우 이 옵션을 사용합니다. **설정**에서 **파일 업로드**를 선택합니다. 파일을 페이지로 끌어다 놓거나 **파일 선택**을 선택합니다. Iru는 파일을 편집기에 불러오고 동일한 방식으로 검사합니다. 파일 자체는 저장되지 않습니다. [선언 JSON](#declaration-json)을 참조하십시오.

![파일 업로드가 선택된 Custom Declarations 설정. 선언 JSON을 페이지로 끌어다 놓거나 파일을 선택합니다.](https://mintcdn.com/iru/EIZIDeW6fQDKik27/assets/media/images/iru-custom-declarations-upload-file.jpg?fit=max\&auto=format\&n=EIZIDeW6fQDKik27\&q=85\&s=98ee1608c139da55421624e8865d62bf)

**7. 옵션 2: 수동 입력**

JSON을 직접 붙여넣으려면 이 옵션을 사용합니다. **설정**에서 **수동 입력**을 선택한 다음 **JSON 입력**에 JSON을 붙여넣습니다. 입력하는 동안 **유효성 검사**가 업데이트됩니다. [선언 JSON](#declaration-json)을 참조하십시오.

![수동 입력이 선택된 Custom Declarations 설정. 왼쪽에 JSON을 입력하고 오른쪽에서 유효성 검사를 확인합니다.](https://mintcdn.com/iru/EIZIDeW6fQDKik27/assets/media/images/iru-custom-declarations-manual-entry.jpg?fit=max\&auto=format\&n=EIZIDeW6fQDKik27\&q=85\&s=b19cb9b90b5c784f5b92797e14b06fc4)

**8. 유효성 검사 검토**

**유효성 검사**의 결과를 검토하고 **오류**로 표시된 항목을 수정합니다. [유효성 검사 결과](#validation-findings)를 참조하십시오.

**9. 저장**

**저장**을 선택합니다.

## 설정

### 선언 JSON

하나 이상의 Apple 구성 선언을 붙여넣거나 업로드합니다. 각 선언에는 `Type`과 `Payload`가 필요합니다. 단일 선언 또는 목록을 추가할 수 있습니다. 다음 예시는 Safari 북마크 선언 하나가 포함된 목록입니다.

```json theme={null}
[
  {
    "Type": "com.apple.configuration.safari.bookmarks",
    "Payload": {
      "ManagedBookmarks": [
        {
          "Title": "Iru Resources",
          "Bookmarks": [
            {
              "URL": "https://www.iru.com",
              "Title": "Iru"
            },
            {
              "URL": "https://www.iru.com/updates/all",
              "Title": "Product Updates"
            },
            {
              "URL": "https://www.iru.com/legal",
              "Title": "Legal and Privacy"
            }
          ],
          "GroupIdentifier": "Group1"
        }
      ]
    },
    "Identifier": "EB13EE2B-5D63-4EBA-810F-5B81D07F5019"
  }
]
```

* 하나의 Library Item에는 1\~100개의 선언을 총 128KB까지 담을 수 있습니다.
* 각 선언에는 자체 활성화가 적용되므로 하나가 실패해도 다른 선언이 차단되지 않습니다.
* Iru는 구성 선언(`com.apple.configuration.*`)을 허용합니다. 활성화 또는 관리 선언은 허용하지 않습니다.
* `Identifier`는 선택 사항입니다. 생략하면 Iru가 할당합니다. 각 `Identifier`는 Library Item 내에서 고유해야 합니다.
* `ServerToken`을 포함하면 Iru가 저장 시 이를 제거하고 자체적으로 계산합니다.
* `$EMAIL` 또는 `$ASSET_TAG`와 같은 [전역 변수](https://docs.iru.com/ko/endpoint/library/library-items-profiles/global-variables.md)를 사용할 수 있습니다. Iru는 각 기기에 맞게 변수를 확인합니다. 값이 없는 변수는 빈 텍스트가 됩니다.

### 채널

Iru는 Apple의 스키마에 따라 각 선언에 대해 기기 채널 또는 사용자 채널을 선택합니다. 사용자 채널은 Mac 컴퓨터와 Shared iPad에만 있습니다.

### 유효성 검사 결과

Iru는 편집하는 동안, 입력을 멈춘 직후, 그리고 저장할 때 다시 선언을 검사합니다. 결과는 **유효성 검사**에 해당 줄과 연결되어 표시됩니다. Apple 베타 주기 동안에는 패널에 베타 탭도 표시됩니다.

각 결과에는 심각도가 있습니다.

* **오류**: Apple이 선언을 거부합니다. 예를 들어 값의 유형이 잘못되었거나 필수 키가 누락된 경우입니다.
* **경고**: 선언이 여전히 작동할 수 있지만 Iru가 이를 확인할 수 없습니다. 예를 들어 키 또는 유형을 알 수 없거나, 선택한 모든 플랫폼에서 지원되지 않는 경우입니다.
* **정보**: Iru가 무언가를 변경하거나 보류합니다. 예를 들어 Iru가 `ServerToken`을 제거하거나 에셋을 전달하지 않는 경우입니다.
* **권장 사항**: Iru에 이 선언 유형에 대한 기본 제공 Library Item이 있습니다. 결과에 해당 항목에 대한 링크가 표시됩니다.

Iru가 보유한 Apple 스키마 사본은 새 릴리스보다 늦게 업데이트될 수 있으므로 결과가 저장을 차단하지는 않습니다. 다음 문제는 저장을 차단합니다.

* 잘못된 JSON
* `Type` 또는 `Payload`가 없는 선언
* Iru가 지원하지 않는 선언 종류
* 중복된 `Identifier`
* **설치 대상**에서 선택한 플랫폼 없음
* 100개를 초과하는 선언 또는 128KB 초과

## 고려 사항

> [accordion] 에셋은 전달되지 않음
>
> 에셋 선언(`com.apple.asset.*`)을 저장할 수는 있지만 Iru는 이를 전달하지 않습니다. 이러한 에셋 중 하나를 참조하는 구성도 전달되지 않습니다. 두 경우 모두 기기에서 **호환되지 않음**으로 표시됩니다. DDM 에셋 지원은 향후 릴리스에서 추가될 예정입니다.

> [accordion] 프로필은 허용되지 않음
>
> Custom Declarations는 선언만 배포합니다. `.mobileconfig` 파일을 배포하려면 [Custom Profile](https://docs.iru.com/ko/endpoint/library/library-items-profiles/custom-profiles-overview.md)을 사용하십시오.

> [accordion] 일부 선언이 호환되지 않음으로 표시됨
>
> 기기가 선언을 받을 수 없는 경우 Iru는 선언을 보내지 않고 이유와 함께 **호환되지 않음**으로 표시합니다. 이유에는 지원되지 않는 OS 또는 플랫폼, 에셋, Apple이 Shared iPad에서 허용하지 않는 유형 등이 있습니다. 기기가 선언을 받을 수 있게 되면 Iru가 선언을 전달합니다.

> [accordion] 선언별로 상태가 표시됨
>
> 기기의 상태를 열면 각 선언이 `Identifier`별로 나열됩니다. Library Item의 전체 상태는 다음 규칙을 따릅니다. 선언 중 하나라도 **오류**이면 항목이 **오류**로 표시됩니다. 그렇지 않고 하나라도 **보류 중**이면 항목이 **보류 중**으로 표시됩니다. 그 외의 경우에는 **통과**로 표시됩니다. 선언이 실패하면 Iru는 Apple의 오류 텍스트를 표시합니다.

> [accordion] 유효한 선언이 보류 중 상태로 유지될 수 있음
>
> Apple이 수락했지만 비활성으로 표시한 선언은 Apple의 이유와 함께 **보류 중**으로 표시됩니다. 이유가 `Error.*` 코드인 경우 선언은 **오류**로 표시됩니다.

> [accordion] 편집 시 변경된 항목만 다시 전송됨
>
> 선언 하나를 편집하면 Iru는 해당 선언만 다시 보냅니다. 다른 항목의 순서를 바꾸거나 편집해도 나머지 항목은 변경되지 않습니다.

> [accordion] 설정 지원
>
> Automated Device Enrollment 중에 설정 지원은 모든 선언이 활성화되거나 하나라도 실패할 때까지 기다립니다. **호환되지 않음** 선언은 기다리지 않습니다. OS가 선언형 기기 관리를 실행할 수 없는 기기는 대신 MDM을 통해 Library Item을 받습니다.

> [accordion] 선언을 제거하면 기기에서 제거됨
>
> 선언을 제거하거나 Library Item 할당을 해제하면 기기에서 제거됩니다. Iru는 확인을 요청합니다. 매우 큰 테넌트에서는 제거가 일괄적으로 실행되므로 기기에서 제거되기까지 몇 분이 걸릴 수 있습니다.

> [accordion] Library Items 간 Identifier 충돌
>
> Iru는 각 `Identifier`가 Library Item 내에서 고유한지 확인합니다. 다른 Library Item에 있는 동일한 `Identifier`는 감지하지 않습니다. Library Items 간에 Identifier를 서로 다르게 유지하십시오.

## 모범 사례

**1. 파일럿 기기에서 테스트**

Iru는 구조를 검사할 뿐 Apple 소프트웨어의 동작은 검사하지 않습니다. 광범위하게 할당하기 전에 모든 선언을 파일럿 기기에서 테스트하십시오.

**2. 기본 제공 Library Item 사용**

**권장 사항** 결과가 동일한 구성에 대한 기본 제공 Library Item에 연결되는 경우 해당 Library Item을 사용하십시오.

**3. 명확한 Identifier 사용**

Iru는 `Identifier`를 기준으로 상태에 레이블을 지정합니다. 설명적인 이름을 사용하면 문제 해결이 빨라집니다.

**4. 관련 선언 그룹화**

함께 사용하는 선언은 하나의 Library Item에 최대 100개까지 넣으십시오.

**5. 할당 전에 오류 결과 수정**

결과가 저장을 차단하지는 않지만 **오류**는 일반적으로 기기가 선언을 거부한다는 의미입니다.

**6. 할당 후 상태 확인**

기기 상태를 열고 각 선언이 **통과**로 표시되는지 확인하십시오.

## 문제 해결

> [accordion] 선언이 호환되지 않음으로 표시됨
>
> Iru가 선언을 보내지 않았습니다. 기기 상태를 열고 이유를 확인하십시오.
>
> **가능한 원인:**
>
> * 기기 OS 또는 플랫폼이 선언 유형을 지원하지 않습니다.
> * 선언이 에셋이거나 구성이 에셋을 참조합니다.
> * Shared iPad에서 허용되지 않는 유형입니다.
>
> **해결 방법:**
>
> * 기기를 지원되는 OS로 업데이트하거나 Library Item에서 선언을 제거하십시오.
> * 에셋 참조를 제거하십시오.

> [accordion] Library Item이 보류 중 상태로 유지됨
>
> **가능한 원인:**
>
> * 기기가 아직 체크인하지 않았거나 상태를 보고하지 않았습니다.
> * Apple이 선언을 수락하고 비활성으로 표시했습니다.
>
> **해결 방법:**
>
> * 기기가 온라인 상태이고 체크인했는지 확인하십시오.
> * 기기 상태를 열고 해당 선언에 대한 Apple의 이유를 확인하십시오.

> [accordion] Library Item이 오류로 표시됨
>
> **가능한 원인:**
>
> * 선언에 잘못된 값, 누락된 키 또는 Apple의 허용 범위를 벗어난 값이 있습니다.
> * Apple이 `Error.*` 이유를 보고했습니다.
>
> **해결 방법:**
>
> * 기기 상태를 열고 `Identifier`로 선언을 찾은 다음 Apple의 오류 텍스트를 확인하십시오.
> * 선언을 수정하고 저장하십시오. Iru는 변경된 항목만 다시 보냅니다.

> [accordion] Library Item을 저장할 수 없음
>
> **가능한 원인:**
>
> * JSON이 잘못되었습니다.
> * 선언에 `Type` 또는 `Payload`가 없습니다.
> * 두 선언이 동일한 `Identifier`를 공유합니다.
> * **설치 대상**에서 선택한 플랫폼이 없습니다.
> * Library Item에 100개를 초과하는 선언이 있거나 크기가 128KB를 초과합니다.
> * 텍스트 크기가 2MB를 초과합니다.
>
> **해결 방법:**
>
> * **유효성 검사**의 메시지를 읽고 해당 메시지가 가리키는 줄을 수정하십시오.
> * 텍스트 크기가 2MB를 초과하는 경우 한도 미만으로 줄이십시오. Iru는 즉시 이를 거부하고 크기를 표시합니다.

> [accordion] 유효성 검사에서 선언을 검사할 수 없음
>
> **가능한 원인:**
>
> * 유효성 검사가 완료되지 않았습니다.
>
> **해결 방법:**
>
> * 잠시 기다린 후 JSON을 다시 편집하여 검사를 실행하십시오.
> * 선언이 유효한 경우에도 저장할 수 있습니다.

> [accordion] .mobileconfig 파일이 허용되지 않음
>
> **가능한 원인:**
>
> * 파일이 선언 JSON이 아닌 `.mobileconfig` 프로필입니다.
>
> **해결 방법:**
>
> * [Custom Profile](https://docs.iru.com/ko/endpoint/library/library-items-profiles/custom-profiles-overview.md)로 프로필을 배포하십시오.

## 관련 문서

> [card] [Library 개요](https://docs.iru.com/ko/endpoint/library/library-items-profiles/library-overview.md)
>
> Library Items를 선별, 생성 및 관리하고 Blueprints에 추가합니다

> [card] [Custom Profiles 개요](https://docs.iru.com/ko/endpoint/library/library-items-profiles/custom-profiles-overview.md)
>
> 선언이 적합한 페이로드가 아닌 경우 .mobileconfig 프로필을 배포합니다

> [card] [Blueprint 구성](https://docs.iru.com/ko/endpoint/getting-started/blueprints-and-library/configuring-blueprints.md)
>
> Blueprint로 기기에 Library Items를 할당합니다

> [card] [전역 변수](https://docs.iru.com/ko/endpoint/library/library-items-profiles/global-variables.md)
>
> 기기 및 할당된 사용자 값을 선언에 삽입합니다


## Related topics

- [Custom Profiles 개요](https://docs.iru.com/ko/endpoint/library/library-items-profiles/custom-profiles-overview.md)
- [Library 관리](https://docs.iru.com/ko/endpoint/getting-started/blueprints-and-library/managing-library.md)
- [전역 변수](https://docs.iru.com/ko/endpoint/library/library-items-profiles/global-variables.md)
