Plex

Sell access to your Plex server - every order invites the client's Plex account and shares exactly the libraries their plan includes.

What it does

Running a paid Plex server usually means manually inviting every subscriber and remembering which libraries each of them paid for - and remembering to revoke access again when they stop paying. The Plex module automates all of that: a paid order invites the client's Plex email to your server and shares the libraries their package includes, a cancelled order removes the share again, and a client who buys more than one plan keeps everything they already have rather than losing access to it.

Key features

• Automatic Library Sharing: A paid order invites the client's Plex email to your server and shares the libraries their package includes, with no manual invite to send. Cancelling removes the share again, and the friendship only when nothing else is shared with that account.
• Pick Libraries by Name: Build a package by ticking the libraries off your actual Plex server in a named picker, instead of hunting for section IDs. If the server cannot be reached the module falls back to entering IDs by hand, so package editing never blocks.
• Server Auto-Discovery: Paste your Plex token, click Fetch Servers, and pick your server from the list - the server and machine identifiers are filled in for you, and can still be typed in manually if you prefer.
• Library Add-Ons at Checkout: Offer extra libraries as a configurable option and they are added on top of the package's base libraries when the client orders, so upsells need no extra package.
• Share Settings per Package: Decide per package whether subscribers may download and sync media for offline playback, whether they may upload their camera roll, and which movie and TV content ratings they are limited to.
• Several Plans on One Plex Account: A client who buys more than one plan keeps everything they already have - new libraries are merged into their existing share rather than replacing it, and suspending one plan only pulls that plan's libraries.
• Client Libraries Tab: Clients see exactly which libraries are shared with them, by name, on their own Libraries tab.
• Built-In Demo Mode: A built-in Mock API mode runs the whole module from bundled sample data, so you can try out every screen and action before you have a Plex account or token to hand.

Installing Plex

Before you start

• If you are on the leased (subscription) licence, the Blesta Club Subscription Manager must be installed and your subscription active. The owned and owned-source licences have no such requirement.
• You will need a Plex account and its Plex Token to provision real shares. If you just want to try the module out first, you don't need one: a built-in Mock API mode runs the whole module from bundled sample data.

1. Upload the files

Upload the extension folder into your Blesta installation so it lands under your Blesta directory at:

components/modules/plex/

For example, on a typical install: /var/www/html/blesta/components/modules/plex/

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has the Modules permission under the Settings group in Manage Staff Groups.
2. Go to Settings > Company > Modules and click the Available tab.
3. Find Plex in the list and click Install.

3. Configure it

1. Under the Installed tab, click Manage next to Plex.
2. Click Add Server, then enter your Plex Token. Click Fetch Servers to load the servers on your account into the Discovered Servers dropdown and pick one - the Server ID and Machine ID fields fill in for you. If discovery is unavailable you can enter these by hand (see the usage guide for where to find them).
   • To try the module without a real Plex account, tick Enable Mock API instead - the server then serves built-in sample data for every library and share action, and any token is accepted.
   • The token, Server ID and Machine ID are checked against plex.tv as soon as you save a live server, so a bad value is caught immediately rather than at the first order.
3. Create a package on this module (or edit an existing one) and choose the Libraries it shares - a named picker lists your server's libraries by title when it can be reached, otherwise enter one library section ID per line. Set the package's share settings alongside it: Allow Downloads / Sync, Allow Camera Upload, and the Movie Rating Filter / TV Rating Filter text fields.
4. Optionally, load the welcome email template that ships with the module onto the package from its Welcome Email tab, so new clients are emailed their Plex access details automatically.

You're ready to go - see the usage guide for a walkthrough of day-to-day use.

Updating Plex

Upgrading works just like installing: upload the new files over the old ones, then run the upgrade from the same page you installed it on.

1. Back up your current extension files first - good practice before any upgrade.
2. Upload the new version over the existing folder at components/modules/plex/, replacing the old files.
3. Log in to your Blesta admin area and go to Settings > Company > Modules.
4. Find Plex under the Installed tab and click Upgrade to run the upgrade, if shown.

Version-specific notes

• Upgrading from 1.0.1: that version stored the Plex Token in plain text, listed it as a column on the Servers page, and offered it as a {module.plex_token} email tag - so it could have been mailed out or read by anyone with access to those pages. Later versions encrypt it, drop it from the Servers list and remove the email tag. Because the old token may have been exposed, sign in to Plex and sign out of the device the token belongs to (this invalidates it), get a fresh token (see the usage guide), then edit each Plex server in Blesta and paste the new token in - leaving the Token field blank keeps whatever is already stored, so nothing changes until you do this.
• Beyond that, upgrading is drop-in - no other steps or data migrations are needed. Packages and servers saved under an older version keep working as before.

