create-react-native-app通用链接实现：跨平台一致体验

【免费下载链接】create-react-native-app Create React Native apps that run on iOS, Android, and web 项目地址: https://gitcode.com/gh_mirrors/cr/create-react-native-app

你是否曾为React Native应用在iOS、Android和Web平台间的链接跳转不一致而困扰？用户点击链接时，有时打开网页，有时打开应用，体验碎片化严重。本文将带你使用create-react-native-app实现通用链接（Universal Link），打造跨平台一致的跳转体验，让用户在任何设备上都能获得无缝的应用内导航。

通用链接工作原理

通用链接（Universal Link）是Apple推出的深度链接技术，Android也有类似的App Link。它们允许应用注册域名，当用户点击该域名的链接时，系统会直接打开应用而非浏览器。create-react-native-app通过整合Expo生态和原生配置，简化了这一流程。

项目初始化与依赖配置

首先确保你使用最新版本的create-react-native-app创建项目。通过src/index.ts中的初始化流程，我们可以看到项目创建时会自动配置基础依赖：

npx create-react-native-app my-universal-link-app
cd my-universal-link-app

安装处理通用链接的核心依赖：

# 使用Expo的链接处理库
expo install expo-linking
# 用于深度链接路由
npm install react-navigation

配置Expo通用链接

修改app.json配置文件，添加expo.hostUri和scheme字段。create-react-native-app在src/Template.ts中处理模板文件时，会将这些配置注入到项目中：

{
  "expo": {
    "name": "my-universal-link-app",
    "slug": "my-universal-link-app",
    "scheme": "myapp",
    "hostUri": "app.example.com",
    "ios": {
      "supportsTablet": true,
      "associatedDomains": ["applinks:app.example.com"]
    },
    "android": {
      "package": "com.yourcompany.myuniversallinkapp",
      "intentFilters": [
        {
          "action": "VIEW",
          "data": [
            {
              "scheme": "https",
              "host": "app.example.com",
              "pathPrefix": "/"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    },
    "web": {
      "favicon": "./assets/favicon.png"
    }
  }
}

实现链接解析与路由

在App.js中使用expo-linking解析链接并导航到相应页面。create-react-native-app的模板系统(src/Template.ts)会帮你搭建基础架构：

import * as Linking from 'expo-linking';
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';

const Stack = createStackNavigator();

// 配置链接前缀
const linking = {
  prefixes: [Linking.makeUrl('/'), 'https://app.example.com', 'myapp://'],
  config: {
    screens: {
      Home: 'home',
      Profile: 'profile/:userId',
      Settings: 'settings',
    },
  },
};

export default function App() {
  return (
    <NavigationContainer linking={linking} fallback={<Text>Loading...</Text>}>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Profile" component={ProfileScreen} />
        <Stack.Screen name="Settings" component={SettingsScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

处理链接请求与导航

创建一个自定义钩子来处理链接打开事件，确保应用在前台和后台都能响应：

import { useEffect } from 'react';
import * as Linking from 'expo-linking';
import { useNavigation } from '@react-navigation/native';

function useUniversalLink() {
  const navigation = useNavigation();

  useEffect(() => {
    // 处理初始链接
    Linking.getInitialURL().then(url => {
      if (url) {
        handleDeepLink(url);
      }
    });

    // 监听后续链接
    const linkingSubscription = Linking.addEventListener('url', ({ url }) => {
      handleDeepLink(url);
    });

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

  const handleDeepLink = (url) => {
    const { path, queryParams } = Linking.parse(url);
    // 根据路径导航到相应页面
    if (path === '/profile') {
      navigation.navigate('Profile', { userId: queryParams.userId });
    }
  };
}

原生配置与测试

iOS配置

1. 在Apple开发者中心为你的应用开启Associated Domains
2. 创建apple-app-site-association文件并托管在你的域名根目录：

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TeamID.com.yourcompany.myuniversallinkapp",
        "paths": ["*"]
      }
    ]
  }
}

Android配置

1. 创建assetlinks.json文件并托管在你的域名下：

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourcompany.myuniversallinkapp",
    "sha256_cert_fingerprints": ["你的应用签名SHA256指纹"]
  }
}]

测试链接

使用Expo的Linking模块测试链接：

// 在组件中测试
import * as Linking from 'expo-linking';

// 生成通用链接
const url = Linking.makeUrl('/profile', { userId: '123' });
console.log('Generated URL:', url);

// 打开链接
Linking.openURL(url);

常见问题与解决方案

链接不触发应用打开

检查src/Template.ts中的模板生成逻辑，确保associatedDomains和intentFilters正确配置。确认服务器上的apple-app-site-association和assetlinks.json文件可访问。

路由解析错误

使用src/Logger.ts添加调试日志，检查Linking.parse(url)的输出是否符合预期：

import log from './Logger';

const handleDeepLink = (url) => {
  log(`Parsing URL: ${url}`);
  const parsed = Linking.parse(url);
  log(`Parsed path: ${parsed.path}`);
  // ...
};

部署与验证

使用create-react-native-app的内置命令构建并部署应用：

# 构建iOS应用
expo build:ios
# 构建Android应用
expo build:android
# 构建Web应用
expo build:web

部署完成后，使用Apple的验证工具检查通用链接配置：

npx app-store-validationTool --apple-app-site-association https://app.example.com/apple-app-site-association

总结与展望

通过本文介绍的方法，你已成功使用create-react-native-app实现了跨平台通用链接。用户现在可以通过单一链接在iOS、Android和Web平台上获得一致的体验。随着src/Update.ts中版本更新机制的迭代，未来通用链接功能将更加智能化，支持更多复杂场景的深度链接需求。

记住，优质的通用链接体验能显著提升用户留存率和转化率，建议在应用开发初期就规划并实施这一功能。

如果你有任何问题或改进建议，欢迎通过项目的CONTRIBUTING.md文档参与贡献。

祝你的应用开发之旅顺利！

【免费下载链接】create-react-native-app Create React Native apps that run on iOS, Android, and web 项目地址: https://gitcode.com/gh_mirrors/cr/create-react-native-app