Installing your app from your website

Overview

Alternative distribution apps approved for download from your website install when people navigate to a special URL scheme; see Distributing your app from your website.

When someone taps a button mapped to the URL, the system makes several requests of your web server to facilitate the installation. Each of the following services that you implement on your web server contain at least two endpoints:

• Authentication server

• Licensing server

• App-data server

MarketplaceKit supports authentication through the the OAuth 2.0 specification IETF RFC 6749. If your website requires someone to be signed-in before they can download an app, or to have made a purchase, include an authentication token in the MarketplaceKitURIScheme URL to begin the authorization process.

After your server authorizes the device, the system requests a license for the app. Your server uses App License Delivery SDK in conjunction with the encryption and signing assets that Apple provides to implement digital rights management by issuing a dynamic license for each installation of an app.

After the device receives a license, the system requests the app data from your web server’s restore endpoint to install the app.

[Image]

Authenticate the page visitor

To restrict download access to a specific set of people, include a token in the MarketplaceKitURIScheme request. If you include the optional token parameter in the URL, MarketplaceKit passes the value to your athentication server to begin authorization. The system looks for details about your authentication server at the following URL:

<fully-qualified-domain>/.well-known/oauth-authorization-server

At this URL, host a JSON file with the following configuration:

{
    "authorization_endpoint": 
        "<fully-qualified-domain>/oauth/authorize",
    "code_challenge_methods_supported": [
        "5256"
    ],
    "grant_types_supported": [
        "authorization_code"
    ],
    "issuer": "<fully-qualified-domain>",
    "response_types_supported": [
        "code",
        "token"
    ],
    "token_endpoint": "<fully-qualified-domain>/oauth/token"
}

The system sends the token from your download URL in a POST to your token_endpoint in the format of described in RFC 8693 section 2.3, for example:

POST /oauth/token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&issued_token_type=urn:ietf:params:oauth:token-type:access_token
&subject_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&client_id=6ef01a168f14431d98a0626cf5c89104

The fields in the POST body are:

Your token endpoint responds to the request with an access token and, optionally, a refresh token. Here’s an example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token": "2YotnFZFEjr1zCsicMWpAA",
   "refresh_token": "82u9fehjiofasbkr3290",
   "token_type": "bearer",
   "expires_in": 3600
}

When the system makes subsequent calls to your web server for app licenses, app installs (restores), or app updates, it includes the bearer token in the header for your server to validate the communication and associate with the person’s account.

Retrieve a license for the app from your web server

If your website doesn’t require authentication or the device is already successfully authorized to act on behalf of the page visitor, the system requests an app license from your web server. To process license requests, your web server implements an endpoint that serves generated licenses by using App License Delivery SDK.

Serve a restore request

When your server responds with a license, the system requests to download your app. Your web server needs to provide a JSON file at the following URL:

<fully-qualified-domain>/.well-known/marketplace-kit

Inside the file, define an endpoint to handle restore requests from the device:

"restore": "<fully-qualified-domain>/PATH",

The system calls your restore endpoint with the following example POST:

{ 
    "apps": [
       { 
          "appleItemId": "<your marketplace's appleItemID>",
          "appleVersionId" : "<version number>"
       }
    ], 
    "platform" : "iOS",
    "osVersion" : "17.4"
}

The request contains the following fields:

Compare the platform and osVersion fields to those contained within the app’s manifest to confirm that your alternative distribution package supports the device attempting to install it.

If downloading your app requires authorization and the system communicates with your endpoint without a valid access token, request reauthentication in your response. An invalid access token can result from token expiration, or the restoration of a device from a backup. For more information, see Reauthenticating a person to manage apps.

Otherwise, send your app in response by supplying a URL in the restores element to the alternative distribution package for the requested app version:

{
    "restores": [
        {
            "appleItemId": "10737747186",
            "appleVersionId": "2000004563",
            "alternativeDistributionPackage": 
                "<fully qualified domain>/PATH",
            "installVerificationToken" : "<required-string>"
            "appShareURL" : <URL>
        }
    ]
}

The "restores" array in the response contains an object with the following fields:

See Also

Web services

• Processing alternative app marketplace notifications
• Ingesting an alternative distribution package
• Installing apps from an alternative marketplace
• Supplying an install verification token