Wix OAuth安装器重定向至undefined而非指定URL的问题排查

背景 #

我正在开发一款需要访问Wix站点联系人的外部应用，目标是获取access token和refresh token来调用Wix Contacts REST API。参照custom-authentication-legacy文档，我已在Wix开发者控制台创建应用，将AppUrl和RedirectURL均配置为外部应用域名https://example.com，并获取了appId和appSecret。

实现的OAuth流程步骤 #

步骤1：引导用户授权跳转 #

用户点击“Activate Wix”按钮时，应用将其重定向至Wix安装页面，携带appId、state（内部id_token）、redirectUrl参数，代码如下：

async function wix_activate() {
    const id_token = oauth.get_tokens().id_token;

    // Build the base URL
    const baseUrl = "https://www.wix.com/installer/install";
    const appId = <MyAppId>;
    const redirectUrl = "https://example.com";

    if (!baseUrl || !appId || !redirectUrl ) {
       console.error('OAuth params not configured');
       return;
    }

    // Build the query parameters
    const params = new URLSearchParams({
       appId: appId,
       state: id_token,
       redirectUrl: redirectUrl,
    });

    // Construct the final URL
    const url = `${baseUrl}?${params.toString()}`;
    console.log('OAuth URL:', url);

    // Open the popup
    const popup_activate = window.open(url);
}

步骤2：授权后回调处理 #

根据文档，用户授权后应重定向至https://example.com?code=<AUTH_CODE>，我编写的处理代码如下：

async function init() {
   
    const query = new window.URLSearchParams(window.location.search);
    if (query.has('code')) {
       const queryParams = {};
       for (const [key, value] of query.entries()) {
          queryParams[key] = value;
       }
       console.log(queryParams);
      
      //send an http request to my callback in the backend
    }
}

遇到的问题 #

实际用户授权后，页面重定向至https://www.wix.com/installer/undefined，触发404错误，无法正常跳转到指定的redirectUrl并获取授权码。我已验证跳转参数符合文档要求，但问题依然存在。

疑问 #

1. 导致Wix生成含undefined的重定向URL的原因是什么？
2. Wix开发者控制台是否需要额外配置参数？
3. custom-authentication-legacy流程是否存在已知问题导致该现象？

调试指导及解决方案 #

1. 参数校验 #

• 确认redirectUrl参数拼写正确：Wix legacy授权流程对参数大小写敏感，需严格使用redirectUrl格式。
• 替换appId占位符：代码中<MyAppId>必须替换为真实的应用ID，未替换会导致参数无效，触发重定向错误。
• 检查state参数有效性：确保oauth.get_tokens().id_token返回有效字符串，若为undefined会破坏Wix的重定向逻辑。

2. 开发者控制台配置检查 #

• 保持Redirect URL一致：控制台中配置的Redirect URL必须与跳转时传入的redirectUrl完全匹配，包括协议、域名，无多余路径或斜杠。
• 校验AppUrl配置：虽然主要用于展示，但错误的AppUrl可能影响应用合法性校验，建议与Redirect URL保持一致。
• 确认权限已开启：在控制台Permissions页面，确保添加了Contacts.Read等所需权限，无权限配置会导致授权流程中断。

3. Legacy流程特殊注意事项 #

• 固定授权跳转地址：必须使用https://www.wix.com/installer/install，不能使用其他域名或路径。
• 避免弹窗跳转：部分浏览器的弹窗拦截可能导致参数传递异常，建议改用window.location.href直接跳转。
• 确认应用状态：应用需处于Published状态，未发布的应用无法完成授权流程。

4. 调试技巧 #

• 打印最终跳转URL：在wix_activate中输出构造后的URL，确认所有参数无undefined值。
• 监控网络请求：用浏览器开发者工具Network面板查看Wix返回的重定向响应，排查错误信息。
• 用Postman测试：直接构造授权URL发起请求，排除前端代码干扰，验证参数有效性。

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