iOS现有APP无法通过Gmail邮件唤起，激活按钮跳转问题求助

Hey there! Let’s work through your universal link problems—since you’ve already set up the basics (associated domains, apple-app-site-association file, and the continue userActivity method), we’ll focus on the easy-to-miss details that often cause these headaches, especially with Gmail.

First: Double-Check Your apple-app-site-association File #

Even if you’ve added it, small formatting errors can break everything:

• Strict JSON rules: No comments, no trailing commas. A valid file should look like this:

  {
    "applinks": {
      "apps": [],
      "details": [
        {
          "appID": "YOUR_TEAM_ID.YOUR_BUNDLE_ID",
          "paths": [ "/activate/*", "*" ] // Match your activation link's path here
        }
      ]
    }
  }
  

• Hosting requirements: Make sure it’s hosted at https://yourdomain.com/.well-known/apple-app-site-association (preferred) or the root directory. Your site must have a valid, trusted HTTPS certificate—Gmail is strict about this, so self-signed certs won’t work.
• Validate with Apple’s tool: Use Apple’s official validation tool (found in your Developer Account) to confirm the file is recognized correctly.

Verify Associated Domains & Provisioning Profiles #

• In Xcode, go to your target’s Signing & Capabilities tab. Ensure Associated Domains is enabled, and add applinks:yourdomain.com (no http:// or https://, no paths).
• Regenerate your Provisioning Profile after adding the capability—old profiles won’t include the universal link permission, which causes failures on real devices.

Fix the continue userActivity Implementation #

Depending on your iOS version, make sure you’re using the right delegate:

For iOS 13+ (SceneDelegate): #

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return
    }
    
    // Handle your activation link here (e.g., parse the token and navigate to the activation screen)
    print("Received universal link: \(url)")
}

For Older iOS Versions (AppDelegate): #

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
        guard let url = userActivity.webpageURL else { return false }
        
        // Process the activation link
        return true // Tell iOS you've handled the activity
    }
    return false
}

• Critical: Return true in the AppDelegate method to confirm you’ve processed the link—if you return false, iOS might fall back to opening the web page.

Fix Gmail-Specific Link Issues #

Gmail often modifies links or caches old configurations, which breaks universal links:

• Avoid Gmail’s link wrapping: Ensure your activation email uses the raw, direct URL (e.g., https://yourdomain.com/activate?token=123) instead of any wrapped or tracked links.
• Clear Gmail’s cache: If you recently updated your universal link setup, Gmail might be using old data. Uninstall and reinstall the Gmail app on your test device to clear cached settings.
• Test with the Gmail app, not webmail: Web-based Gmail behaves differently than the iOS app—always test on the native Gmail app to replicate real user behavior.

Test Universal Links Correctly #

• Don’t test by typing the link into Safari (it often prioritizes the web page). Instead, send the link to yourself via Notes or Messages, then tap it—this mimics how users will interact with the email link.
• Use this terminal command to test on a simulator:

  xcrun simctl openurl booted "https://yourdomain.com/activate?token=test123"
  

  This will directly trigger the universal link and let you see if your userActivity method is called.

Prevent Redirects to the App Store #

As long as:

1. The user has your app installed
2. Your apple-app-site-association paths correctly match the activation link
3. All configuration steps are correct

The link will open your app directly. If the app isn’t installed, it’ll fall back to your web page—you can customize that page to prompt users to download the app, but that’s optional.

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