Using Plex

Adding a Plex server

Go to Settings > Company > Modules > Installed > Plex > Manage and click Add Server.

1. Token: paste your Plex Token. To find it, sign in to the Plex Web App, browse to any library item, click Get Info, view the XML and locate the X-Plex-Token value in the URL.
2. Server ID & Machine ID: click Fetch Servers. The module loads the servers on your Plex account into the Discovered Servers dropdown - pick yours and the Machine ID and Server ID fields fill in automatically. If discovery is unavailable you can still enter the values by hand: browse to https://plex.tv/api/servers?X-Plex-Token={YOUR_PLEX_TOKEN}, view the source, and find the machineIdentifier attribute on your <Server> tag.
3. Enable Mock API (optional): tick this to have the server respond with built-in sample data instead of contacting plex.tv. Any token is accepted and no real share is ever created - use it to try the module out or demonstrate it before you have a server to point it at. Leave it unticked for live use.

The Token, Server ID and Machine ID are checked against plex.tv when you save a live server, so an incorrect value is reported straight away rather than at the first order. Editing a server later leaves the Token field blank - leave it blank to keep the one already stored, or paste a new one to replace it.

Choosing the libraries a package sells

On a package's Module settings, set which of your Plex libraries it shares:

• Libraries: when your server can be reached, this is a named picker listing your libraries by title - tick the ones this package includes. If the server can't be reached the field falls back to a plain text box: enter one library section ID per line (find them at https://plex.tv/api/servers/{YOUR_MACHINE_ID}?X-Plex-Client-Identifier=Blesta&X-Plex-Token={YOUR_PLEX_TOKEN}, inside the <Server> tag as <Section id>). At least one library is required.
• Share settings, on the same page: Allow Downloads / Sync and Allow Camera Upload are on/off, and Movie Rating Filter / TV Rating Filter accept a Plex content-rating string, if you want to cap what subscribers on this package can see.

Selling extra libraries as an add-on (optional)

Create a Blesta configurable option named libraries, of type Select or Checkbox (not Text - see below), whose option values are the library section IDs you're willing to sell, and attach it to the package. A client who picks it at order time gets those libraries in addition to the package's base set.

Use Select or Checkbox rather than Text: a Text option lets a client type any value themselves. The module won't honour a library ID your server doesn't publish, but only the option type stops a client from requesting a library you sell elsewhere but didn't mean to include in this add-on.

Managing an order

Placing, suspending, unsuspending and cancelling a service works the same as any other Blesta module:

• Ordering invites the client's Plex email to your server (or merges into their existing share, if that email already holds another service on the same server) and grants the package's libraries plus any add-on libraries chosen at checkout.
• Suspending removes only the libraries this particular package granted - it never removes the client's Plex friendship, so reactivating restores their access instantly and any other service on the same email is untouched.
• Cancelling removes the share, and removes the Plex friendship itself only if the client has no other share left on the account.
• Opening a service from the client's profile and going to its Upgrade/Downgrade panel shows the module's own Plex ID and Plex Email fields. Plex ID is a staff-only escape hatch for attaching an existing share by its ID without going through the API - leave it blank to let the module create the share normally.

Clicking a Plex service in the client's profile Services list expands an inline panel showing the invited Plex Email, the Plex Share ID, and whether the share is currently Active or Inactive, so you can answer "does this client have access?" without opening Plex.

For your clients

Clicking a Plex service on their own Services page expands the same kind of panel, showing their invited Plex Email and Active/Inactive status (the Plex Share ID is admin-only and isn't shown to them). Opening the service's Libraries tab lists exactly which libraries are currently shared with them, by name - or a message saying none are shared yet, if the share hasn't been granted, or has since been suspended or cancelled.

Email tags

If you write your own service or welcome email templates, these merge fields are available:

• {module.server_id} and {module.machine_id} - the Plex server's ID and machine identifier.
• {package.libraries} - the package's configured library IDs.
• {service.plex_email} and {service.plex_id} - the subscriber's invited Plex email and share ID.

A ready-made welcome email is included with the module - open a package's Welcome Email tab and click Load Sample Email to use it as a starting point.

Good to know

• Mock mode is per-server: any server with Enable Mock API ticked serves sample data for every package and service that uses it, so you can build and test packages, orders, suspends and cancels end to end with no Plex account at all.
• A service that was provisioned while its server was in Mock API mode keeps serving mock data for that service even if you later switch the server to live - it won't suddenly try to act on a real Plex account.