apple_device-management/mdm/commands/media.install.yaml

title: Install Media Command
description: Install a book on a device.
payload:
  requesttype: InstallMedia
  supportedOS:
    iOS:
      introduced: '8.0'
      accessrights: AllowAppInstallation
      supervised: false
      requiresdep: false
      sharedipad:
        mode: allowed
        devicechannel: true
        userchannel: false
      userenrollment:
        mode: allowed
    macOS:
      introduced: '10.9'
      deprecated: '11.0'
      removed: '11.0'
      accessrights: AllowAppInstallation
      devicechannel: false
      userchannel: true
      supervised: false
      requiresdep: false
      userenrollment:
        mode: forbidden
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  content: This command allows the server to install a book on a device. If the book
    is already being managed, this command will update the book.
payloadkeys:
- key: iTunesStoreID
  type: <integer>
  presence: optional
  content: The book's iTunes Store identifier.
- key: MediaURL
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The URL to retrieve the book.
- key: MediaType
  type: <string>
  presence: required
  rangelist:
  - Book
  content: The media type, which can only be `Book`.
- key: PersistentID
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The book's persistent identifier in reverse-DNS form; for example, `com.acme.manuals.training`.
- key: Kind
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  rangelist:
  - pdf
  - epub
  - ibooks
  content: |-
    The kind of the media, which can be one of the following values:

    - `pdf`: A PDF file
    - `epub`: An EPUB file in `gzip` format.
    - `ibooks`: An iBooks Author file in `gzip` format.

    If you omit this value, its value is the file extension in the URL.
- key: Version
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The book's version number.
- key: Author
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The name of the book's author.
- key: Title
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The book's title.
responsekeys:
- key: iTunesStoreID
  type: <integer>
  presence: optional
  content: The book's iTunes Store identifier, if present in the command.
- key: MediaURL
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The URL to retrieve the book, if present in the command.
- key: PersistentID
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The book's persistent identifier, if present in the command.
- key: MediaType
  type: <string>
  presence: optional
  content: The media type, which can only be `Book`.
- key: State
  type: <string>
  presence: optional
  rangelist:
  - Queued
  - PromptingForLogin
  - Updating
  - Installing
  - Managed
  - ManagedButUninstalled
  - Installed
  - Uninstalled
  - Failed
  - Unknown
  content: The installation state of this book. The `Failed` and `Unknown` states
    are transient and the device only reports them once. Books from the Book Store
    report their state as `Installed` instead of `Managed`.
- key: RejectionReason
  type: <string>
  presence: optional
  rangelist:
  - CouldNotVerifyITunesStoreID
  - PurchaseNotFound
  - AppStoreDisabled
  - WrongMediaType
  - DownloadInvalid
  - EnterpriseBooksNotSupportedInMultiUser
  content: |-
    The reason, if installation fails, which is one of the following values:

    - `CouldNotVerifyITunesStoreID`: The `iTunesStoreID` is invalid.
    - `PurchaseNotFound`: The Volume Purchase Program (VPP) license isn't in the user's history.
    - `AppStoreDisabled`: App Store isn't available on the device.
    - `WrongMediaType`: The media type is invalid. The only valid type is `Book`.
    - `DownloadInvalid`: The URL doesn't lead to a valid book.
    - `EnterpriseBooksNotSupportedInMultiUser`: Multiuser mode doesn't support enterprise books.
notes:
- title: ''
  content: |-
    The request must contain either the `iTunesStoreID` or `MediaURL`. The `MediaURL` must lead to a PDF file, an EPUB file in `gzip` format, or an iBooks Author document in `gzip` format. Books that MDM has installed become managed books.

    Use Volume Purchase Program (VPP) Licensing to obtain books from the Book Store. Books from the Book Store require that the device has enabled App Store. These books undergo backup, sync with iTunes, and remain on the device after removal of the MDM profile.

    Books that aren't from the Book Store don't require that the device has enabled App Store. These books don't undergo backup, don't sync with iTunes, and don't remain on the device after removal of the MDM profile.

    If the book already exists, this command updates the book and makes it visible to the MDM server. The user doesn't receive a prompt for a book installation or update unless they need to log in to complete a Book Store transaction.

    If you install a book from the Book Store with the same `iTunesStoreID` as an existing managed book, the new book replaces the existing one.

    If you install a book that isn't from the Book Store with the same `PersistentID` as an existing book that also isn't from the Book Store, the new book replaces the existing one.

    Refer to the following sections to determine supported channels and requirements, and to see an example request and response.
examples:
- title: Example request and response
  files:
  - tab: Enterprise
    description: This command installs an enterprise book.
    request-file: examples/mdm/commands/media.install/example1.plist
    response-file: examples/mdm/commands/media.install/example2.plist
  - tab: Book Store
    description: This command installs a book from the Book Store.
    request-file: examples/mdm/commands/media.install/example3.plist
    response-file: examples/mdm/commands/media.install/example4.plist