Try any driver free for 30 days
Sign in Cart (0)
Fixxy Driver

Docs · Driver manuals

Custom Mini App by Papaya

Any show, movie or link as its own App Switcher tile on the Apple TV

Driver name in Composer: Custom Mini App. Model: Custom Link Tile. Manufacturer: Papaya Web Services. File: Papaya_CustomMiniApp.c4z. Current driver version: 1.0.20. Store slug: custom-mini-app. Bundled with the Apple TV driver (one Apple TV license covers it). It needs the Apple TV by Papaya driver, which does the deep linking.

Overview

Custom Mini App turns a streaming link into a one-tap tile in the room, like Control4's Universal mini apps, but for a specific show, movie, episode or YouTube video. When someone picks the tile, the Apple TV opens that title in the right app.

  • One tile = one link. Set a Tile Name and a Link URL, or search for a title and pick a result.
  • Built-in search fills in the link, the poster and the tile name for you.
  • YouTube links fill in the video title and thumbnail automatically.
  • Poster art replaces the default icon.
  • Generate Tile Driver makes a dedicated .c4z for each tile so every tile keeps its own poster.
  • The remote controls the Apple TV while the tile is selected.
  • Renames the device in the project tree to the tile name (optional).

Who it is for: households with favorite shows, kids' content or YouTube videos they want one tap away in the Watch menu.

Requirements

  • Apple TV by Papaya driver in the room, paired, with its App Switcher. Update it to the latest version; new services and link fixes are added there.
  • Control4 OS 3.3.0 or newer (needed to write the tile image). Tested on OS 4.x.
  • Controller internet access for Search, poster images, YouTube auto-fill and Generate Tile Driver (they use the Papaya resolver service).
  • The streaming app installed on the Apple TV.
  • Apple TV driver in IP control mode.

Installing and first setup

  1. Set up the Apple TV by Papaya driver first and confirm it is paired.
  2. Add Custom Mini App to the same room.
  3. Connections: bind the tile's Custom Link output to a free MiniApp input on the Apple TV's App Switcher. Linked Apple TV then names the Apple TV.
  4. Fill the tile, one of two ways:
  • Search: pick Search Service (or leave Any), type the title in Search For (the search runs right away, or use the Search action), then pick the match in Search Results. Link URL, Tile Image URL and Tile Name fill in.
  • Manual: paste the title's web URL into Link URL, paste a poster image URL into Tile Image URL, and set Tile Name.
  1. If the poster did not appear, run Grab Image for Tile, then Refresh Navigators.
  2. Select the tile in the room to test, or run Test Open Link.

For several tiles with different posters, use the Generate Tile Driver workflow below instead of adding the same driver many times.

Per-tile posters: Generate Tile Driver

Control4 shares a driver's icon files across every copy of that driver, so many copies of Custom Mini App all show whichever poster was grabbed last. This is a Control4 limitation. The fix is one driver file per tile:

  1. Add one Custom Mini App as your reusable "builder".
  2. Fill it (Search, or paste a link). Name, link and poster fill in.
  3. Run Generate Tile Driver. Tile Driver Download fills with a download link.
  4. Open that link in a browser and download the dedicated .c4z (poster built in, name and link preset).
  5. Add the downloaded driver in Composer and bind it to a MiniApp input on the Apple TV's App Switcher.
  6. Repeat from step 2 for the next tile.

Properties

  • Driver Version: read only.
  • Tile Name: default Custom Link. Name on the tile and, with Auto-Rename on, the device name in the project tree.
  • Auto-Rename Device: On (default) or Off.
  • Service Filter: type text to narrow the Search Service list.
  • Search Service: Any (default) or one service. The default list is Amazon Prime Video, Apple TV+, Disney+, Paramount+, Peacock and Pluto TV; the driver refreshes it from the resolver.
  • Search For: type a title. Searching starts as soon as you set it.
  • Search Results: pick a match to fill Link URL, Tile Image URL and Tile Name.
  • Link URL: the web link the tile opens. YouTube links also fill name and thumbnail.
  • Tile Image URL: poster or image link. Setting it grabs the image right away.
  • Status: read only. Hints and results.
  • Tile Driver Download: read only. Link to the generated tile driver.
  • Linked Apple TV: read only. The Apple TV this tile is bound to, or not bound yet.
  • Resolver URL: Papaya resolver address. Leave at the default.
  • Debug Mode: Off (default) or On.

