React Native Background Actions点击通知跳转应用配置问题

当前配置里的linkingURI使用了官方示例的占位值yourSchemeHere://chat/jane，该自定义协议未在你应用的Android清单中注册，系统无法找到对应处理该URI的应用时，会默认拉起具备通用URI处理权限的系统相册，无法定位到你的应用。

1. 配置Android端Deep Link匹配规则 #

找到项目路径下的android/app/src/main/AndroidManifest.xml文件，在应用主入口MainActivity的标签内新增自定义协议的intent-filter，不要删除原有的桌面入口intent-filter配置。

<activity
  android:name=".MainActivity"
  android:label="@string/app_name"
  android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
  android:launchMode="singleTask"
  android:windowSoftInputMode="adjustResize"
  android:exported="true">
  <!-- 原有桌面入口配置，请勿删除 -->
  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>

  <!-- 新增：后台通知点击唤起的协议匹配配置 -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- 替换为你应用独有的自定义scheme和host，不要和其他应用重名 -->
    <data android:scheme="yourapp" android:host="backgroundnotify" />
  </intent-filter>
</activity>

配置注意点：

• android:exported="true"必须添加，Android 12及以上版本不允许外部组件拉起未声明exported的Activity
• android:launchMode="singleTask"建议配置，避免点击通知时重复创建应用实例
• 自定义scheme不要使用http/https这类通用协议，避免被浏览器、系统应用拦截

2. 修改JS端后台任务配置 #

将原配置中占位的linkingURI替换为和AndroidManifest中完全匹配的自定义协议地址，示例如下：

const options = {
    taskName: 'Downloading',
    taskTitle: 'ExampleTask title',
    taskDesc: 'ExampleTask description',
    taskIcon: {
      name: 'ic_launcher',
      type: 'mipmap',
    },
    color: '#ff00ff',
    // 和Manifest中<data>标签配置的scheme、host完全对应
    linkingURI: 'yourapp://backgroundnotify/task',
    parameters: {
      delay: 15000,
    },
};

3.（可选）配置通知点击后的指定页面跳转 #

如果需要点击通知后直接打开应用内指定页面（例如下载任务列表页），可以在应用入口处监听系统Linking事件做路由分发，示例代码如下：

import { Linking } from 'react-native';
import { useEffect } from 'react';
// 替换为你项目中实际使用的路由实例引用
import { navigationRef } from './src/utils/navigation';

export default function App() {
  useEffect(() => {
    // 处理应用冷启动场景下的通知点击唤起
    Linking.getInitialURL().then(handleNotifyJump);
    // 处理应用后台存活场景下的通知点击唤起
    const urlListener = Linking.addEventListener('url', ({ url }) => {
      handleNotifyJump(url);
    });

    return () => urlListener.remove();
  }, []);

  const handleNotifyJump = (url) => {
    if (!url) return;
    // 匹配后台通知唤起的协议
    if (url.startsWith('yourapp://backgroundnotify')) {
      // 替换为你需要跳转的实际页面路由
      navigationRef.current?.navigate('DownloadTaskPage');
    }
  };

  // 原有应用渲染逻辑
  return <AppContainer />
}

• 修改完AndroidManifest配置后，必须卸载设备上的旧安装包重新编译安装，否则系统不会更新应用的intent匹配规则
• 确认taskIcon配置的资源真实存在于对应资源目录下，图标资源缺失时部分机型会出现通知点击行为异常
• Android 13及以上版本需要提前申请POST_NOTIFICATIONS运行时权限，否则通知无法正常展示，点击逻辑也会失效
• 自定义scheme尽量使用和应用包名关联的唯一值，避免和其他应用scheme重名导致匹配失败

内容的提问来源于stack exchange，提问作者Rover