Install and publish Audisode

1How it fits together

Your listeners use the app. The app talks to your backend for everything that matters: the catalogue, coins, unlocks, and the links to the audio. You use the admin panel, which is part of the backend, to manage it all. Around them sit a few outside services, shown in the diagram.

Dashed outlines and lines mark the optional parts.

1. App and backend. Everything the app shows and does goes over HTTPS as JSON to the backend's /api.
2. App and Firebase. Google and Apple sign-in happen in Firebase. The app then sends Firebase's proof of identity (an ID token) to your backend.
3. App and RevenueCat. The RevenueCat SDK in the app shows the store prices and runs the purchase.
4. App and AdMob. The AdMob SDK in the app loads banner, full-screen and rewarded ads.
5. Backend and Firebase. The backend checks every sign-in token with Firebase, and sends push notifications through Firebase Cloud Messaging.
6. Backend and RevenueCat. The backend asks RevenueCat's REST API what a listener owns. RevenueCat also calls the backend's webhook when something changes.
7. AdMob and backend. When a listener finishes a rewarded ad, AdMob calls /api/admob/ssv with a signed message. Only then are coins granted.
8. Backend and cloud storage (optional). Audio can sit in a private S3 or Cloudflare R2 bucket instead of your server.
9. Backend and AI voices (optional). The AI narration page sends text to OpenAI or ElevenLabs and stores the audio they return.

2Requirements

Check these before you start. The accounts take the longest: some need approval from Apple or Google, which can take days.

2.1Server

2.2Accounts

2.3Your computer

3What is in the package

Unzip the package. This is what you will find:

audisode-v1.0.0/
  START_HERE.html          opens this guide
  CHANGELOG.md             what changed in each version
  THIRD_PARTY_NOTICES.md   licences of the open-source parts
  docs/                    this guide (index.html), its images, a PDF copy
  audisode_backend/        the server: Laravel 12 API and admin panel
  audisode/                the mobile app: Flutter, Android and iOS

3.1What is not included, and why

Nothing that belongs to a previous owner is in the package. You create your own:

• Your .env file, with your database password and keys. You make it from .env.example.
• Your Android keystore and android/key.properties. See section 16.1.
• Firebase files: google-services.json, GoogleService-Info.plist and lib/firebase_options.dart. The app will not build until you create them (section 9).
• Ad IDs: the app ships with Google's test IDs.
• Apple team: you choose yours in Xcode.

4Install the backend~20 minServer

Pick the path that matches your hosting. All three end in the same place: an admin panel you can sign in to.

4.1A. Server with SSHRecommended

1. Create a database and a user. In your hosting panel, or with these commands in the MySQL client (change the names and the password):

   sqlCopy

   CREATE DATABASE audisode CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'audisode_user'@'localhost' IDENTIFIED BY 'choose-a-strong-password';
   GRANT ALL PRIVILEGES ON audisode.* TO 'audisode_user'@'localhost';

2. Upload the audisode_backend folder to your server. If your host allows it, put it outside the public web folder.

3. Point the domain's document root at the public/ folder inside it. This matters: everything else in the folder (your .env file, logs, source code) must not be reachable from the web.

4. Install the PHP packages. Skip this step if the folder already contains vendor/.

   bashCopy

   cd /path/to/audisode_backend
   composer install --no-dev --optimize-autoloader

5. Create your settings file.

   bashCopy

   cp .env.example .env

   Open .env and set at least these lines. Leave APP_ENV=production, APP_DEBUG=false and APP_KEY (the installer fills it in).

   dotenvCopy

   APP_NAME="Your Brand"
   APP_URL=https://your-domain.com
   DB_DATABASE=audisode
   DB_USERNAME=audisode_user
   DB_PASSWORD=choose-a-strong-password
   MAIL_MAILER=smtp
   MAIL_HOST=mail.your-domain.com
   MAIL_PORT=587
   MAIL_USERNAME=hello@your-domain.com
   MAIL_PASSWORD=your-mail-password
   MAIL_FROM_ADDRESS="hello@your-domain.com"

   APP_NAME is your brand name. It appears in the admin panel, the sign-in pages, emails and the public website. Every key is explained in section 5.

6. Run the installer.

   bashCopy

   php artisan app:install --demo

   It prints Installing Audisode v1.0.0, asks for your licence key and username (the email you bought with) and activates the licence for your domain. Then it creates the tables and default settings, adds an English language and a few categories (because of --demo), and asks for the admin email and password you will sign in with (at least 8 characters).

   It ends with a configuration checklist. Lines marked TODO are normal at this point: they are the later sections of this guide. The command is safe to run again.

   These options skip the questions, which helps in scripts:

   Option	What it does
   --license-key= and --license-username=	The licence from your purchase.
   --admin-email= and --admin-password=	The admin account.
   --demo	Adds an English language and a few categories, so you can add books straight away.
   --sample-books	Also adds seven English sample audiobooks with authors and covers, so the app has something in it from the first minute. Delete them before you launch. Includes what --demo adds.

7. Add the scheduler to cron. Run crontab -e and add this line, with your path. It runs push notifications, AI narration jobs and the daily clean-up:

   cronCopy

   * * * * * cd /path/to/audisode_backend && php artisan schedule:run >> /dev/null 2>&1

8. Check that your settings file is not public. This must print 404 or 403, never 200:

   bashCopy

   curl -s -o /dev/null -w "%{http_code}\n" https://your-domain.com/.env

9. Sign in at https://your-domain.com/login with the admin email and password you chose. Continue with the first sign-in below.

4.2B. cPanel shared hosting, no SSH

You do not need a terminal. The backend has a web installer that asks the same questions in your browser. It needs a package that already contains the PHP packages.

1. Check for audisode_backend/vendor. If the folder exists, carry on. If it does not, run composer install --no-dev --optimize-autoloader inside audisode_backend on your own computer first, then upload the folder together with the new vendor/.

2. Create a database and a user in cPanel under MySQL Databases. Add the user to the database with all privileges. cPanel puts your account name in front of both names (for example account_audisode): use the full names later.

3. Choose PHP 8.2 or newer in MultiPHP Manager, and in Select PHP Version make sure the extensions pdo_mysql, openssl, mbstring, gd, fileinfo, curl and zip are ticked.

4. Upload and unzip the audisode_backend folder with File Manager. Turn on Show Hidden Files and check that .env.example and .htaccess are there: hidden files are easy to lose.

5. Point the domain at audisode_backend/public. In cPanel open Domains (or Subdomains) and set the document root of your domain or subdomain to that folder.

6. Open your site in a browser. A copy that is not installed yet sends every page to /install. If a screen says it cannot write .env, make the project folder writable (permissions 775) for the installation and put it back afterwards.

7. Click through the installer. It has five screens.

8. Add the cron job. In cPanel open Cron Jobs, choose Once Per Minute and paste the command shown on the finish page. It looks like this:

   cronCopy

   * * * * * cd /home/youraccount/audisode_backend && php artisan schedule:run >> /dev/null 2>&1

   If php on your host is an older version than 8.2, use the full path of PHP 8.2 instead (on cPanel it is often /opt/cpanel/ea-php82/root/usr/bin/php).

9. Check that your settings file is not public. Open https://your-domain.com/.env in a browser. You must see an error page (404 or 403), never a list of settings.

When the installer has finished, every /install page is a 404. It only runs while there is no storage/app/installed file and no APP_KEY, so a site that is already set up is never offered the installer. To install from scratch again, delete .env and storage/app/installed.

4.3C. Your own computer

The quickest way to see the admin panel working. You need PHP 8.2 or newer and Composer 2 on your computer. The licence step still asks for your key, so you need internet. Local addresses (localhost, *.test and private IP addresses) do not use up an installation of your licence.

1. Install the packages (skip it if vendor/ exists) and create the settings file:

   bashCopy

   cd audisode_backend
   composer install
   cp .env.example .env

