Downloadable Fonts

Android 8.0 (API level 26) and Android Support Library 26 introduce support for APIs to request fonts from a provider application instead of bundling files into the APK or letting the APK download fonts. The feature is available on devices running Android API versions 14 and higher through the Support Library 26.

The Downloadable Fonts feature offers the following benefits:

• Reduces the APK size
• Increases the app installation success rate
• Improves the overall system health as multiple APKs can share the same font through a provider. This saves users cellular data, phone memory, and disk space. In this model, the font is fetched over the network when needed.

Refer to the following related resources:

• Downloadable Fonts sample app Java | Kotlin

How does Downloadable Fonts work?

A font provider is an application that retrieves fonts and caches them locally so other apps can request and share fonts. Figure 1 illustrates the process.

Figure 1. Downloadable Fonts process

The basics

You can use the Downloadable Fonts feature in the following ways:

• via Android Studio and Google Play Services
• Programmatically
• Via the support library

Using Downloadable Fonts via Android Studio and Google Play services

You can set your application to download fonts by using Android Studio 3.0 or higher. To help you get started with the Downloadable Fonts features, you can use the font provider from Google Play services.

Note: A device must have Google Play services version 11 or higher to use the Google Fonts provider.

1. In the Layout Editor, select a TextView, and then under Properties, select fontFamily > More Fonts.

   

   Figure 2. Using Layout editor

   The Resources window appears.

2. In the Source drop-down list, select Google Fonts.
3. In the Fonts box, select a font.
4. Select Create downloadable font and click OK.

   Note: To bundle the font in your app, select Add font to project.

   

   Figure 3. Selecting font from the Resources window

Android Studio automatically generates the relevant XML files that are needed to render the font correctly in your app.



Figure 4. Previewing font file

Using Downloadable Fonts programmatically

Prior to Android 8.0 (API level 26), the Support Library 26.0 provides full support for Downloadable Fonts. For more information about using the support library, go to the Downloadable Fonts support library section.

To use the Downloadable Fonts feature programmatically, you need to interact with two key classes:

• android.graphics.fonts.FontRequest: This class lets you create a font request.
• FontsContract: This class lets you create a new Typeface object based on the font request.

Your app retrieves fonts from the font provider by using the FontsContract API. Each provider has its own set of restrictions on the Android versions and query language it supports. For more information on the Android versions and query format, refer to your provider’s documentation.

To download a font, perform the following steps:

1. Create an instance of the android.graphics.fonts.FontRequest class to request the font from the provider. To create a request, pass the following parameters:
   • The font provider authority
   • The font provider package to verify the identity of the provider
   • The string query of the font. For more information about query formats, see your font provider's documentation, such as Google Fonts.
   • A list of sets of hashes for the certificates to verify the identity of the provider.

     Note: There is no need to add a certificate if you request fonts from pre-installed providers. However, you must always provide a certificate if you request fonts through the support library.

   Kotlin

   val request = FontRequest(
           "com.example.fontprovider.authority",
           "com.example.fontprovider",
           "my font",
           certs
   )
   

   Java

   FontRequest request = new FontRequest("com.example.fontprovider",
                      "com.example.fontprovider", "my font", certs);
   

   Note: You can receive the parameter values from your font provider. Android Studio automatically populates these values for the providers it supports in its UI.

2. Create an instance of the FontsContract.FontRequestCallback class.
3. Override the onTypefaceRetrieved() method to indicate the font request is complete. Provide the retrieved font as the parameter. You can use this method to set the font, as needed. For example, you can set the font on a TextView
4. Override the onTypefaceRequestFailed() method to receive information about errors in the font request process. For more information about error codes, refer to the error code constants.
5. Call the FontsContract.requestFont() method to retrieve the font from the font provider. The method initiates a check to determine if the font exists in the cache. If the font is not available locally, it calls the font provider, retrieves the font asynchronously, and passes the result to the callback. Pass the following parameters:
   • an instance of the Context class
   • an instance of the android.graphics.fonts.FontRequest class
   • a callback to receive the results of the font request
   • a handler to fetch fonts on a thread

   Note: Ensure this handler is not the User Interface thread handler.

The following sample code illustrates the overall Downloadable Fonts process:

Kotlin

val request = FontRequest(
        "com.example.fontprovider.authority",
        "com.example.fontprovider",
        "my font",
        certs
)
val callback = object : FontsContract.FontRequestCallback() {

    override fun onTypefaceRetrieved(typeface: Typeface) {
        // Your code to use the font goes here
        ...
    }

    override fun onTypefaceRequestFailed(reason: Int) {
        // Your code to deal with the failure goes here
        ...
    }
}
FontsContract.requestFonts(context, request, handler, null, callback)

