В этом руководстве рассказывается, как настроить и запустить заметную службу Android (активную службу, или FGS) в частном процессе из приложения Unity.
1. Как настроить поддержку заметных сервисов
В этом разделе объясняется, как настроить необходимые разрешения и объявить службу в манифесте вашего проекта.
1.1. Разрешения и декларация сервиса
В специальном файле Assets/Plugins/Android/AndroidManifest.xml должны быть объявлены действия панели запуска, разрешения на использование заметных сервисов, уведомлений и сети, а также сам сервис:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.INTERNET" />
<application>
<activity
android:name="com.unity3d.player.UnityPlayerActivity"
android:theme="@style/UnityThemeSelector"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<meta-data android:name="unityplayer.UnityActivity" android:value="true" />
</activity>
<service
android:name="com.sample.fgs.DownloadService"
android:process=":downloader"
android:exported="false"
android:stopWithTask="false"
android:foregroundServiceType="dataSync" />
</application>
</manifest>
foregroundServiceType должно соответствовать реальной работе: dataSync для передачи, mediaPlayback для воспроизведения, location для отслеживания местоположения. Оно должно соответствовать разрешению FOREGROUND_SERVICE_<TYPE> и вызову startForeground. Если все три элемента не согласованы, запустить службу не удастся.
1.2. Добавьте Java-файл service-process в проект Unity
Процесс службы переднего плана выполняется на Java. Упакуйте код Java реализации сервиса в JAR-файл и поместите его в каталог Assets/Plugins/Android/. Unity автоматически включает JAR-файлы из этого каталога в папку libs/ Gradle и упаковывает их в APK. Процесс сервиса загружает эти классы во время выполнения. Подробнее о том, как реализовать сервис на Java или Kotlin…
2. Настройте отдельный процесс
Граница процесса включается с помощью одного атрибута манифеста:
android:process=":downloader"
Двоеточие в начале создает частный процесс приложения с именем your.package.name:downloader. У него другой идентификатор процесса, и он может продолжать работу после завершения основного процесса.
2.1. В процессе обслуживания нет единства
Чтобы не переносить libunity.so Unity, среду выполнения IL2CPP и другие подобные элементы в процесс сервиса, Java на стороне сервиса не должна использовать классы Unity (включая UnityPlayer.currentActivity) и должна зависеть только от Android Context, Intent extras и API платформы. Среда выполнения Unity загружается только через UnityPlayerActivity основного процесса. Частный процесс :downloader не загружает эти библиотеки, поэтому ссылки на классы Unity не работают в процессе сервиса.
2.2. Точки входа для запуска процессов
После того как основной процесс вызывает startForegroundService, система разветвляет процесс сервиса :downloader:
- Создает экземпляр
Applicationи вызываетApplication.onCreate. Это выполняется в каждом процессе, поэтому инициализацию, необходимую для процесса сервиса, нужно выполнить здесь снова. Дополнительную информацию можно найти в разделе 2.3. - Создает
DownloadServiceи вызываетonCreate– это точка входа в процесс сервиса. - Вызывает
onStartCommandс намерением, созданным при запуске. Сервис переходит в активный режим и запускает рабочий процесс. Дополнительную информацию вы найдете в разделе 3.1.
2.3. Состояние существует один раз для каждого процесса
Код Dex доступен только для чтения, но состояние среды выполнения – нет:
Application.attachBaseContextиApplication.onCreateзапускаются в каждом процессе, в котором размещаются компоненты приложения.- Статические инициализаторы и статические поля существуют независимо в каждом процессе. Назначение статического поля в основном процессе не обеспечивает связь с сервисом.
- Unity, C# и действия остаются в основном процессе.
3. Реализация на Java
В этом разделе рассматривается часть модуля FGS, написанная на Java: 3.1 и 3.2 – это DownloadService в процессе сервиса; 3.3 – это FgsBridge в основном процессе (точка входа, которую C# вызывает с помощью JNI).
3.1. Сначала переведите приложение в активный режим
public class DownloadService extends Service {
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
try {
startForegroundCompat();
// Start the download thread; must come after promoting to foreground
// ...
} catch (Exception e) {
Log.e(TAG, "onStartCommand() failed [errorType="
+ e.getClass().getSimpleName() + "]: " + e.getMessage(), e);
stopSelf();
}
return START_NOT_STICKY;
}
private void startForegroundCompat() {
Notification notification = buildNotification(0L);
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
startForeground(NOTIFICATION_ID, notification,
ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC);
} else {
startForeground(NOTIFICATION_ID, notification);
}
}
...
3.2. Добавьте уведомление
Для заметной службы требуется постоянное уведомление в канале уведомлений, чтобы сообщать о ходе выполнения. Уведомление содержит действие Stop, которое отправляет ACTION_STOP в сам сервис с помощью PendingIntent.getService, чтобы остановить его.
private Notification buildNotification(long progressBytes) {
int progressMib = (int) (progressBytes / MIB);
Intent launchIntent = getPackageManager().getLaunchIntentForPackage(getPackageName());
PendingIntent contentIntent = launchIntent != null
? PendingIntent.getActivity(this, 0, launchIntent,
PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT)
: null;
Intent stopIntent = new Intent(this, DownloadService.class)
.setAction(ACTION_STOP);
PendingIntent stopPendingIntent = PendingIntent.getService(this, 0,
stopIntent, PendingIntent.FLAG_IMMUTABLE
| PendingIntent.FLAG_UPDATE_CURRENT);
Notification.Builder builder = new Notification.Builder(this,
CHANNEL_ID)
.setContentTitle("Download service")
.setContentText("Downloaded " + progressMib + " MB / " + TOTAL_MIB + " MB")
.setSmallIcon(android.R.drawable.stat_sys_download)
.setProgress(TOTAL_MIB, progressMib, false)
.setOngoing(true)
.setOnlyAlertOnce(true)
.addAction(new Notification.Action.Builder(null,
"Stop", stopPendingIntent).build());
if (contentIntent != null) {
builder.setContentIntent(contentIntent);
}
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
builder.setForegroundServiceBehavior(
Notification.FOREGROUND_SERVICE_IMMEDIATE);
}
return builder.build();
}
3.3. Точка входа хоста Java
FgsBridge – точка входа Java, которую основной процесс использует для управления FGS (выполняется в основном процессе, а не в процессе сервиса). C# вызывает эти статические методы с помощью JNI, чтобы запускать и останавливать сервис, а также управлять разрешением на уведомления:
public class FgsBridge {
// Start the :downloader perceptible service and begin downloading
public static void startDownloadService(Context context) {
try {
context.startForegroundService(new Intent(context, DownloadService.class));
} catch (Exception e) {
Log.e(TAG, "startDownloadService() failed [errorType="
+ e.getClass().getSimpleName() + "]: " + e.getMessage(), e);
}
}
// Stop the service: sends a stop intent; the service removes its
// notification before exiting
public static void stopDownloadService(Context context) {
try {
context.startService(new Intent(context, DownloadService.class)
.setAction(ACTION_STOP));
} catch (Exception e) {
Log.e(TAG, "stopDownloadService() failed [errorType="
+ e.getClass().getSimpleName() + "]: " + e.getMessage(), e);
}
}
// Request notification permission (only needed on API 33+; if already
// granted, no dialog is shown and it returns immediately)
public static void requestNotificationPermission(Activity activity) {
if (Build.VERSION.SDK_INT < 33) {
return;
}
try {
activity.requestPermissions(
new String[] { POST_NOTIFICATIONS }, NOTIFICATION_PERMISSION_REQUEST);
} catch (Exception e) {
Log.e(TAG, "requestNotificationPermission() failed [errorType="
+ e.getClass().getSimpleName() + "]: " + e.getMessage(), e);
}
}
}
4. Запуск FGS и управление им из Unity (C#)
AndroidBridge – это оболочка C#, которая вызывает FgsBridge с помощью JNI. Три реализации метода:
public static void StartDownloadService()
{
#if UNITY_ANDROID && !UNITY_EDITOR
CallStatic("startDownloadService");
#else
Debug.Log("StartDownloadService() no-op outside Android");
#endif
}
public static void StopDownloadService()
{
#if UNITY_ANDROID && !UNITY_EDITOR
CallStatic("stopDownloadService");
#else
Debug.Log("StopDownloadService() no-op outside Android");
#endif
}
public static void RequestNotificationPermission()
{
#if UNITY_ANDROID && !UNITY_EDITOR
CallStatic("requestNotificationPermission");
#else
Debug.Log("RequestNotificationPermission() no-op outside Android");
#endif
}
CallStatic – это внутренний вспомогательный класс JNI, который разрешает класс FgsBridge и вызывает соответствующий статический метод Java. RequestNotificationPermission
должен вызываться при запуске приложения, чтобы уведомление появлялось сразу после запуска процесса службы.