2. Edit .env for development. A SQLite file is the easiest database: create an empty file and point to it with an absolute path.

   bashCopy

   touch database/database.sqlite

   dotenvCopy

   APP_ENV=local
   APP_DEBUG=true
   APP_URL=http://127.0.0.1:8000
   DB_CONNECTION=sqlite
   DB_DATABASE=/full/path/to/audisode_backend/database/database.sqlite
   SESSION_DRIVER=file
   CACHE_STORE=file
   MAIL_MAILER=log

   Or use a local MySQL database exactly as in path A. APP_DEBUG=true shows error details; never use it on a live server. MAIL_MAILER=log writes emails to storage/logs/laravel.log instead of sending them.

3. Install and start:

   bashCopy

   php artisan app:install --sample-books
   php artisan serve

   Open http://127.0.0.1:8000/login.

4.4Your first sign-in

Go to https://your-domain.com/login and sign in with the admin email and password you chose. After five wrong tries the sign-in pauses for a short while.

The dashboard is your home page: listeners, active listeners, Premium subscribers, estimated revenue, a chart of new listeners or coin flow, your top books and the coin economy. Switch between 7, 30 and 90 days at the top; every number is compared with the period before.

What "Needs attention" means

This list shows problems and unfinished setup. Each item links to the page that fixes it:

• The licence needs attention, or a new version is available.
• Narrations failed, or are in progress.
• Single-audio books without audio, and series without episodes: listeners cannot play these yet.
• Notifications failed this week: check the Firebase credentials.
• Low ratings this week (one and two stars) worth a look.
• In-app purchases are not set up, or the RevenueCat webhook is not secured: see section 10.
• Push notifications are not set up: see section 12.
• AI narration is not set up: optional, see section 7.5.

4.5Background jobs and the queue

Push notifications and AI narration run in the background. On hosting without a process manager you do nothing extra: the cron entry above runs the scheduler every minute, and the scheduler starts a short-lived queue worker each time. That is enough on shared hosting.

If you run the worker yourself with Supervisor or systemd, tell the scheduler not to start its own, and keep the retry time longer than your longest job:

QUEUE_RUN_VIA_SCHEDULER=false
DB_QUEUE_RETRY_AFTER=960

DB_QUEUE_RETRY_AFTER must stay above 900 seconds, because a long AI narration can take up to 15 minutes. A sample Supervisor configuration:

[program:audisode-worker]
command=php /path/to/audisode_backend/artisan queue:work --sleep=3 --tries=3 --max-time=3600
process_name=%(program_name)s_%(process_num)02d
numprocs=1
user=www-data
autostart=true
autorestart=true
stopwaitsecs=3600
redirect_stderr=true
stdout_logfile=/path/to/audisode_backend/storage/logs/worker.log

After you deploy an update, run php artisan queue:restart so the worker picks up the new code. The scheduler still needs its cron line: it sends the daily reminders and does the clean-up.

4.6File permissions