Actions

  • Search: runs a search with Search Service and Search For.
  • Grab Image for Tile: downloads Tile Image URL into the tile's icon. Refresh Navigators afterwards.
  • Test Open Link: sends Link URL to the bound Apple TV now.
  • Clear Tile Image (restore default): clears the saved image. Re-add or update the driver to get the default icon back.
  • Generate Tile Driver: builds a dedicated tile .c4z and puts its download link in Tile Driver Download.

Programming

Commands:

  • OPEN: opens this tile's link on the Apple TV it is bound to.
  • SET_LINK (Link): sets Link URL and opens it.

Events:

  • Link Opened: the tile's link was opened.
  • Tile Image Captured: the tile art was set (Refresh Navigators to see it).

Variable: APP_NAME holds the Link URL. The Apple TV driver reads it when the tile is selected; that is how picking the tile becomes a deep link.

No conditionals.

Connections and bindings

  • Custom Link (RF_MINI_APP output): bind to a MiniApp input (1 to 25) on the Apple TV by Papaya App Switcher. Required.
  • The tile has a media player proxy. Remote keys pressed while the tile is selected are passed to the Apple TV through the App Switcher.

Best practices

  • Use a link from a service that deep-links on Apple TV. Apple TV+, Disney+, Peacock and Pluto TV open the title with no prompt. Prime Video, Paramount+ and YouTube open it after one "Open" tap; turn on Auto-Press Open on the Apple TV driver.
  • Netflix, Hulu and Max links only open the app. You can still make an "open the app" tile with them.
  • Use Generate Tile Driver when a room has more than one custom tile.
  • Keep one builder copy for making tiles; the generated drivers are the real tiles.
  • Poster art is saved in the driver and restored after driver updates.

Troubleshooting

  • Tile opens the app but not the title: the service is app-launch only on Apple TV, or the Apple TV driver is out of date. Update the Apple TV driver.
  • Nothing opens: check the tile is bound to a MiniApp input on the App Switcher and Linked Apple TV names the Apple TV. Status "Not bound to an Apple TV yet" means no binding.
  • Status "No Link URL set": fill Link URL or use Search.
  • Remote does nothing while on the tile: see the Apple TV driver's Tile Remote Keys property and its troubleshooting.
  • All tiles show the same poster: Control4 shares icons across copies of one driver. Use Generate Tile Driver.
  • Status "Image fetch failed": the image link is wrong or unreachable. Check the URL and the controller's internet.
  • Status "Downloaded the image but could not write the icon files": needs OS 3.3.0 or newer. Turn Debug Mode On and retry to see details.
  • Poster set but not showing: Refresh Navigators.
  • Search failed or no results: check internet and Resolver URL. Only deep-linkable services are searchable. YouTube is not searchable; paste the video link instead.
  • Status "Generate failed": the resolver could not be reached or returned an error. Retry; check internet.
  • Device name changed unexpectedly: Auto-Rename Device is On. Set it Off to keep your own name.

Limitations

  • Apple TV only, through Apple TV by Papaya.
  • Copies of the same driver share one icon. Per-tile art needs a generated tile driver.
  • Deep links depend on each streaming app. Netflix, Hulu and Max open the app home.
  • Search, posters and tile generation need internet.
  • The poster cannot be changed per device by any Control4 API; the generated driver is the only way.

Version history highlights

  • 1.0.20: driver code encrypted. No functional changes.
  • 1.0.19: Generate Tile Driver for per-tile posters.
  • 1.0.18: YouTube links auto-fill the tile name and thumbnail.
  • 1.0.15 to 1.0.17: search list limited to services confirmed to deep-link on hardware; YouTube removed from search.
  • 1.0.11: remote keys work while the tile is selected.
  • 1.0.10 and earlier: core tile, search, Grab Image, self-healing icons, auto-rename, Linked Apple TV.

Still stuck? Ask Fixxy (bottom right) or open a ticket.