Skip to main content

Per-User Collection Targeting

Control which Plex users see specific collections on their homescreen. By default, rotated collections are visible to everyone. With per-user targeting, you can restrict a group's collections so only certain users see them.

Use Cases​

  • Show anime collections only to users who watch anime
  • Keep kids' content groups visible only to family profiles
  • Target niche genre groups to the users who care about them
  • Run different homescreen experiences for different household members

How It Works​

Targeting is configured at the group level. When you assign target users to a group, only those users will see that group's collections after a rotation. Everyone else gets the collections hidden from their homescreen.

Under the hood, homescreen-hero uses Plex's label-based sharing restrictions:

  1. Collections selected during rotation get an Hsh-hide-{username} label added for each excluded user
  2. Each excluded user's Plex sharing settings are updated to filter out content with their hide label
  3. The result: targeted collections appear on the homescreen for allowed users and are invisible to everyone else

Labels are cleaned up automatically when collections rotate off the homescreen.

Setting Up Targeting​

1. Enable Authentication​

Per-user targeting requires authentication to be enabled with the Plex or Both auth method. This is how homescreen-hero discovers your Plex users.

2. Configure Target Users on a Group​

  1. Go to the Groups page and select a group
  2. Click the User Targeting section
  3. Select which users should see this group's collections
  4. Save the group

Leave the target users empty (the default) to make the group visible to everyone.

3. Run a Rotation​

Targeting is applied during rotation. After running a rotation (manual or scheduled), the labels and sharing filters are synced automatically.

Managing Targeting​

Sync Filters​

If user targeting gets out of sync (e.g., after adding new Plex users), filters are automatically re-synced during the next rotation. You can also trigger a sync via the API endpoint POST /api/admin/user-targeting/sync.

Clear All Targeting​

To remove all targeting labels and filters at once, use the Clear User Targeting Labels tool on the Tools page. This removes every Hsh-hide-* label from all collections and cleans all user sharing filters. Useful if you want to start fresh or disable targeting entirely.

Important Notes​

  • Targeting requires Plex Media Server 1.43.1+ due to a bug fix in how Plex handles label restrictions
  • The server owner (admin) is never excluded from collections
  • Plex auto-capitalizes the first letter of labels, so homescreen-hero uses Hsh-hide- as the prefix
  • Targeting works with both regular and smart groups
  • Labels are applied during rotation and cleaned up when collections rotate off

Config Reference​

Target users are set per group in config.yaml:

groups:
  - name: Anime Night
    enabled: true
    target_users:
      - AnimeLover
      - WeekendWatcher
    collections:
      - Studio Ghibli Films
      - Anime Essentials

When target_users is omitted or set to null, the group is visible to all users.