The web server user must be able to write to storage/ and bootstrap/cache/. If you see a blank page or a 500 error after uploading, this is the usual cause. On a server with SSH (replace www-data with your web server's user):

cd /path/to/audisode_backend
chown -R www-data:www-data storage bootstrap/cache
find storage bootstrap/cache -type d -exec chmod 775 {} \;
find storage bootstrap/cache -type f -exec chmod 664 {} \;

On cPanel, select those two folders in File Manager and set the permissions to 775.

5The .env reference

The .env file in audisode_backend holds your settings and secrets. This section lists every line of .env.example, in the same order, so you can see what each one does.

Where a value contains spaces or a #, put it in double quotes. Anything marked Leave works as it is.

5.1App

The basics. Most of these you set once.

5.2Database

The empty database you created in the install step.

5.3Sessions, cache and queue

These work as they are. The backend runs on the database drivers, so you need no Redis or Memcached.

5.4Mail

Password-reset emails for admins and for app users, and admin invitations. Until you set this up, emails are only written to the log.

5.5Admin and demo admin

Only used by php artisan db:seed, the alternative to app:install. The installer and app:install ask you for the admin email and password instead.

5.6Firebase sign-in

So the backend can check who is signing in, and end a listener's Sign in with Apple when they delete their account. See section 9.

5.7RevenueCat

Coin packs and Premium. See section 10.

5.8App identity

Fallbacks for shared book links. Settings > App links takes precedence.

5.9Revenue currency

5.10Rewarded ads

See section 11.

5.11Audio and cloud storage

See section 14. With the defaults, audio stays on your server.

5.12Push notifications

See section 12.

5.13AI narration

Optional. See section 7.5. Providers bill per character.

5.14Background jobs

See the queue.

5.15Keys that are not in the template

You can add these lines yourself.

6The admin panelAdmin panel

The admin panel is where you run the business. This section walks through each page in the order of the left-hand menu. Sign in at https://your-domain.com/login.

• Press Ctrl or ⌘ + K anywhere to search books, episodes, authors and listeners, or to jump to a page. Press / to focus the search box on the page you are on.
• The Create button at the top has shortcuts for a new book, episode, bulk upload, AI narration and notification.
• The half-moon button at the top switches between light, dark and system themes.
• The menu at the top right holds your Account, the app settings, a link to your public website, and the product version.
• A small orange dot next to AI Narration or Notifications means that feature is not set up yet.

6.1Dashboard

The home page, shown in section 4. Use it to see how the business is doing and what needs doing.

• Switch between 7, 30 and 90 days. Every number is compared with the period before.
• Cards for listeners, active listeners, Premium subscribers, estimated Premium income per month, estimated coin pack income and invited listeners.
• An activity chart (new listeners, or coin flow), your top books by listeners, coins spent and views, and the coin economy: coins earned and spent, and where they came from.
• The Needs attention list of problems and unfinished setup, each linking to the page that fixes it.

6.2Books

Your catalogue. A book is either a single audio (one file) or a series (episodes).

• Search, and filter by format, category, language, author or featured. Sort by newest, oldest, title, highest rated or most viewed. Switch between a table and a cover grid.
• New book asks for the title, summary, author, category, language, a cover image and, for a single audio, the price in coins and the audio.
• For a series the price is set on each episode instead, and you add the episodes on the Episodes page or with Bulk upload.
• A price of 0 makes a book free. Premium subscribers always listen for free.
• Star a book to feature it on the home screen.
• The filter links from Needs attention show books without audio and series without episodes.

6.3Episodes

Open a series to see its episodes in order.

• Add episodes one at a time: title, number, price, and the audio (upload or link).
• Preview each episode's audio on the page.
• Set a price per episode. Making the first few free is the usual way to hook listeners.
• Episode numbers must be unique within a series.

6.4Bulk upload

Add a whole season in one go. Section 7.4 explains it step by step.

• Choose the series, the first episode number, the price per episode and how many are free.
• Drop the audio files in. A preview table shows the order, titles and sizes before you send anything.
• The page checks the files against your server's upload limits and warns you before uploading.

6.5Home screen

Decides what listeners see when they open the app.

• Sections you can show, hide and reorder: Premium offer, Daily check-in, Continue listening, Recommended for you, Featured, Recently added, New episodes, Series, Browse by category, Trending this week, Listeners are saying, Free to listen, Your week, Top rated, Top 10, Author spotlight and Authors.
• Sections tagged Personal are filled in by the app from each listener's own activity. You only decide whether they appear and where.
• Most sections let you type a heading of your own.
• Collections you create appear here too. Reset restores the original order.

6.6Collections

Hand-picked shelves, such as "Staff picks" or "Summer thrillers".

• Create a collection with a heading and a short description, then add books and put them in order.
• A new collection is placed under Featured on the home screen; move it on the Home screen page.

6.7Authors

• Add authors with a name, a photo and a short bio.
• Authors who have a bio can be featured in the home screen's Author spotlight, and the bio shows on their page in the app.
• Listeners can follow an author and get an alert when a new episode arrives.

6.8Categories

The topics listeners browse by, such as Fiction or Kids. Add, rename and delete them here.

6.9Languages

The languages of your audiobooks. Listeners pick one in the app, and the home screen shows books in that language. This is separate from the language of the app's own text; see section 15.9.

6.10AI NarrationOptional

Paste text and a voice reads it aloud. See section 7.5.

• Choose a book and a voice, paste the text. For a series it becomes a new episode (title, number, price); for a single audio it replaces the audio.
• Long text is split on sentence boundaries and joined into one MP3.
• Failed jobs can be retried or deleted. It needs an API key in .env.

6.11Listeners

Everyone who uses the app.

• Search by name, email or invite code. Filter by Premium, suspended or active.
• Each listener's page shows listening time, books started, unlocks, recently played, subscriptions, coin pack purchases and the full coin history.
• Adjust coins: set a new balance and give a reason. The listener sees the reason in their coin history.
• Suspend signs the listener out on every device and blocks the app. Store subscriptions keep billing; refund them in Google Play Console or App Store Connect if needed. You can restore the account later.

6.12Reviews

• A rating summary, search and filters, including low ratings.
• Hide removes a review from the app and from the book's rating, and you can bring it back. Delete removes it for good.

6.13NotificationsOptional

Send an announcement to listeners' phones. It needs Firebase push set up first: section 12.

• Write a title and message, choose who gets it (everyone, Premium subscribers, or free listeners), and choose whether tapping opens the app or a particular book.
• The page shows how many devices each audience reaches.
• New-episode alerts and check-in reminders go out automatically; you only switch them on in Settings.

6.14Settings

How the app rewards, sells and talks to listeners. Changes reach the app the next time it loads its settings. Use the list at the left to jump between sections, then press Save settings at the bottom. There are nine sections.

Coins & rewards

Welcome coins are given once when a listener creates an account. Rewarded ad is the number of coins for watching a rewarded video to the end.

Daily check-in

Coins for each day of a seven-day streak. Missing a day starts the streak over. The page adds up a full week for you.

Ads

A master switch for every ad, then banner ads, full-screen ads, how often a full-screen ad may appear (at most one every N plays and never more often than the interval), and how many rewarded ads one listener may watch per day (0 means no limit). Premium subscribers never see ads.

Invite friends

Every listener has an invite code. A new listener can enter a friend's code in their first 7 days and both get coins. Set the rewards, and the monthly limit of rewarded invites per inviter (0 means no limit; a cap limits abuse with fake accounts).

Store products

The coin packs and Premium plans the app sells. Remove every Premium plan to hide Premium in the app.

Notifications

Switch on new-episode alerts (to followers of the author and listeners who played or saved the book) and check-in streak reminders, and choose the reminder hour in your server's time zone. Listeners can still turn each kind off in the app.

Branding

Your name, accent colour, logo and favicon for the admin panel, sign-in pages, public website and shared book pages. The name replaces APP_NAME on web pages and in emails. Choose an accent colour dark enough for white button text (the form tells you if it is not). Logos are PNG, JPG or WEBP up to 1 MB; favicons PNG or ICO up to 256 KB; SVG is refused on purpose. The mobile app has its own name, icon and colours: section 15.

App links

Where shared book links lead. Section 13 explains it.

Legal pages

Your privacy policy, contact us and about us text, written in a simple editor. They show in the app (Profile menu) and on the public website at /page/privacy_policy, /page/contact_us and /page/about_us. Both stores require a privacy policy, so fill it in before you submit.

6.15Team

Everyone who can sign in to the panel. Under System in the menu.

• Add and invite creates the account and emails the new admin a link to choose their own password. If the server has no real mail set up yet, the page shows the link for you to send by hand.
• The link works for 60 minutes. Invite again sends a new one.
• You cannot remove yourself, and the last admin can never be removed.
• Admins can change everything in the panel. Only add people you trust.

6.16License

The licence for this copy. Under System in the menu.

• Shows the status, a masked licence key, the domain, installations used, the date support ends and whether a newer version exists.
• Check now asks the licence server straight away. The scheduler also checks once a day.
• Move this licence gives the domain back so you can use the licence on another site. A subdomain counts as a different domain.
• If the licence server cannot be reached, nothing changes: the product keeps running on the last answer. Only a refusal from the server shows a notice, with its reason.

6.17Account

Your own sign-in details: top-right menu, Account.

Change your name, email or password. Changing the email or the password asks for your current password and signs out every other browser.

6.18The public website

Your domain's home page (/) is a small public website with your name, store badges and links to the legal pages. The store badges appear only for the stores whose links you filled in under Settings > App links. The admin sign-in is a small link in the footer.

A shared book link (https://your-domain.com/book/12) opens a page with the book's cover and summary and sends phones on to the app or the store. See section 13.

7Adding contentAdmin panel

Work through the left-hand menu from top to bottom. This is the order that saves you backtracking: a book needs an author, a category and a language to exist first.

7.1Languages, categories and authors

1. Languages. The installer added English if you used --demo or --sample-books. Add the languages your audiobooks are in. Listeners pick one in the app and see books in that language.

2. Categories. Add the topics listeners browse by (Fiction, Kids, Mystery & Thriller…).

3. Authors. Add each author with a name and, if you like, a photo and a short bio. A bio makes the author eligible for the home screen's Author spotlight.

7.2A single-audio book

One file, one price. Good for a complete audiobook.

1. Open Books and click New book.

2. Choose the format Single audio. Enter the title and summary, and pick the author, category and language.

3. Upload a cover image.

4. Set the price in coins. 0 makes it free. Premium subscribers always listen for free.

5. Upload the audio file, or paste a link to it. See uploaded and linked audio below.

6. Save. Check the dashboard: a single audio without audio shows up under Needs attention.

7.3A series with episodes

Many short episodes under one book. Each episode has its own price, so you can make the first few free.

1. Click New book and choose the format Series. A series has no price of its own.

2. Add episodes one at a time on the Episodes page: open the series, then New episode. Give each a title, a number, a price and its audio.

3. Or add them all in one go with bulk upload.

7.4Bulk upload

The quickest way to add a whole season. In the menu, open Bulk upload (or the Bulk upload button on the Books page).

1. Choose the series the episodes belong to, and the number the first file should get.

2. Choose how titles are made. From file names uses the name of each file; the other choice names them "Episode 1", "Episode 2" and so on.

3. Set the price per episode and how many of the first episodes are free. A free sample hooks listeners.

4. Drop the audio files in. Name them with the number first: 01 Intro.mp3, 02 The Journey.mp3. Files are put in order by the number their name starts with, so Episode 3 - Title.mp3, 03_Title.mp3 and 3 Title.mp3 all sort as 3. With From file names, the number and separators are removed from the title: 03 - The Long Night.mp3 becomes "The Long Night".

5. Check the preview table and click Upload episodes. Followers of the author and listeners who played or saved the book get one notification for the whole batch, not one per episode.

When uploads are rejected for size

PHP limits how much one upload may hold. The Bulk upload page shows your server's limits and warns you before you send. If they are too small, raise them: in cPanel open MultiPHP INI Editor, or edit php.ini (or .user.ini) on your own server.

upload_max_filesize = 256M
post_max_size = 300M
max_file_uploads = 50
max_execution_time = 300

post_max_size must be larger than upload_max_filesize. If you use nginx, also raise client_max_body_size. When even that is not enough, upload big seasons in parts, a few files at a time.

7.5AI narrationOptional

1. Put the key in .env and run php artisan config:cache.

   dotenvCopy

   TTS_PROVIDER=openai
   OPENAI_API_KEY=sk-...
   # or
   TTS_PROVIDER=elevenlabs
   ELEVENLABS_API_KEY=...
   ELEVENLABS_VOICES="Rachel:21m00Tcm4TlvDq8ikWAM,Adam:pNInz6obpgDQGcFmaJgB"

2. Open AI Narration. The orange dot beside it in the menu disappears once a key is set.

3. Choose a book and a voice. For a series, add the episode title, number and price. Paste the text (up to TTS_MAX_CHARACTERS, 50,000 by default) and send it.

4. Wait. The job list refreshes itself. When it finishes, a series gets a new episode (and listeners are notified) and a single-audio book gets its audio replaced.

This needs the scheduler (cron) or a queue worker running: see the queue. A failed job shows on the dashboard; retry it from the AI Narration page.

7.6Arrange the home screen and collections

1. Star the books you want under Featured on the Books page.

2. Make collections ("Staff picks") on the Collections page: a heading, a description, and the books in order.

3. On Home screen, drag the sections into the order you want, switch off the ones you do not need, and give most of them your own heading. Collections show up in the list; move them where they belong.

Sections such as Trending this week stay empty until listeners play books. Changes reach the app the next time it opens.

7.7Audio formats, uploaded and linked audio

Audio can be uploaded as MP3, WAV, M4A, M4B or AAC. (M4B is the usual audiobook format.) Or you can paste a link to audio hosted somewhere else.

8Coins, Premium and the economyAdmin panel

Coins are the app's currency. Listeners earn them or buy them, and spend them to unlock books and episodes. Everything is decided on the server and every price is read from the database, so the app cannot cheat.

8.1How listeners earn coins

8.2How listeners spend coins

• A single-audio book is unlocked at the price set on the book.
• An episode of a series is unlocked at the price set on that episode. There is no "buy the whole series" price: each episode is unlocked on its own.
• Free titles (price 0) and the free first episodes need no coins.
• An unlock is final: coins are deducted and the title is the listener's to keep.
• Listeners with Premium are never charged: everything is open to them.

8.3Premium

• Premium unlocks every book and episode, and removes all ads, while it is active.
• Plans are auto-renewing subscriptions that you set up under Settings > Store products and in the stores. Remove every plan and Premium disappears from the app.
• Cancelling keeps Premium until the period ends. A billing problem keeps it open for the store's grace period.
• Promotional entitlements you grant in the RevenueCat dashboard (a free month for a reviewer, say) work too.

8.4A worked example

You upload a 10-episode series and set 20 coins per episode with the first 2 free.

• A new listener hears episodes 1 and 2 at once, for nothing.
• Episodes 3 to 10 are 8 episodes at 20 coins: 160 coins to hear them all.
• With the default settings, a new listener starts with 50 welcome coins and a full week of check-ins pays another 145 (5, 10, 15, 20, 25, 30 and 40). That is 195 coins, enough to finish the series without paying.
• Or they buy the coins_100 pack twice (200 coins), or subscribe to Premium and listen to everything.

So tune the three numbers against each other: how generous the free coins are, how much each episode costs, and how big the packs are. The dashboard's coin economy chart shows what listeners earn and spend.

9Firebase: sign-in and push~25 min

Firebase checks who is signing in (Google and Apple) and delivers push notifications. Email and password sign-in is handled by your own backend, so you do not need to turn on Firebase's Email/Password provider.

1. Create a project. Open the Firebase console, click Add project and follow the prompts. Google Analytics is optional.

2. Turn on the sign-in providers. In your project open Authentication, then Sign-in method, and enable Google (choose a support email) and Apple. Switch Apple on and save; the key that Apple requires for account deletion is added in Sign in with Apple and the App Store, below. The Apple button shows in the iOS app only.

3. Connect the app to the project. Install and sign in to the Firebase CLI, then run the FlutterFire tool inside the audisode folder. Pick your project and tick Android and iOS. It reads the package name and bundle ID from the project, so check that they are the ones you chose in section 15.

   bashCopy

   npm install -g firebase-tools
   firebase login
   dart pub global activate flutterfire_cli
   cd audisode
   flutterfire configure

   It writes three files:

   • android/app/google-services.json
   • ios/Runner/GoogleService-Info.plist
   • lib/firebase_options.dart

   Google sign-in takes its client IDs from these files, so nothing goes into the Dart code. On Android, google-services.json must contain a web client ("client_type": 3). Firebase adds it once the Google provider is on. If the app says serverClientId must be provided, run flutterfire configure again to refresh the file.

4. Add your Android fingerprints. Google sign-in fails on Android without them. You need up to three SHA-1 fingerprints. Add each in Project settings > Your apps > Android app > Add fingerprint:

   • Debug, for testing. Run ./gradlew signingReport in the android folder.
   • Release, from your upload keystore (section 16.1): keytool -list -v -keystore ~/upload.jks -alias upload.
   • Play App Signing, after your first upload to Google Play. Google re-signs your app with its own key, and releases installed from the store use that key. Copy it from Play Console > Test and release > App integrity > App signing. This is the one people forget: Google sign-in works in testing and fails for real users.

   After adding fingerprints, download google-services.json again (or rerun flutterfire configure) so it includes them.

5. iOS: one value in Info.plist. Open ios/Runner/GoogleService-Info.plist, copy the value of REVERSED_CLIENT_ID, and paste it into ios/Runner/Info.plist in place of REPLACE_WITH_REVERSED_CLIENT_ID (under CFBundleURLSchemes). Without it Google sign-in fails on iOS.

6. Sign in with Apple, on Apple's side. In Apple Developer open Certificates, Identifiers & Profiles > Identifiers, open your app's ID, and tick Sign In with Apple. In Xcode (section 16.2) check that Sign in with Apple is listed under Signing & Capabilities. The project's Runner.entitlements already asks for it. Then add the key for account deletion: see Sign in with Apple and the App Store, below. Apple requires it.

7. Tell the backend. Set your Firebase project ID in the server's .env and refresh the cache. The backend uses it to check every sign-in, so nobody can sign in as someone else just by sending an email address.

   dotenvCopy

   FIREBASE_PROJECT_ID=your-firebase-project-id

   bashCopy

   php artisan config:cache

   The project ID is in Project settings > General.

9.1Sign in with Apple and the App Store

Apple rejects an iOS app that offers Google sign-in without Sign in with Apple next to it (App Review Guideline 4.8). It also requires that people can delete their account inside the app, and that an app with Sign in with Apple ends that link when they do (Guideline 5.1.1(v) and Apple's account-deletion rules). The app already follows all three. The last one needs a key from you, and the key goes into Firebase, not into your backend.

1. Create a key. In Apple Developer open Certificates, Identifiers & Profiles > Keys and click +. Name it, tick Sign in with Apple and click Configure. Choose your app's ID as the Primary App ID, save, and register the key. Download the .p8 file now: Apple lets you download it only once. Write down the Key ID (10 characters).

2. Create a Services ID. Under Identifiers click +, choose Services IDs and give it an identifier such as com.yourcompany.yourapp.signin. Open it, tick Sign in with Apple and click Configure. Choose your app's ID as the primary App ID, add the domain your-project-id.firebaseapp.com, and the return URL https://your-project-id.firebaseapp.com/__/auth/handler. Firebase shows both values under the Apple provider (next step).

3. Give them to Firebase. In the Firebase console open Authentication > Sign-in method > Apple. Fill in Services ID, and under OAuth code flow configuration your Apple Team ID (Apple Developer > Membership details), the Key ID, and the contents of the .p8 file as the Private key. Save. Despite what the form implies, these fields are not optional for deleting accounts: without them Firebase cannot revoke the link.

Test it before you submit

1. On a real iPhone, or a simulator that is signed in to an Apple Account in Settings, tap Continue with Apple and choose Hide My Email. The new listener appears under Listeners with the sign-up type Apple.
2. Delete that account: Profile, the pencil icon, Delete account, then confirm with Apple.
3. On the iPhone open Settings > your name > Sign-In & Security > Sign in with Apple. Your app must no longer be listed.

10In-app purchases with RevenueCat~45 min

Coin packs and Premium are sold through RevenueCat, one service for Google Play and the App Store. The backend never trusts what the app says it bought. It asks RevenueCat what the listener owns, and credits coins or turns Premium on from that answer. Each store transaction is credited once.

10.1How a purchase works

The app calls the sync right after a purchase and when it starts. The webhook covers everything that happens while the app is closed: renewals, expirations, refunds. All of it can repeat safely.

10.2Set it up

1. Create the products in the stores.

   • Coin packs are consumable in-app products. In Google Play Console: Monetize > Products > In-app products. In App Store Connect: your app > In-App Purchases.
   • Premium plans are auto-renewing subscriptions. In App Store Connect create one subscription group and a subscription in it for each plan. In Google Play Console create one subscription for each plan, with one base plan each.
   • Use the same IDs on both stores, made of lowercase letters, digits and underscores. The starter IDs are coins_100, coins_500, coins_1000, premium_monthly and premium_yearly. Pick your own if you like.
   • On Google Play enter the subscription ID (RevenueCat's subscription:base-plan form is understood too).

2. Create a RevenueCat project and add two apps: an iOS app with your bundle ID and an Android app with your package name. RevenueCat asks for an App Store Connect API key (the In-App Purchase key) and a Google Play service account with access to your app. Follow its prompts: they change from time to time.

3. Add the products to RevenueCat. Under Product catalog > Products add the same IDs.

4. Create the entitlement premium and attach the subscriptions to it. Do not attach coin packs. (If you name it something else, set REVENUECAT_ENTITLEMENT.) You do not need offerings: the app fetches the products by ID.

5. Tell the admin panel. Open Settings > Store products and enter the same product IDs, the number of coins each pack gives, each plan's billing period in months, a list price and the currency. Save. The app reads this list from your server, so you can change coin amounts later without a new app release. Until you save it, the starter list in config/monetization.php applies.

   

6. Add the keys to .env. In RevenueCat open Project settings > API keys. There are two kinds of key; do not mix them up:

   dotenvCopy

   REVENUECAT_SECRET_KEY=sk_...            # secret API key. Server only, never in the app
   REVENUECAT_IOS_API_KEY=appl_...         # public SDK key of the iOS app
   REVENUECAT_ANDROID_API_KEY=goog_...     # public SDK key of the Android app
   REVENUECAT_WEBHOOK_AUTH=a-long-random-secret

   Make up REVENUECAT_WEBHOOK_AUTH yourself: any long random string. Then php artisan config:cache. The two public keys reach the app through your server, so changing them needs no app rebuild.

7. Add the webhook. In RevenueCat open Project settings > Integrations > Webhooks and add one:

   • URL: https://your-domain.com/api/webhooks/revenuecat
   • Authorization header value: the same string as REVENUECAT_WEBHOOK_AUTH
   • Environment: both production and sandbox

8. Send the test event from RevenueCat. Your server answers 200 only when the secret matches. A 403 means the value differs. A 503 means REVENUECAT_WEBHOOK_AUTH is empty on the server (or the config cache is stale). You can also check by hand:

   bashCopy

   curl -i -X POST https://your-domain.com/api/webhooks/revenuecat \
     -H "Authorization: wrong-value" -H "Content-Type: application/json" -d '{}'

   That should answer 403 (or 503 if the secret is not set). It must never answer 404: a 404 means this backend version is not installed there.

Without the webhook, purchases still apply when the app syncs, but renewals, expirations and refunds only show up the next time that listener opens the app. The dashboard warns you if the secret is missing.

10.3Testing

• Google Play: add your Google account as a licence tester (Play Console > Settings > License testing) and install the app from an internal testing track.
• App Store: create a Sandbox tester in App Store Connect (Users and Access > Sandbox) and sign in with it on the device when asked to buy.
• Buy one coin pack and one subscription on both platforms. Coins should appear within seconds. Sandbox purchases credit coins and Premium too, but are left out of the dashboard's revenue.
• Test Restore purchases after reinstalling the app.
• App Review buys in the sandbox, which RevenueCat handles for you: no server switch is needed.

10.4Refunds

When RevenueCat reports a coin pack as refunded, its coins are taken back from the listener's balance. The balance never goes below zero, and coins already spent cannot be recovered. The purchase on the listener's page shows how many coins were taken back, and refunded packs are left out of the revenue estimate. Google Play refunds count once they go through RevenueCat (refund or revoke in Play Console or in RevenueCat); a Play refund made some other way may not be reported. A refunded or expired subscription ends Premium through the same webhook.

10.5What "not available" means

Until the purchase setup is complete, the Coins and Premium pages say that packs and Premium are not available. This is what a listener sees:

It appears when the public key for that platform is empty, when the products are missing or not ready in the store or RevenueCat, or when the product IDs in the admin panel do not match. In the same way, the sync request answers 503 while the secret key is missing or RevenueCat cannot be reached, and the app tries again later. See troubleshooting for a checklist.

11Ads with AdMobOptional~15 min

You can run the app with no ads at all: switch Show ads off in Settings > Ads. Premium subscribers never see ads.

1. Create the apps in AdMob. Add an Android app and an iOS app. Each gets an app ID that looks like ca-app-pub-0000000000000000~0000000000 (with a tilde).

2. Put the app IDs in the app.

   • Android: audisode/android/app/src/main/AndroidManifest.xml, the com.google.android.gms.ads.APPLICATION_ID value.
   • iOS: audisode/ios/Runner/Info.plist, the GADApplicationIdentifier value.

3. Create the ad units in AdMob: a banner, a full-screen (interstitial) and a rewarded ad unit for each platform. Their IDs have a slash, ca-app-pub-0000000000000000/0000000000. Put them in audisode/lib/utils/app_config.dart, or pass them when you build:

   Setting in app_config.dart	Build option
   androidBannerAdID	--dart-define=ANDROID_BANNER_AD_ID=…
   androidInterstitialAdID	--dart-define=ANDROID_INTERSTITIAL_AD_ID=…
   androidRewardedAdID	--dart-define=ANDROID_REWARDED_AD_ID=…
   iosBannerAdID	--dart-define=IOS_BANNER_AD_ID=…
   iosInterstitialAdID	--dart-define=IOS_INTERSTITIAL_AD_ID=…
   iosRewardedAdID	--dart-define=IOS_REWARDED_AD_ID=…

4. Create the consent messages. In AdMob open Privacy & messaging and create a GDPR message. For iOS also create an IDFA explainer message if you want personalised ads: it explains the request and then shows Apple's tracking prompt. The app shows the messages automatically where the law requires consent, and offers Ad privacy in the Profile menu there.

5. Turn on server-side verification for rewarded ads. In AdMob open the rewarded ad unit, enable server-side verification, and set the callback URL to:

   textCopy

   https://your-domain.com/api/admob/ssv

   Coins are then credited only when AdMob's signed callback reaches your server. This is the default (ADMOB_SSV_ENABLED=true).

6. Testing with Google's test ads. Test ad units never call your server, so no rewards would be credited. While you test, set ADMOB_SSV_ENABLED=false in .env: the app then claims rewards itself, one per 30 seconds, within the daily limit. Set it back to true before you release.

7. Tune the frequency in Settings > Ads: the master switch, banner and full-screen ads, how often full-screen ads appear, and how many rewarded ads one listener can watch per day.

12Push notificationsOptional~15 min

The backend sends three kinds of notification through Firebase Cloud Messaging:

• New episode. To listeners who follow the author, have listened to the book or saved it. One alert per bulk upload.
• Daily check-in reminder. To listeners whose streak is about to reset, at the hour you choose.
• Announcements you write on the Notifications page.

1. Create a service account key. In Google Cloud, choose the project that is your Firebase project. Open IAM & Admin > Service accounts, create a service account with the role Firebase Cloud Messaging API Admin, and create a JSON key for it. Download the file.

2. Store the key outside the web root, for example in /home/you/keys/, and tell the backend where it is:

   dotenvCopy

   FIREBASE_SERVICE_ACCOUNT_JSON=/home/you/keys/firebase-service-account.json

   FCM_PROJECT_ID defaults to FIREBASE_PROJECT_ID. Run php artisan config:cache.

3. iOS only: upload an APNs key to Firebase. In Apple Developer open Keys, create a key with Apple Push Notifications service (APNs) turned on, and download the .p8 file (you can download it only once). In the Firebase console open Project settings > Cloud Messaging, find your iOS app, and upload the key with your Key ID and Team ID. In Xcode, check that Push Notifications is listed under Signing & Capabilities.

4. Switch on the automatic notifications in Settings > Notifications (new-episode alerts and check-in reminders) and choose the reminder hour.

5. Send a test. Open Notifications in the admin panel, write a title and message, send it to everyone, and watch your phone. The orange dot beside Notifications in the menu and the matching item on the dashboard go away once the key is set.

Listeners choose which kinds they want in the app, and the app asks for permission the first time. The scheduler must be running (cron), because the reminder is sent by it.

13Shared book links~20 min

The share button on a book shares https://your-domain.com/book/12. What happens next depends on the device:

1. Put your domain in the app, in two files. Replace your-domain.com with the domain of your backend (the one in BASE_URL, without https://):

   • audisode/android/app/src/main/AndroidManifest.xml: the android:host in the intent filter with pathPrefix="/book/".
   • audisode/ios/Runner/Runner.entitlements: the applinks: entry under com.apple.developer.associated-domains.

   The domain is written into the app, so a backend that moves to a new domain needs a new app release for links to open the app.

2. Fill in Settings > App links in the admin panel:

   • Store pages: the Google Play and App Store links. Leave a store empty until its listing is public; its button is hidden and phones are not sent there.
   • Android package name: your application ID.
   • Android signing fingerprints: SHA-256 fingerprints, one per line. Add the app signing key from Play Console (Test and release > App integrity > App signing) and, for copies installed outside Google Play, the key they were signed with (keytool -list -v -keystore your.jks). These are SHA-256, not the SHA-1 used for Firebase.
   • Apple Team ID: 10 characters, from developer.apple.com > Account > Membership details.
   • iOS bundle ID: your bundle ID.

   

3. Check both verification files. From these settings the backend serves the two files phones read. Each must answer 200 with JSON over HTTPS, at the root of the domain in APP_URL, with no redirect:

   bashCopy

   curl -i https://your-domain.com/.well-known/assetlinks.json
   curl -i https://your-domain.com/.well-known/apple-app-site-association

   A 404 means a setting is missing. An HTML page from your host instead of JSON means the web server answered before Laravel: let it pass /.well-known/ through to public/index.php.

4. Test on a device. Without sharing anything:

   bashCopy

   adb shell am start -a android.intent.action.VIEW -d "https://your-domain.com/book/12" com.yourcompany.yourapp
   xcrun simctl openurl booted "https://your-domain.com/book/12"

14Audio storage in the cloudOptional

By default your audio stays on your server. If your hosting has little disk space or bandwidth, keep it in a bucket instead. Listeners still get the same protected, expiring links.

1. Create a private bucket and an access key with read and write access to it. The bucket must not be public.

2. Set the keys in .env. For Cloudflare R2:

   dotenvCopy

   MEDIA_DISK=media_cloud
   MEDIA_S3_KEY=your-access-key
   MEDIA_S3_SECRET=your-secret-key
   MEDIA_S3_REGION=auto
   MEDIA_S3_BUCKET=audisode-audio
   MEDIA_S3_ENDPOINT=https://ACCOUNT_ID.r2.cloudflarestorage.com
   MEDIA_S3_PATH_STYLE=false

   For Amazon S3, use your region (for example us-east-1) and leave MEDIA_S3_ENDPOINT empty. Keep MEDIA_URL_TTL_MINUTES at 10080 or less: cloud links cannot last longer than 7 days. Run php artisan config:cache.

3. Move the audio you already have. New uploads go straight to the bucket. Copy the existing files across, first as a rehearsal and then for real:

   bashCopy

   php artisan media:push-to-cloud --dry-run
   php artisan media:push-to-cloud --delete-local

   --delete-local removes each local file once it is safely in the bucket. Files not yet copied keep streaming from your server, so the switch needs no downtime.

15Make the app yoursApp

Everything that identifies the app is in a few files. Open the audisode folder in your editor. All paths below are inside it.

15.11. The backend address

In lib/utils/app_config.dart, set baseUrl to your backend, with https:// and a trailing slash:

defaultValue: 'https://your-domain.com/',

You can also pass it when you run or build, without editing the file: --dart-define=BASE_URL=https://your-domain.com/. Release builds only allow https; plain http works in debug builds only.

15.22. The package name and bundle ID

Choose a unique ID in reverse-domain style, such as com.yourcompany.yourapp. You can never change it after you publish. Install the packages, then run:

cd audisode
flutter pub get
dart run change_app_package_name:main com.yourcompany.yourapp

It changes the Android applicationId and namespace in android/app/build.gradle, the Android manifests, and the iOS bundle identifier. Open build.gradle and check that both show your ID.

15.33. The app name

The name appears in more than one place. Change them all:

After editing the .arb files, regenerate the text:

flutter gen-l10n

15.44. Icons and launch screen

One image makes both. Replace assets/icons/logo.png with your logo and run two commands.

dart run flutter_launcher_icons
dart run flutter_native_splash:create

The first writes the Android and iOS icons (the iOS one without transparency, which the App Store refuses). The second writes the launch screens, light and dark. They read the settings at the end of pubspec.yaml. The colours there (#FDFCF9 for light and #1A1512 for dark) are the app's paper colours: change them if you change the palette. These commands rewrite files under android/ and ios/, so run them before you commit. The other pictures in assets/icons (Google, Apple, email, app bar) are shown inside the app.

15.55. Colours

All colours are in lib/utils/app_colors.dart, as two palettes: AppPalette.light and AppPalette.dark. Each colour is named for the job it does, not for how it looks:

Change the colour values (Color(0xFF8C2F24) and so on) and keep the names. Check that text stays readable on its background in both palettes.

15.66. Onboarding images

The three welcome screens use assets/onboard/intro1.jpeg, intro2.jpeg and intro3.jpeg, each 1024 × 1024 pixels. Replace them with your own pictures of the same size and keep the file names. Their titles and texts are in the .arb files (onboardingTitle1, onboardingBody1 and so on).

15.77. The notification channel ID

In lib/utils/app_config.dart, change audioNotificationChannelId so it starts with your new package name, for example com.yourcompany.yourapp.channel.audio. It names the Android notification used for the lock-screen player controls.

15.88. Terms and privacy links

The Premium page links to your terms and your privacy policy, which both stores require for subscriptions.

• Privacy policy: comes from your backend, https://your-domain.com/page/privacy_policy. Write it in Settings > Legal pages.
• Terms of use: by default Apple's standard licence agreement. To use your own, pass --dart-define=TERMS_URL=https://your-domain.com/terms when you build, or change termsUrl in app_config.dart.

15.99. Languages

The app's own text follows the phone's language. It ships in English, Bengali, Arabic (right to left) and Spanish. Have a native speaker review the translations in lib/l10n before you release: they were not written by professional translators.

• Add a language: copy lib/l10n/app_en.arb to app_<code>.arb (for example app_fr.arb), translate the values, run flutter gen-l10n, and add the code to CFBundleLocalizations in ios/Runner/Info.plist.
• Remove a language: delete its .arb file, run flutter gen-l10n, and remove its code from CFBundleLocalizations.

The language of the audiobooks is separate: it is chosen in the app under Audiobook language and managed under Languages in the admin panel.

15.1010. Run it

flutter pub get
flutter run --dart-define=BASE_URL=https://your-domain.com/

Start the app on a phone or emulator that can reach your backend. If your backend runs on your own computer, use http://10.0.2.2:8000/ from the Android emulator or http://127.0.0.1:8000/ from the iOS simulator (plain http works in debug builds only).

16Build and publishApp

16.1Android

1. Create your own upload keystore. Keep it somewhere safe and back it up: if you lose it you cannot update your app the normal way. Never share it or put it in a repository.

   bashCopy

   keytool -genkey -v -keystore ~/upload.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

2. Create android/key.properties with these four lines (your own passwords and the full path to the keystore):

   propertiesCopy

   storePassword=your-store-password
   keyPassword=your-key-password
   keyAlias=upload
   storeFile=/full/path/to/upload.jks

3. Set the version in pubspec.yaml. version: 1.0.1+4 means version name 1.0.1 and build number 4, on both platforms. The number after the plus sign must go up with every upload to a store.

4. Build the bundle (it ends up in build/app/outputs/bundle/release/) and upload it in Play Console:

   bashCopy

   flutter build appbundle --dart-define=BASE_URL=https://your-domain.com/

   Add any ad-unit IDs or TERMS_URL as further --dart-define options, or set them in app_config.dart.

5. After the first upload, go back to two places. Google signs your app with its own key. Copy it from Play Console > Test and release > App integrity > App signing, and add:

   • its SHA-1 to the Android app in Firebase (section 9), or Google sign-in fails for store installs;
   • its SHA-256 to Settings > App links in the admin panel (section 13), or shared links open the browser.

16.2iOS

1. Open the workspace in Xcode: ios/Runner.xcworkspace (not the .xcodeproj). If you have changed packages, run cd ios && pod install first.

2. Choose your team. Under Runner > Signing & Capabilities pick your Team and leave Automatically manage signing on.

3. Check the capabilities. The list must show Push Notifications, Sign in with Apple and Associated Domains. Automatic signing adds them from Runner.entitlements. The Associated Domains entry must show applinks:your-domain.com (section 13).

4. Check the minimum version. The app supports iOS 15 and newer.

5. Build the archive (the result is in build/ios/ipa/):

   bashCopy

   flutter build ipa --dart-define=BASE_URL=https://your-domain.com/

6. Upload it with Xcode's Organizer (Window > Organizer > Distribute App) or the Transporter app. Then finish the listing in App Store Connect.

Troubleshooting: iOS simulator build under Xcode 27

With Xcode 27, flutter build ios --simulator can stop with a "does not contain architectures" error in debug_unpack_ios (a failing lipo -verify_arch check). We have seen it only with simulator builds. Work around it by letting Flutter write the settings and building with xcodebuild for one architecture:

flutter build ios --simulator --debug --config-only --dart-define=BASE_URL=http://127.0.0.1:8000/
xcodebuild -workspace ios/Runner.xcworkspace -scheme Runner -configuration Debug \
  -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
  ONLY_ACTIVE_ARCH=YES ARCHS=arm64 build

16.3Before you submit to the stores

Tick these off as you go. Your ticks are kept in this browser only.

• Privacy policy is written (Settings > Legal pages) and its address, https://your-domain.com/page/privacy_policy, is entered in both store listings.
• Google Play "Data safety" form and App Store "App privacy" answers match what the app collects: email address, name, user ID, purchases, listening activity, push token, and (with ads on) the advertising ID. ios/Runner/PrivacyInfo.xcprivacy lists these for Apple: check it against your real setup and change it if you add services or turn ads off.
• Account deletion. Listeners can delete their account inside the app: Profile, the pencil icon, then Delete account. Google Play also asks for a web page where people can request deletion: your Contact page (/page/contact_us) can explain how.
• Sign in with Apple works on a real iPhone, and deleting that account removes your app from Settings > your name > Sign-In & Security > Sign in with Apple. The Apple key is in the Firebase console (section 9.1). Apple rejects an app with Google sign-in that lacks either.
• Tracking prompt. If you show personalised ads on iOS, create the IDFA explainer message in AdMob (section 11). The wording of Apple's prompt is NSUserTrackingUsageDescription in Info.plist.
• Subscription terms and links. The Premium page shows the renewal terms, a Terms of use link and a Privacy Policy link, and a Restore purchases button. Check that the terms link goes where you want (section 15.8).
• Purchases work in the sandbox on both platforms: one coin pack and one subscription each (section 10).
• Real ad IDs are in place and ADMOB_SSV_ENABLED is true (section 11), or ads are switched off.
• Content rights. You have the rights to all audio, covers, pictures and text. The sample books are deleted.
• AI narration is labelled as AI-generated where the stores or the law require it.
• A demo account for App Review. Reviewers cannot use your Google account, but they can use their own Apple Account for Sign in with Apple. Sign up in the app with an email and password, add some coins to that listener in the admin panel (Listeners > Adjust coins), and put the email and password in the review notes of both stores. In the App Store notes also say where Sign in with Apple and Delete account are.
• Store listing assets are ready: icon, screenshots, description, age rating, contact details.

17Running the serviceServer

17.1Before you go live

• APP_ENV=production and APP_DEBUG=false; APP_URL is your https address.
• https://your-domain.com/.env answers 404 or 403, and the document root is public/.
• The cron entry exists and runs every minute (php artisan schedule:list shows the jobs).
• Mail works: a password-reset email really arrives (troubleshooting).
• Firebase works: you can sign in with Google (and Apple on iOS) on a real build, including a build installed from the store.
• RevenueCat: all five keys are set, the webhook test answers 200, and a purchase on each platform credits coins.
• Push notifications reach a real phone, on both platforms.
• Real AdMob IDs in the app, SSV callback set, ADMOB_SSV_ENABLED=true (or ads off).
• Both /.well-known/ files answer 200 and a shared link opens the app on a store install.
• Settings > Branding, Legal pages and App links are filled in; the home screen is arranged.
• The sample books are deleted. The dashboard's Needs attention list has nothing you do not understand.
• Backups are set up and you have restored one at least once (below).
• The licence shows Active under License in the admin panel.

17.2Backups

Back up these regularly, and keep copies somewhere other than the server:

• The database. For example, daily from cron:
  bashCopy

  mysqldump -u audisode_user -p audisode | gzip > audisode-$(date +%F).sql.gz

• Uploaded audio: the folder audisode_backend/storage/app/private/media (not needed if your audio is in a bucket, but keep that bucket safe).
• .env and your keys: the Firebase service account file, your Android keystore and key.properties, and the Apple key files. Losing the keystore means you cannot update your Android app the normal way.
• Uploaded branding and covers: audisode_backend/public/uploads.

17.3Updating the backend

When you receive a new version:

1. Back up the database and the audio folder.

2. Upload the new files over the old ones. Keep your .env and the storage/ folder (and public/uploads).

3. Install the packages. With a package that includes vendor/, upload it too. With SSH:

   bashCopy

   composer install --no-dev --optimize-autoloader

4. Update the database.

   bashCopy

   php artisan migrate --force

5. Refresh the caches. If something looks stale, run php artisan optimize:clear first.

   bashCopy

   php artisan config:cache
   php artisan queue:restart

   (queue:restart matters only if you run the worker under Supervisor.)

6. Check the cron entry still exists. Running php artisan app:install again is safe, skips the admin account when one exists, and ends with the configuration checklist, so any new TODO line shows what the release needs.

7. Check the deployment. POST /api/webhooks/revenuecat without the secret must answer 503 or 403, never 404. A 404 means the old code is still live.

17.4Logs and the scheduler

• Errors are written to storage/logs/laravel.log. Keep APP_DEBUG=false on a live server.
• To see that the scheduler knows its jobs, run php artisan schedule:list. To run it once by hand, run php artisan schedule:run.
• If AI narrations or announcements stay waiting for more than a few minutes, the cron entry is not running: see troubleshooting.
• The licence is checked once a day by the scheduler. A server that cannot reach the licence server keeps running.

17.5Hosting a public demo

To show the admin panel to buyers, host it with a read-only demo admin: someone who signs in with it can browse everything, but every change is refused and a "Demo mode" alert says so. It is the same code as the real panel, and the demo login exists only where you create it.

1. Deploy the code to its own server with its own database, and run php artisan app:install --sample-books there. The demo server needs its own licence for its own domain.

2. Set DEMO_ADMIN_EMAIL in .env. Use an address that is not a real mailbox, so the public "forgot password" page cannot reach anyone. Set DEMO_ADMIN_PASSWORD too.

3. Create the demo admin:

   bashCopy

   php artisan db:seed --class=DemoAdminSeeder

4. Publish that login and password on your listing. Keep your own owner account off the demo server. Listener emails are masked in the demo.

5. If people can use the mobile app against the demo server, reset its data now and then, for example nightly: only the admin panel is read-only, so listeners can create accounts, spend coins and write reviews. A reset is php artisan migrate:fresh --force followed by the install and seeder steps above. Run it from cron at night.

17.6Security checklist

• APP_DEBUG=false and APP_ENV=production.
• HTTPS everywhere, and the document root set to public/.
• https://your-domain.com/.env answers 404 or 403.
• Strong, unique admin passwords. Add people on the Team page rather than sharing one login. Remove people who leave.
• Keep the Firebase service account key, .env and your keystore out of any public folder, repository and email.
• Hide your PHP version: set expose_php = Off in php.ini (in cPanel, MultiPHP INI Editor). PHP otherwise sends an X-Powered-By: PHP/x.y header. The panel itself already sends X-Frame-Options, X-Content-Type-Options, Referrer-Policy and Permissions-Policy headers.
• If .env was ever exposed or committed, change every key in it, rotate the app key with php artisan key:generate --force (this signs admins out), and sign every listener out by emptying the token table:
  bashCopy

  php artisan tinker --execute="DB::table('personal_access_tokens')->delete();"

• Keep the backend updated, and keep your server's PHP and operating system updated.

18API referenceFor developers

You do not need this to run the product. It is a compact map of the backend's API for developers. The README in audisode_backend/README.md has more detail.

• All endpoints live under /api and return JSON.
• Signed-in endpoints expect the header Authorization: Bearer <token>. The token comes from /login, /register or /social-login and lasts a year by default.
• Errors always have one shape: {"status": false, "code": "...", "message": "...", "errors": {...}}. errors appears for validation failures.
• Sign-in endpoints are rate limited. Purchases and unlocks answer 503 with not_configured while a needed service is not set up.

18.1The home screen layout

GET /api/home returns a layout: the sections the app should draw, top to bottom, exactly as set on the admin panel's Home screen page. Each entry has a type and an optional title (your own heading). A collection entry also carries its description and books. The other keys in the response (featured, recent, top_rated, most_played, free, series, trending, new_episodes, reviews, spotlight, authors) hold the data for those sections. A section you hid is left out of layout and its data comes back empty.

Some sections are personal: the app fills them in from the listener's own activity (the premium and check-in strips, continue listening, recommendations, "your week"). The server only decides whether they appear and where. The app ignores a section type it does not know, so a newer backend can add sections without breaking older app releases. To add a built-in section, see "Home screen" in the backend README.

19Troubleshooting

Find the symptom, open it, and work down the list. Most problems are one wrong value in one place. Always check storage/logs/laravel.log on the server first: it usually names the problem.

19.1Server and admin panel

19.2App, sign-in and Firebase

19.3Purchases and Premium

19.4Links and notifications

19.5Building

20FAQ

21Changelog, licence and support

21.1Changelog

Versions follow MAJOR.MINOR.PATCH. The version of the whole product, backend and app together, is in audisode_backend/config/app.php and shows in the admin panel's user menu and in php artisan app:install. Quote it when you ask for support. The app also carries its own number in audisode/pubspec.yaml (version: 1.0.1+4 is version name 1.0.1, build number 4). The stores need that number to go up with every upload, so it does not match the product version. The full text is in CHANGELOG.md.

1.0.0: first marketplace release

Mobile app (Android and iOS)

• Audiobooks as single files or series of episodes, with covers, authors, categories, languages, collections and a home screen laid out from the admin panel
• Playback with background audio, lock-screen controls, speed control, sleep timer, bookmarks and "continue listening" that follows the listener across devices
• Offline downloads that pause, resume and survive a closed app
• Coins: a welcome gift, a 7-day check-in streak with reminders, rewarded ads and invite-a-friend rewards; paid titles unlock with coins
• Premium subscription that unlocks everything and removes ads
• In-app purchases through RevenueCat (coin packs and subscriptions), with restore
• Sign in with Google and Sign in with Apple through Firebase; guests can browse and play free titles
• Reviews and ratings, push notifications, shared book links that open the app
• AdMob ads with Google's consent form and an "Ad privacy" menu entry
• Account deletion inside the app
• Four languages: English, Bengali, Arabic (right to left) and Spanish
• Light and dark themes
• App icon and launch screen from one image
• iOS privacy manifest and Google's SKAdNetwork list
• Up-to-date dependencies, including google_sign_in 7 (see the app README for the two packages held back)

Backend and admin panel (Laravel)

• REST API with token sign-in, rate limits and one error format
• Server-side wallet and unlocks: the app cannot grant itself coins or titles
• Audio kept outside the web root and handed out as short-lived signed links, or from S3-compatible cloud storage
• Purchases verified against RevenueCat, with webhooks for renewals, expirations and refunds
• Admin panel: dashboard with analytics, books, episodes, bulk upload, authors, categories, languages, home screen layout, collections, listeners, reviews, push notifications, AI narration (OpenAI or ElevenLabs), settings and legal pages
• Public website with store badges and legal pages
• Read-only demo admin for public demos
• Web installer at /install for hosting without SSH
• Licence activation for one domain, a daily check that never takes the site down when the licence server is unreachable, and the License page
• Settings > Branding: name, accent colour, logo and favicon
• Team: add admins by email invite, remove them; the last admin stays
• php artisan app:install --sample-books: seven public-domain English audiobooks
• Panel libraries and fonts served from public/vendor/: no CDN, no Google Fonts
• Sign-in tokens expire after a year; expired ones are pruned daily
• php artisan app:install with a configuration checklist
• Light and dark admin themes, a command palette (Ctrl or ⌘ + K) and security headers

21.2Licence and support

Each copy of the product is licensed for one domain, activated with the key and username from your purchase (License page). The licence terms and the support terms are set by the seller of the product and are filled in below.

21.3Credits and third-party notices

Audisode uses open-source software and fonts, each under its own licence. The full list is in THIRD_PARTY_NOTICES.md at the top of the package. In short:

• Admin panel and website: Bootstrap (MIT), Bootstrap Icons (MIT), Chart.js (MIT), Tom Select (Apache-2.0) and Quill (BSD-3-Clause), all served from audisode_backend/public/vendor/.
• Fonts: Fraunces and Literata in the app, Geist, Geist Mono and Instrument Serif in the admin panel, all under the SIL Open Font License 1.1.
• Sample content: the seven public-domain books and their LibriVox recordings, streamed from archive.org. Delete them before you launch.
• Packages: the PHP packages are listed in audisode_backend/composer.lock and the Dart and Flutter packages in audisode/pubspec.lock.
• Artwork: replace the placeholder images, icons and onboarding pictures with your own before you publish, and make sure you have the right to use every image, sound and font you ship.