📓Make a Source

Overview

To distribute your apps with AltStore you need to first create a source, which is just a self-hosted JSON file containing basic metadata about your apps. Below is a list of required keys to make a valid source in AltStore along with optional keys you can use to further customize your source.

Instructions

1. Create a new JSON document

2. Input information about your Source using the Source Keys below

3. Host that document at your sourceURL

Example Source

Download this example source as a template to edit with your source's information

6KB

ExampleSource.json

Source Keys

Source

{
  "name": "My Example Source",
  "subtitle": "A source for all of my apps",
  "description": "Welcome to my source! Here you'll find all of my apps.",
  "iconURL": "https://example.com/source_icon.png",
  "headerURL": "https://example.com/source_header.png",
  "website": "https://example.com",
  "patreonURL": "https://patreon.com/mycampaign"
  "tintColor": "#F54F32",
  "featuredApps": [
    "com.example.myapp",
    "com.example.anotherapp"
  ],
  "apps": [],
  "news": [],
}

name (string)

The name of your source as it will appear in AltStore.

subtitle (string)

(optional)

A short, one-sentence description of your source. This will appear underneath the source's name on its About page.

description (string)

(optional)

A full-length description of your source. This can include any information you believe is relevant for your source, such as information about your apps or additional links.

iconURL (string)

(optional)

A link to an image that will be used to visually identify your source. It will appear as a circle.

If not provided, this defaults to the iconURL of the first app listed in your source.

headerURL (string)

(optional)

A link to an image that will be displayed as the header of your source's About page. The image will be blurred by default, but can be viewed by swiping the source's info banner.

We recommended using a 3:2 aspect ratio for best results.

If not provided, this defaults to your source's iconURL.

website (string)

(optional)

A link to the primary website for your source. It will be displayed underneath your source's name on its About page.

patreonURL (string)

(optional)

A link to your Patreon campaign. This will enable you to distribute Patreon-only apps through your Source.

You must add a Patreon object to every app listing you want to designate as Patreon-only. See the Apps section for more information.

tintColor (string)

(optional)

A color that will be used to theme your source's About page. We recommend using a color that works well with your source's icon for consistent theming, but you are free to choose any color you want. Black and white tint colors will be automatically adjusted for legibility.

