shizu_store.json
Reference Guide

What is shizu_store.json?

shizu_store.json is a manifest file that tells the Shizu CoreFetch Android app how to beautifully display your application — overriding the default GitHub data with your custom name, description, icon, developer info, and ads.

The Shizu Store automatically discovers and lists Shizuku-based apps. If you don't provide this file, your app will still appear, but it will use your GitHub profile picture as the icon and fetch basic details from your repository description and README. Adding a shizu_store.json unlocks a clean, tailored UI/UX experience for your users.

File Placement

Place shizu_store.json at the root level of your GitHub repository — the same level as your README.md.

# [PASS] Correct — file is at the root
my-shizuku-app/
├── shizu_store.json   ← here
├── README.md
├── app/
│   └── src/...
└── build.gradle

# [FAIL] Wrong — file is in a subdirectory
my-shizuku-app/
├── docs/
│   └── shizu_store.json   ← NOT here
└── ...

The raw URL to your file will be something like:
https://raw.githubusercontent.com/<user>/<repo>/main/shizu_store.json

Required Fields

If you choose to create a shizu_store.json file for custom branding, it must include these four fields at minimum. If any are missing or invalid, the store will ignore the file and fall back to your default GitHub repository data.

Minimal valid example

{
  "app_name": "My Shizuku App",
  "package_name": "xyz.siwane.myapp",
  "short_description": "Does something cool with Shizuku.",
  "icon_url": "https://raw.githubusercontent.com/you/repo/main/icon.png"
}

Extended Fields

These fields enhance how your app appears in the store, including your developer portfolio and community integration.

Developer Portfolio Object

The developer object powers the developer dashboard in the store, showing your banner, website, and other apps.

"developer": {
  "name":        "Jamal El Hizazi",
  "banner_url":  "https://domain.com/coverture.jpg",
  "account_url": "https://github.com/elhizazi1",
  "email":       "[email protected]",
  "website":     "https://siwane.xyz",
  "portfolio":   "https://jamal.elhizazi.me",
  "socials": {
    "facebook":  "https://fb.com/elhizazi2",
    "instagram": "https://instagram.com/elhizazi1",
    "x":         "https://x.com/elhizazi1",
    "youtube":   "https://youtube.com/@si1xyz",
    "github":    "https://github.com/elhizazi1",
    "telegram":  "https://t.me/elhizazi1"
  }
}

Ads & Monetization

Shizu CoreFetch empowers developers by allowing them to display their own custom ads directly inside their app's details page. You keep 100% of the traffic. Set "ad": true and configure the ads array.

"ad": true,
"ads": [
  {
    "position": "top",
    "image_url": "https://yourdomain.com/ad_top.webp",
    "target_url": "https://sponsored-link.com"
  },
  {
    "position": "bottom",
    "image_url": "https://yourdomain.com/ad_bottom.jpeg",
    "target_url": "https://wa.me/123456789"
  }
]

Languages & Locales

The Shizu Store natively supports 9 languages. Add translated strings under the locales key using BCP 47 language codes. The store will display the appropriate locale based on the user's device language, falling back to en if unavailable.

What can be translated?

Each locale object supports these translatable fields:

Store Architecture & Disclaimer

Decentralized Auto-Fetching: The Shizu CoreFetch store acts as an intelligent bridge. It auto-indexes Shizuku applications and fetches metadata and APK releases directly from the developers' GitHub repositories. There is no direct hosting or intervention from the store itself. The ecosystem relies entirely on the open-source community.

Validation

Always validate your shizu_store.json before publishing. Malformed JSON will cause the store to ignore your customizations and display the default GitHub data instead.

Online (recommended)

Command Line with ajv

# Install ajv-cli
npm install -g ajv-cli

# Validate your file
ajv validate -s schema.json -d shizu_store.json

Python

pip install jsonschema

python3 - <<'EOF'
import json, jsonschema

with open("schema.json") as f:
    schema = json.load(f)
with open("shizu_store.json") as f:
    data = json.load(f)

jsonschema.validate(data, schema)
print("[PASS] Valid!")
EOF

Quick JSON syntax check

python3 -m json.tool shizu_store.json > /dev/null && echo "[PASS] Valid JSON"

Common Mistakes

1. Duplicate keys in an object

JSON does not allow duplicate keys inside the same object. Most parsers will silently use the last value, which leads to data loss.

{
  "app_name": "My App",
  "app_name": "My App Again"  ← duplicate key!
}

2. Trailing commas

JSON does not allow a comma after the last item in an object or array.

{
  "app_name": "My App",
  "package_name": "xyz.siwane.app",  ← trailing comma
}

{
  "app_name": "My App",
  "package_name": "xyz.siwane.app"
}

3. Relative URLs

All URL fields (icon_url, banner_url, screenshots, etc.) must be absolute HTTPS URLs. Relative paths won't work because the store fetches them remotely.

"icon_url": "./assets/icon.png"

"icon_url": "https://raw.githubusercontent.com/you/repo/main/assets/icon.png"

4. Wrong file name or location

To apply your custom branding, the file must be named exactly shizu_store.json (lowercase, with underscore) and placed at the root of the repository.

Security Notice

As a developer whose app is listed on the Shizu Store, you agree to act responsibly. This means:

• Never serve malware or spyware through your GitHub releases.
• Be transparent about what your app does. Accurately describe all Shizuku permissions your app uses.
• Publish your source code when possible. Users and reviewers are far more likely to trust open-source apps.
• Sign your APKs with a consistent certificate. Never swap a legitimate APK for a malicious one.
• Notify users of significant changes via GitHub releases, especially if you are requesting new permissions.

FAQ