BEST STORE v1.2.0 - COMPLETE SETUP GUIDE

WHAT IS INCLUDED
Best-Store-v1.2.0.apk: signed app for Android and Android TV.
Best-Store-Panel.zip: PHP panel for your hosting.
Best-Store-Source.zip: Android source and branding files.
Best-Store-Logo.png: square logo.
START-HERE.txt: quick setup.
FORUM-POST.txt: forum title and description.
VALIDATION.txt: actual checks and testing limits.

HOSTING REQUIREMENTS
A host with PHP 7.4 or newer; PHP 8.x is recommended.
HTTPS hosting is recommended. The app also accepts HTTP URLs.
No MySQL database, database username, database password, Composer or Node setup.
The catalog is stored in data/apps.json.

A. INSTALL THE PANEL ON CPANEL
1. Open cPanel > File Manager > public_html.
2. Create a folder named beststore, or choose another folder name.
3. Open that folder and upload Best-Store-Panel.zip.
4. Select the ZIP and click Extract. Extract directly into that folder.
5. Check that index.php, api.php, lib.php, config.php, logo.png and data are directly inside the folder.
6. Open https://yourdomain.com/beststore/ in a browser.
7. Log in using beststore123.
8. In File Manager, edit config.php and change this line to your own password:
   define('ADMIN_PASSWORD', 'beststore123');
   Keep the quotes and semicolon intact.

For hosting without cPanel, upload/extract the same panel files into your web folder using your host's file manager or FTP. The public URL should point to that folder.

B. ADD YOUR APPS
1. Use the Add a new app form.
2. Enter the app name, category, version and description.
3. Enter an optional full icon URL, such as https://yourdomain.com/icons/player.png.
4. Enter the direct APK URL, such as https://yourdomain.com/apks/player.apk.
5. Click Save app.
6. Use Edit or Delete in the catalog to change entries later.

The panel accepts links; it does not upload APKs or icons.
To host files yourself, use File Manager to create public_html/apks and public_html/icons, then upload the files there. Their URLs will usually be https://yourdomain.com/apks/filename.apk and https://yourdomain.com/icons/filename.png.
The APK link must return the APK file, not a web page, login page or download landing page.
The included catalog starts empty. You supply your own apps and links.

C. CONNECT THE APP WITHOUT EDITING IT
1. Install Best-Store-v1.2.0.apk on your Android device.
2. On a phone, press and hold the Best Store logo.
   On a TV, focus the logo with the remote and hold OK.
3. The Panel URL dialog opens.
4. Enter your full panel folder URL and save:
   https://yourdomain.com/beststore/
5. Press Refresh to load the catalog.

Keep the trailing slash. Do not append index.php or api.php.
Folder names can be case-sensitive: /BestStore/ and /beststore/ may be different.
The app automatically requests api.php from the folder you enter.
Each device saves its own chosen panel URL. Changing one device does not change other devices.
The included APK has a preset URL, so change it to your own panel before using your own catalog.

IMPORTANT URL DIFFERENCE
Panel URL: where the PHP panel lives, for example https://yourdomain.com/beststore/.
Direct APK URL: the download link for one app, for example https://yourdomain.com/apks/player.apk.
Enter the Panel URL in Best Store. Enter individual APK URLs in the panel's app entries.

D. OPTIONAL: DISTRIBUTE AN APK ALREADY CONNECTED TO YOUR PANEL
Normal setup does not require APK editing. This option is for owners who want customers to receive a preconfigured APK.

Inside the APK:
assets/panel-url.txt

In the supplied source ZIP:
android/app/src/main/assets/panel-url.txt

Replace the one-line URL with your own panel folder URL.
If editing an APK, rebuild it using a proper APK editor and re-sign it afterward. Merely zipping extracted files is not enough.
If building the source, follow the Android build instructions included in Best-Store-Source.zip.
Keep your own signing key for all future updates. A different key prevents the modified APK from updating the original installed copy; uninstall that copy first if you receive an installation conflict.
Never put a private signing key into a forum package.
An already saved Panel URL on a device overrides the default in panel-url.txt. Change the saved setting too when testing your preconfigured APK.

E. DOWNLOADING AND INSTALLING APPS
Select an app to view its details, then Download & install.
A progress strip shows the download and provides Cancel.
Android uses its standard installer; Best Store does not install apps silently.
If Android requests permission to install unknown apps, allow Best Store, return and select Install again.
After returning from the installer, Delete APK removes the downloaded file to save space.
Installing Best Store and installing other apps through Best Store are separate steps.

F. TROUBLESHOOTING
Panel shows 404:
Check the folder path, letter case and nesting. index.php must be in the folder matching your public URL.

Panel shows an error or a blank page:
Check the host's PHP version and PHP error log. Confirm all panel files were extracted.

Cannot save an app:
PHP must be able to write to data/. Use your host's normal owner permissions, usually 0755 folders and 0644 files. Ask the host to correct PHP ownership if necessary; do not use 0777.

App shows Store unavailable:
Open https://yourdomain.com/beststore/api.php in a browser. It should return JSON containing store and apps. Verify the saved Panel URL, internet connection and hosting certificate, then Refresh.

App shows No apps yet:
Add an app in the panel. Verify that api.php contains that app, then Refresh. Check that the app is connected to your intended panel.

No matching apps:
Clear the search or choose All apps. Reset filters also clears these filters.

Download fails:
Open the direct APK URL and confirm it downloads an APK file without a login or landing page. Check free device storage.

Android says App not installed:
A differently signed existing copy can cause a conflict. Uninstall that copy before installing your newly signed APK. Also check Android version, supported device architecture, the file's completeness and available storage.

G. BACKUPS AND FUTURE UPDATES
Back up config.php and data/apps.json before changing panel files.
For an existing panel, do not overwrite your saved catalog with the blank apps.json from a fresh-install package.
This 1.2.0 app release needs no update to an already working panel.
For future APK updates, preserve the package ID and signing key and increase versionCode.

H. TESTING STATUS
The APK builds and passes signature checks. Core installation, provider and URL-handling code passed source regression checks against the preceding release.
No physical-device or Android emulator testing was performed for the 1.2.0 layout. Test on your own phones/TVs before wider distribution.