This must be in hexadecimal format (e.g #F54F32 or C9B632)

If not provided, this defaults to the tintColor of the first app listed in your source.

featuredApps (array of strings)

(optional)

An ordered list of app bundleIdentifier's you want featured on your source's About page. Currently, only the first five will be displayed.

If not provided, this defaults to the first five apps listed in your source.

apps (array of Apps)

An ordered list of the apps in your source.

See Apps section below for more.

news (array of News Item)

A list of the News items in your source. The ordering does not matter because AltStore will display them in reverse chronological order according to their date.

See News Items section below for more.

Apps

"apps": [
    {
        "name": "My Example App",
        "bundleIdentifier": "com.example.myapp",
        "marketplaceID": "12345678",
        "developerName": "Example Developer",
        "subtitle": "An awesome app.",
        "localizedDescription": "This is an awesome app only available on AltStore.",
        "iconURL": "https://example.com/myapp_icon.png",
        "tintColor": "#F54F32",
        "category": "utilities",
        "screenshots": [
            "https://example.com/myapp_screenshot1.png",
            "https://example.com/myapp_screenshot2.png",
            "https://example.com/myapp_screenshot3.png"
        ],
        "versions": [],
        "appPermissions": {},
        "patreon": {},
    },
]

name (string)

The name of your app as it will appear on its store page.

bundleIdentifier (string)

Your app's bundle identifier (CFBundleIdentifier). It is case sensitive and should match exactly what is in your Info.plist.

A source cannot have multiple apps with the same bundle identifier.

marketplaceID (string)

The "Apple ID" of your notarized app. You can find this on your app's App Store Connect page under "App Information."

Not required for non-notarized apps distributed with AltStore (World)

developerName (string)

The name of the developer or developers as it will appear on the store page.

subtitle (string)

(optional)

A short, one-sentence description of your app that will appear in the Browse tab of AltStore.

localizedDescription (string)

A full-length description of your app. This can include any information you believe is relevant for your app, such as feature descriptions or additional links.

iconURL (string)

A link to you app's icon image. It will automatically be masked to an app icon shape.

tintColor (string)

(optional)

The color used to theme your app's store page. We recommend using your app's existing tint color (if it has one), but you are free to choose any color you want.

This must be in hexadecimal format (e.g #F54F32 or C9B632)

category (string)

(optional)

The store category best representing your app.

This must be one of the below values. If no category is provided it will default to other

• developer

• entertainment

• games

• lifestyle

• other

• photo-video

• social

• utilities

screenshots (array of Screenshots)

(optional)

Screenshots of your app. We recommend showcasing your app's main features.

Please see the Screenshots section below for detailed info and instructions.

versions (array of App Versions)

A list of all the published versions of your app.

Please see the App Versions section below for detailed info and instructions

The order of versions matters. AltStore uses the order to determine which version is the "latest" release. For more information, see Updating Apps

appPermissions (App Permissions object)

An object listing all entitlements and privacy permissions information used by the app.

See App Permissions section below for more.

patreon (Patreon object)

(optional)

An object specifying the required pledge/tiers to download the app.

See Patreon section below for more.

Screenshots

Standard

"screenshots": [
    {
        "imageURL": "https://example.com/iphone_portrait_1.png"
    },
    {
        "imageURL": "https://example.com/iphone_portrait_2.png"
    },
    {
        "imageURL": "https://example.com/iphone_landscape.png",
        "width": 2556,
        "height": 1179
    },
]

If a screenshot has an aspect ratio of 9:19.5 (aka a portrait Face ID iPhone), you can optionally list the URL directly instead of a full Screenshot object:

"screenshots": [ 
    "https://example.com/iphone_portrait_1.png",
    "https://example.com/iphone_portrait_2.png",
    {
        "imageURL": "https://example.com/iphone_landscape.png",
        "width": 2556,
        "height": 1179
    }
]

Screenshots with an aspect ratio of 9:19.5 (aka a portrait Face ID iPhone) will have their corners automatically rounded.

Universal Apps

If your app supports both iPhone and iPad and you want to use different screenshots for each device, you can provide multiple arrays nested under the iphone and ipad keys, respectively, using the same format as above.

"screenshots": {
    "iphone": [
        "https://example.com/iphone_portrait_1.png",
        "https://example.com/iphone_portrait_2.png",
        {
            "imageURL": "https://example.com/iphone_landscape.png",
            "width": 2556,
            "height": 1179
        }
    ],
    "ipad": [
        {
            "imageURL": "https://example.com/ipad_portrait.png",
            "width": 1668,
            "height": 2388
        },
        {
            "imageURL": "https://altstore.io/ipad_landscape",
            "width": 2388,
            "height": 1668
        }
    ]
}

imageURL (string)

Link to a screenshot of your app.

width (number)

(optional)

The pixel width of the image. If not provided, AltStore will assume a default size of 393 x 852 points (iPhone 15 in portrait mode).

All iPad screenshots must provide an explicitwidth.

height (number)

(optional)

The pixel height of the image. If not provided, AltStore will assume a default size of 393 x 852 points (iPhone 15 in portrait mode).

All iPad screenshots must provide an explicitheight.

App Versions

"versions": [
  {
    "version": "1.0",
    "buildVersion": "60",
    "date": "2023-03-30",
    "localizedDescription": "First AltStore release!",
    "downloadURL": "https://myapp.com/myapp-1.0.ipa",
    "size": 79821,
    "minOSVersion": "12.0",
    "maxOSVersion": "16.3"
  },
]

For information on how to update your apps once they're published, see Updating Apps.

version (string)

Your app's version number (CFBundleShortVersionString). It is case sensitive and should match exactly what is in your Info.plist.

buildVersion (string)

Your app's build number (CFBundleVersion). It is case sensitive and should match exactly what is in your Info.plist.

marketingVersion (string)

(optional)

The full version displayed to users on your app's store page and throughout the UI. This can be anything you want and does not need to match version or buildVersion.

If not provided, this will default to combining version and buildVersion,e.g. 1.3 (4)

date (string)

The release date for this version.

This should be in ISO 8601 format (e.g. 2023-2-17 or 2023-02-17T12:00:00-06:00)

localizedDescription (string)

(optional)

A description of what's new in this version. You can use this to tell users about new features, bugs fixes, etc.

downloadURL (string)

The URL where your ADP directory is hosted.

For sideloading, this only needs to be the .ipa file

minOSVersion (string)

(optional)

The minimum iOS version supported by this release. AltStore will hide any updates that are not supported by the user's device.

maxOSVersion (string)

(optional)

The maximum iOS version supported by this release (inclusive). AltStore will hide any updates that are not supported by the user's device.

App Permissions

"appPermissions": {
  "entitlements": [
    "com.apple.security.application-groups",
    "com.apple.developer.siri"
  ],
  "privacy": {
    "NSMicrophoneUsageDescription": "App uses the microphone to record audio.",
    "NSCameraUsageDescription": "App uses the camera to take photos."
  }
},

For security purposes, AltStore requires that sources list all entitlements and privacy permissions for every app. These will be checked against the downloaded .ipa, and AltStore will refuse to install any app whose permissions do not match.

entitlements (array of strings)

A list of all entitlements used by the app and its app extensions.

"entitlements": [
    "com.apple.security.application-groups",
    "com.apple.developer.siri"
 ]

These entitlements are required for all applications, so don't need to be listed:

• com.app.developer.team-identifier

• application-identifier

privacy (dictionary of strings)

A dictionary with all the "UsageDescription" keys in your app's Info.plist along with their descriptions. We recommend using the same descriptions already in your Info.plist.

"privacy": {
    "NSMicrophoneUsageDescription": "App uses the microphone to record audio.",
    "NSCameraUsageDescription": "App uses the camera to take photos."
}

News Items

"news": [
  {
    "title": "New Feature Announcement",
    "identifier": "new_feature",
    "caption": "Introducing a new feature in AltStore!",
    "date": "2023-03-15",
    "tintColor": "#F54F32",
    "imageURL": "https://example.com/new_feature_image.png",
    "notify": true,
    "url": "https://example.com/new_feature_details",
    "appID": "com.example.myapp"
  },
]

title (string)

The title of your News item.

identifier (string)

A unique value to distinguish this News item from others in your source.

A source cannot have multiple News items with the same identifier.

caption (string)

A short, one-sentence description of your News item.

date (string)

The publishing date for this News item.

This should be in ISO 8601 format (e.g. 2023-2-17 or 2023-02-17T12:00:00-06:00)

tintColor (string)

(optional)

The background color for your News item.

This must be in hexadecimal format (e.g #F54F32 or F65432)

imageURL (string)

(optional)

A link to the image you want featured with your News item.

This will be scaled to fill a 67:40 aspect ratio.

notify (boolean)

(optional)

When true, AltStore will send a push notification about this News item when it next checks for updates in the background.

url (string)

(optional)

A link that AltStore should open when the News item is tapped. Links will be opened in an in-app web browser.

appID (string)

(optional)

The bundle identifier of an associated app. This will make the app's info banner appear below the News item, which will open the app's Store page when tapped.

Patreon

By adding a Patreon object to your app listing, AltStore can ensure only Patrons can download the app.

For more information on how AltStore's Patreon Integration works, please visit the Patreon Integration page.

"patreon": {
  "pledge": 3,
  "currency": "EUR",
  "benefit": "90zyx87",
  "tiers": [
    "12abc34",
    "56cde78",
  ],  
},

The below requirements are mutually inclusive. This means if any of the conditions you provide are met, a user will be able to download your app.

If you don't provide any of the following keys, AltStore will default to allowing all active Patrons to download the app regardless of tier (excluding followers).

pledge (number)

(optional)

The minimum pledge amount required for download. This can be used to limit downloads to higher tiers.

This amount is assumed to be in USD by default. If using a non-USD currency for your campaign, you must specify it using the currency key below.

This amount will be shown as the app's monthly price if provided. For this reason, we recommend always providing a minimum pledge amount, even if you only have one tier.

currency (string)

(optional*)

The ISO currency code of your campaign's currency.

*This key is required if you provide a pledge amount and your campaign uses a non-USD currency.

benefit (string)

(optional)

The identifier of a campaign benefit. You can add benefits to any of your Patreon campaign tiers, then specify it using this key to allow anyone with that benefit to download your app.

Benefit identifiers are hidden by default, but you can find them by using the Patreon API.

tiers (array of strings)

(optional)

A list of tier identifiers designating which tiers are required to download. A user must be a member of one of these tiers to download your app.

You can find a tier's identifier by selecting a tier and going to its checkout page. The identifier is the numeric value at the end of the URL.

URL	Tier ID
https://www.patreon.com/checkout/shaneriley?rid=	8373919