Java

FontRequest request = new FontRequest("com.example.fontprovider.authority",
        "com.example.fontprovider", "my font", certs);
FontsContract.FontRequestCallback callback =
    new FontsContract.FontRequestCallback() {
        @Override
        public void onTypefaceRetrieved(Typeface typeface) {
            // Your code to use the font goes here
            ...
        }

        @Override
        public void onTypefaceRequestFailed(int reason) {
            // Your code to deal with the failure goes here
            ...
        }
};
FontsContract.requestFonts(context, request, handler, null, callback);

For more information about how to download a font from a font provider, see the Downloadable Fonts sample app Java | Kotlin.

Using Downloadable Fonts via the support library

The Support Library 26 provides support to the Downloadable Fonts feature on devices running Android API versions 14 or higher. The android.support.v4.provider package contains FontsContractCompat and FontRequest classes to implement the backward-compatible Downloadable Fonts feature support. The support library classes contain methods similar to framework. The process of downloading fonts is also similar to the one mentioned in the Downloading fonts section.

To download fonts by using the support library, import the FontsContractCompat and FontRequest classes from the android.support.v4.provider package. Create the instances of these classes instead of FontsContract and android.graphics.fonts.FontRequest framework classes.

Note: You must provide a certificate when you request fonts through the support library. This is applicable even for the pre-installed font providers.

Adding support library dependency

To use the FontsContractCompat and FontRequest classes, you must modify your app project's classpath dependencies within your development environment.

To add a support library to your application project:

1. Open the build.gradle file of your application.
2. Add the support library to the dependencies section.

dependencies {
    ...
    compile "com.android.support:support-compat:28.0.0"
}

Using Downloadable Fonts as resources in XML

Android 8.0 (API level 26) and Support Library 26 offer a faster and more convenient way to declare a custom font as a resource in the XML layout. This means, there is no need to bundle the font as an asset. You can define a custom font for your entire theme, which accelerates usability for multiple weights and styles, such as Bold, Medium, or Light, when provided.

1. Create a new XML file in the res/font folder.
2. Add <font-family> root element and set the font-related attributes as shown in the following sample XML file:

<?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:android="http://schemas.android.com/apk/res/android"
        android:fontProviderAuthority="com.example.fontprovider.authority"
        android:fontProviderPackage="com.example.fontprovider"
        android:fontProviderQuery="example font"
        android:fontProviderCerts="@array/certs">
</font-family>

3. Refer to the file as @font/font_file_name in the layout XML file. You can also use the getFont() method to retrieve the file programmatically. For example, getFont(R.font.font_file_name).

Pre-declaring fonts in the manifest

Layout inflation and resource retrieval are synchronous tasks. By default, the first attempt to retrieve fonts triggers a request to the font provider, and therefore increases the first layout time. To avoid the delay, you can pre-declare fonts that need retrieving in your manifest. After the system retrieves the font from the provider, it is available immediately. If the font retrieval takes longer than expected, the system aborts the fetching process and uses the default font.

To pre-declare fonts in the manifest, perform the following steps:

1. Create a resources array in res/values/arrays.xml and declare the Downloadable Fonts that you want to prefetch.

res/values/arrays.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <array name="preloaded_fonts">
        <item>@font/font1</item>
        <item>@font/font2</item>
    </array>
</resources>

2. Use a meta-data tag to declare the resource array in your manifest.

<meta-data android:name="preloaded_fonts" android:resource="@array/preloaded_fonts" />

Adding certificates

When a font provider is not preinstalled or if you are using the support library, you must declare the certificates the font provider is signed with. The system uses the certificates to verify the font provider's identity.

Note: Android Studio can automatically populate the values for the Google Play services provider if you use the font selector tool in Android Studio. For more information about using Android Studio for downloading fonts, go to the Using Downloadable Fonts via Android Studio and Google Play services section.

Perform the following steps to add certificates:

1. Create a string array with the certificate details. For more information about certificate details, refer to your font provider's documentation.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="certs">
       <item>MIIEqDCCA5CgAwIBAgIJA071MA0GCSqGSIb3DQEBBAUAMIGUMQsww...</item>
    </string-array>
</resources>

2. Set the fontProviderCerts attribute to the array.

android:fontProviderCerts="@array/certs"

Note: If the provider has more than one set of certs, you can define an array of string arrays.