使用Flutter Branch SDK自定义短链别名时遭遇400错误求助

问题 #

在Flutter应用中实现帖子分享功能，要求每个帖子对应唯一分享链接。尝试通过帖子ID自定义链接别名时，返回以下错误：

I/BranchSDK(22688): Server returned: [30e871a8ca2c41769294515af1169f7b-2023061409] Status: [400]; Data: {"error":{"code":400,"message":"Alias provided is invalid"}}
I/flutter (22688): Trouble creating a URL. Unable to create a URL with that alias. If you want to reuse the alias, make sure to submit the same properties for all arguments and that the user is the same owner.

相关代码：

void initDeepLinkData() {
  metadata = BranchContentMetaData()
    ..addCustomMetadata('Key', 'share')
    ..addCustomMetadata('Offer_Id', offerId.toString())
    ..addCustomMetadata('Description', desc)

  buo = BranchUniversalObject(
      canonicalIdentifier: '/$offerId',

  //parameter canonicalUrl
      //If your content lives both on the web and in the app, make sure you set its canonical URL
      // (i.e. the URL of this piece of content on the web) when building any BUO.
      // By doing so, we’ll attribute clicks on the links that you generate back to their original web page,
      // even if the user goes to the app instead of your website! This will help your SEO efforts.
      canonicalUrl: 'https://www.wowclinic.net',
      title: 'Wow Clinic',
      imageUrl: imageURL,
      contentDescription: desc,

      contentMetadata: metadata,
      keywords: ['Plugin', 'Branch', 'Flutter'],
      publiclyIndex: true,
     locallyIndex: true,
      expirationDateInMilliSec: DateTime.now()
          .add(const Duration(days: 365))
          .millisecondsSinceEpoch);

  lp = BranchLinkProperties(
      channel: 'facebook',
      feature: 'sharing',
      //parameter alias
      //Instead of our standard encoded short url, you can specify the vanity alias.
      //For example, instead of a random string of characters/integers, you can set the vanity alias as *.app.link/devonaustin.
      //Aliases are enforced to be unique** and immutable per domain, and per link - they cannot be reused unless deleted.
      alias: 'https://wowclinic.app.link/offers/$offerId', //define link url,
      stage: 'new share',
      campaign: 'offer_share_campaign',
      tags: ['one', 'two', 'three'])

    ..addControlParam('\$ios_url', '/offers/$offerId')
    ..addControlParam('\$android_url', '/offers/$offerId')
    ..addControlParam('\$uri_redirect_mode', '1')
    ..addControlParam('\$ios_nativelink', true)
    ..addControlParam('\$match_duration', 7200)
    ..addControlParam('\$always_deeplink', true)
    ..addControlParam('\$android_redirect_timeout', 750)
    ..addControlParam('referring_user_id', 'user_id');

  eventStandard = BranchEvent.standardEvent(BranchStandardEvent.SHARE)

}

void generateLink(BuildContext context) async {
  BranchResponse response =
  await FlutterBranchSdk.getShortUrl(buo: buo!, linkProperties: lp);
  if (response.success) {
    url = response.result;
    Share.share(url);
    // showGeneratedLink(context, response.result);
  } else {
    print(response.errorMessage);
    GblFn.showSnackbar(
        ' Error:', 'Error : ${response.errorCode} - ${response.errorMessage}');
  }
}

问题排查与解决 #

核心原因 #

Branch SDK的alias参数不需要传入完整URL，它只是自定义的链接后缀，会自动拼接在你的Branch域名（wowclinic.app.link）后面。你传入了完整域名+路径，违反了Alias的格式要求，导致返回400错误。

修复步骤 #

1. 修正Alias参数值
   把alias的值改成纯路径部分，去掉前面的域名：

   alias: 'offers/$offerId', // 只保留后缀路径
   

   Branch会自动生成https://wowclinic.app.link/offers/$offerId这样的完整链接。

2. 验证OfferId的格式
   确保offerId只包含字母、数字、下划线、短横线或斜杠，不能有空格、特殊符号（如!@#$%^&*），否则也会触发Alias无效的错误。

3. 保证Alias的唯一性
   Branch要求每个Alias在你的域名下唯一，如果之前已经用这个offers/$offerId生成过链接，要么删除Branch后台对应的旧链接，要么更换新的Alias格式（比如加上前缀offer-$offerId）。

4. 检查CanonicalIdentifier（可选）
   建议把canonicalIdentifier和Alias保持一致，避免混淆：

   canonicalIdentifier: '/offers/$offerId',
   

修改后的关键代码片段 #

lp = BranchLinkProperties(
    channel: 'facebook',
    feature: 'sharing',
    alias: 'offers/$offerId', // 修正后的alias
    stage: 'new share',
    campaign: 'offer_share_campaign',
    tags: ['one', 'two', 'three'])
  // 其他参数保持不变
  ..addControlParam('\$ios_url', '/offers/$offerId')
  ..addControlParam('\$android_url', '/offers/$offerId')
  // ... 其余控制参数

内容的提问来源于stack exchange，提问作者Roa'a