Implementing Text Classification

Text classification uses machine learning techniques to help developers classify text.

Android 9 release text classification enhancements

Android 9 extended the text classification framework introduced in Android 8.1 with the new Text Classifier service. The Text Classifier service is the recommended way for OEMs to provide text classification system support. The Text Classifier service may be part of any system APK and may be updated when necessary.

Android 9 includes a default Text Classifier service implementation ( TextClassifierImpl) that is used unless you replace it with a custom Text Classifier service implementation.

Implementing a custom Text Classifier service

The following sections describe how to implement a custom Text Classifier service that you develop.

Extend android.service.textclassifier.TextClassifierService

public final class TextClassifierServiceImpl
        extends TextClassifierService {

    // Returns TextClassifierImpl.
    private final TextClassifier tc = getLocalTextClassifier();

    @Override
    public void onSuggestSelection(
            @Nullable TextClassificationSessionId sessionId,
            @NonNull TextSelection.Request request,
            @NonNull CancellationSignal cancellationSignal,
            @NonNull Callback<TextSelection> callback) {
        CompletableFuture.supplyAsync(
                () -> tc.suggestSelection(request))
                .thenAccept(r -> callback.onSuccess(r));
    }

    @Override
    public void onClassifyText(
            @Nullable TextClassificationSessionId sessionId,
		@NonNull TextClassification.Request request,
		@NonNull CancellationSignal cancellationSignal,
		@NonNull Callback<TextClassification> callback) {
        ...
    }

    @Override
    public void onGenerateLinks(
            @Nullable TextClassificationSessionId sessionId,
            @NonNull TextLinks.Request request,
            @NonNull CancellationSignal cancellationSignal,
            @NonNull Callback<TextLinks> callback) {
        ...
    }
    ...
}

Define the service in the Android manifest

[AndroidManifest.xml]

<service android:name=".TextClassifierServiceImpl"
  android:permission="android.permission.BIND_TEXTCLASSIFIER_SERVICE">
    <intent-filter>
      <action android:name=
        "android.service.textclassifier.TextClassifierService"/>
    </intent-filter>
</service>

Note that the service must require the android.permission.BIND_TEXTCLASSIFIER_SERVICE permission and must also specify the android.service.textclassifier.TextClassifierService Intent action.

Set a system default Text Classifier service in the config overlay

[config.xml]

<string name="config_defaultTextClassifierPackage" translatable="false">com.example.textclassifierservice</string>

Build the Text Classifier service into the system image

Your custom Text Classifier service can be a standalone APK that is built into the system image or a part of another system APK. The system uses PackageManager.MATCH_SYSTEM_ONLY to resolve the service.

Testing

Run Tests in android.view.textclassifier.cts

Other text classification changes in Android 9

Refer to Inspecting installed language modules.

Android 9 model files are incompatible with Android 8.x model files.

Android 9 model files have the naming pattern: texclassifier.[language-code].model (e.g. textclassifier.en.model) instead of textclassifier.smartselection.en.model in Android 8.x.

Obtaining the latest text classification model files

To obtain the most up-to-date models the following script can be run, which updates the TextClassifier models in the source tree:

external/libtextclassifier/models/update.sh

Android release 8.1 text classification

Android 8.1 introduced the TextClassfier API to implement text classification

TextClassificationManager tcm =
    context.getSystemService(TextClassificationManager.class);
TextClassifier classifier = tcm.getTextClassifier();
TextSelection selection = classifier.suggestSelection(...);
TextClassification classification = classifier.classifyText(...);

Developers may choose to set a custom text classifier:

tcm.setTextClassifier(customTextClassifier);

But if an app developer sets the text classifier to null, a system default text classifier is returned for getTextClassifier().

See: android.view.textclassifier.TextClassifierImpl

TextView and WebView use the TextClassifier for smart selection and smart text share features:

Figure 1. TEXTCLASSIFIER usage.

TextClassifier neural-net models

The Android Open Source Project (AOSP) features a number of neural network models for classifying text. Each model file is trained for a single language. You may choose to install any combination of models. The models are defined in:

external/libtextclassifier/Android.mk

Pre-installing language models on devices

You may specify a bundle of language models and install them on a device:

# -----------------------
# Smart Selection bundles
# -----------------------

include $(CLEAR_VARS)
LOCAL_MODULE           := textclassifier.smartselection.bundle1
LOCAL_REQUIRED_MODULES := textclassifier.smartselection.en.model
LOCAL_REQUIRED_MODULES += textclassifier.smartselection.es.model
LOCAL_REQUIRED_MODULES += textclassifier.smartselection.de.model
LOCAL_REQUIRED_MODULES += textclassifier.smartselection.fr.model
include $(BUILD_STATIC_LIBRARY)

For example, in device/google/marlin/device-common.mk

# TextClassifier smart selection model files
PRODUCT_PACKAGES += \
    textclassifier.smartselection.bundle1

Inspecting installed language modules

Use ADB to list the files in the directory:

$ adb shell ls -l /etc/textclassifier
-rw-r--r-- 1 root root ... textclassifier.smartselection.de.model
-rw-r--r-- 1 root root ... textclassifier.smartselection.en.model
-rw-r--r-- 1 root root ... textclassifier.smartselection.es.model
-rw-r--r-- 1 root root ... textclassifier.smartselection.fr.model

Model updates

Models can be updated either by having a new model included as part of a system image update, or dynamically via having a system component that would trigger an update through the System API ACTION_UPDATE_SMART_SELECTION intent. By broadcasting this System API intent, the framework is able to update the language model of the currently set language. The models themselves contain the supported language and a version number so the latest appropriate model is used.

So you don't need to preload models for all languages because they can be added later. If no model file is found for the specified language, text classification will return no-op values.

Compatibility Test Suite tests

The associated Android Compatibility Test Suite (CTS) tests can be found in:

cts/tests/tests/view/src/android/view/textclassifier/cts/TextClassificationManagerTest.java

cts/tests/tests/widget/src/android/widget/cts/TextViewTest.java

  • testSmartSelection
  • testSmartSelection_dragSelection
  • testSmartSelection_resetSelection