Cordova SDK - 支持推荐人短链接

关注
Avatar
Jared Ornstead
Updated
文档

创建简短的推荐人链接

生成简短、可共享的推荐人链接，以实现用户到用户归因并跟踪来自有机推荐的应用程序安装。

版本要求：此功能需要 SDK 3.1.8 或更高版本。短链接在创建后 30 天内保持有效。

概述

什么是推荐人短链接

短链接将冗长、充满参数的奇异链接转换为简洁、安全的 URL，便于通过短信、社交媒体或应用程序内邀请进行分享。

动态创建短链接，以便用户与朋友分享，邀请他们下载和使用您的应用程序。每个短链接都会跟踪推荐用户，使您能够衡量病毒式增长，并将新安装归功于特定的拥护者。

实施要求

所需组件

在创建推荐人短链接之前，请先收集这些元素：

  • 单一链接：引导用户下载应用程序的基本跟踪链接。有关设置说明，请参阅奇异链接常见问题
  • 动态参数：用于为链接添加上下文的可选自定义参数。查看跟踪链接参数中的可用选项
  • 推荐人信息：分享链接的用户的姓名和 ID，以便将新安装归因于推荐人

SDK 方法

创建推荐人短链接

生成带有自定义参数和成功与错误状态回调处理程序的短链接。

方法签名： 

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    baseLink: string,
    referrerName: string,
    referrerId: string,
    passthroughParams: Object,
    resultHandler: Object
): void

参数：

  • baseLink：原始奇异追踪链接 URL
  • referrerName：引用用户的显示名称：引用用户的显示名称
  • referrerId：推荐用户的唯一标识符
  • passthroughParams： 直通参数：包含附加动态参数的对象（可选，如果没有，则传递空对象或 null
  • resultHandler： 结果处理程序：包含onSuccess和onError 回调函数的对象

有关完整的方法文档，请参阅createReferrerShortLink 参考资料。

基本使用示例

使用自定义参数创建短链接，并在成功回调中实现共享逻辑。

JavaScript 
document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
  // Create custom parameters for the link
  var parameters = {
    channel: 'sms',
    campaign_id: 'summer_promo_2025',
    referral_type: 'friend_invite'
  };

  // Define result handler
  var resultHandler = {
    onSuccess: function(shortLink) {
      // Success - short link was created
      console.log('Generated short link:', shortLink);
      
      // Share the link using Cordova social sharing plugin
      shareLink(shortLink);
    },
    onError: function(error) {
      // Error occurred during link creation
      console.error('Error creating short link:', error);
      alert('Failed to create share link. Please try again.');
    }
  };

  // Generate the short referrer link
  cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    'https://sample.sng.link/D52wc/cuvk?pcn=test',  // Base Singular Link
    'John Doe',                                      // Referrer name
    'user_12345',                                    // Referrer ID
    parameters,                                      // Custom parameters
    resultHandler                                    // Callback handler
  );
}

function shareLink(shortLink) {
  // Use Cordova social sharing plugin
  if (window.plugins && window.plugins.socialsharing) {
    window.plugins.socialsharing.share(
      'Join me on this awesome app!',
      'App Invitation',
      null,
      shortLink
    );
  } else {
    // Fallback: Copy to clipboard
    copyToClipboard(shortLink);
    alert('Link copied to clipboard: ' + shortLink);
  }
}

function copyToClipboard(text) {
  // Use Cordova clipboard plugin if available
  if (cordova.plugins.clipboard) {
    cordova.plugins.clipboard.copy(text);
  }
}

高级实现

通过重试逻辑、加载状态和剪贴板回退实现完整的推荐系统。

JavaScript 
// Referral Manager Implementation
var ReferralManager = {
  isGenerating: false,
  lastGeneratedLink: null,
  retryCount: 0,
  maxRetries: 3,

  generateShortLink: function(userId, userName, baseLink, callback) {
    var self = this;
    
    if (self.isGenerating) {
      console.log('Link generation already in progress');
      return;
    }

    self.isGenerating = true;
    self.showLoadingIndicator();

    var parameters = {
      channel: 'in_app',
      campaign_id: 'organic_referral',
      user_tier: 'premium',
      referral_timestamp: Date.now().toString()
    };

    var resultHandler = {
      onSuccess: function(shortLink) {
        self.isGenerating = false;
        self.lastGeneratedLink = shortLink;
        self.retryCount = 0;
        self.hideLoadingIndicator();
        
        console.log('Short link generated:', shortLink);
        
        // Track link generation
        cordova.plugins.SingularCordovaSdk.event('referral_link_created');
        
        if (callback) {
          callback(null, shortLink);
        }
      },
      onError: function(error) {
        console.error('Error generating link:', error);
        
        // Retry logic with exponential backoff
        if (self.retryCount < self.maxRetries) {
          var delay = Math.pow(2, self.retryCount) * 1000; // 1s, 2s, 4s
          self.retryCount++;
          
          console.log('Retrying in ' + delay + 'ms... (Attempt ' + 
                     self.retryCount + '/' + self.maxRetries + ')');
          
          setTimeout(function() {
            self.isGenerating = false;
            self.generateShortLink(userId, userName, baseLink, callback);
          }, delay);
        } else {
          // Max retries reached
          self.isGenerating = false;
          self.retryCount = 0;
          self.hideLoadingIndicator();
          
          if (callback) {
            callback(error, null);
          }
        }
      }
    };

    // Generate the link
    cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
      baseLink,
      userName,
      userId,
      parameters,
      resultHandler
    );
  },

  shareReferralLink: function(userId, userName, baseLink) {
    var self = this;
    
    self.generateShortLink(userId, userName, baseLink, function(error, shortLink) {
      if (error) {
        // Use fallback if available
        if (self.lastGeneratedLink) {
          self.copyToClipboard(self.lastGeneratedLink);
          alert('Failed to generate new link, but your previous referral link has been copied to clipboard!');
        } else {
          alert('Failed to generate referral link. Please check your connection and try again.');
        }
      } else if (shortLink) {
        // Success - share the link
        self.shareViaPlugin(shortLink);
      }
    });
  },

  shareViaPlugin: function(shortLink) {
    var self = this;
    
    if (window.plugins && window.plugins.socialsharing) {
      window.plugins.socialsharing.shareWithOptions(
        {
          message: 'Join me on this awesome app!',
          url: shortLink,
          chooserTitle: 'Share via'
        },
        function(result) {
          console.log('Share completed:', result.completed);
          if (result.completed) {
            // Track successful share
            cordova.plugins.SingularCordovaSdk.event('referral_link_shared');
          }
        },
        function(error) {
          console.error('Share error:', error);
          // Fallback to clipboard
          self.copyToClipboard(shortLink);
          alert('Link copied to clipboard!');
        }
      );
    } else {
      // No share plugin available - copy to clipboard
      self.copyToClipboard(shortLink);
      alert('Referral link copied to clipboard: ' + shortLink);
    }
  },

  copyToClipboard: function(text) {
    if (cordova.plugins && cordova.plugins.clipboard) {
      cordova.plugins.clipboard.copy(text);
      console.log('Copied to clipboard:', text);
    }
  },

  showLoadingIndicator: function() {
    // Show loading UI
    var loader = document.getElementById('loading-indicator');
    if (loader) {
      loader.style.display = 'block';
    }
  },

  hideLoadingIndicator: function() {
    // Hide loading UI
    var loader = document.getElementById('loading-indicator');
    if (loader) {
      loader.style.display = 'none';
    }
  }
};

// Usage example
document.addEventListener('deviceready', function() {
  // Setup share button
  document.getElementById('share-button').addEventListener('click', function() {
    var userId = 'user_12345';
    var userName = 'John Doe';
    var baseLink = 'https://sample.sng.link/D52wc/cuvk?pcn=test';
    
    ReferralManager.shareReferralLink(userId, userName, baseLink);
  });

  // Setup copy button
  document.getElementById('copy-button').addEventListener('click', function() {
    if (ReferralManager.lastGeneratedLink) {
      ReferralManager.copyToClipboard(ReferralManager.lastGeneratedLink);
      alert('Link copied to clipboard!');
    } else {
      alert('Please generate a link first');
    }
  });
}, false);

实施最佳实践

错误处理

在回调中实施强大的错误处理，以管理网络故障、无效参数或服务器问题。

  • 重试逻辑：针对瞬时网络错误实施指数回退
  • 用户反馈：链接创建失败时显示清晰的错误信息
  • 回退选项：提供其他共享方式（例如，如果短链接创建失败，则共享完整的奇异链接
  • 验证：在调用createReferrerShortLink 之前验证参数，以便及早发现问题

跟踪和分析

利用推荐人信息建立病毒循环并衡量有机增长。

最佳实践：使用与内部用户识别系统一致的推荐人 ID。这样您就可以

  • 将新安装归因于特定的推荐用户
  • 奖励成功推荐的用户
  • 跟踪病毒系数和 K 因子指标
  • 识别最有价值的品牌拥护者

链接过期

在分享策略中规划 30 天的链接生命周期。

重要：短链接在 30 天后失效。对于长期活动或持续分享功能，请定期生成新的短链接，或使用完整的奇异链接作为备用。

常用案例

应用内推荐计划

让用户可以通过个性化推荐链接直接从应用中邀请朋友。

  • 奖励系统：跟踪推荐并奖励成功注册朋友的用户
  • 社交分享：与用于短信、WhatsApp、电子邮件和社交媒体的 Cordova 社交分享插件集成
  • 个人邀请：在共享信息中包含推荐人姓名，实现个性化

用户生成的内容

当用户生成想要与他人分享的内容时，创建可分享链接。

  • 内容归因：跟踪哪些内容推动了最多的应用安装
  • 创作者识别：将新用户归属于内容创作者，实现游戏化
  • 活动标签：根据内容类型或类别添加动态参数

活动邀请

为活动邀请函生成唯一链接，跟踪哪些与会者带来了新用户。

  • 活动背景：在链接参数中包含活动 ID 和详细信息
  • 与会者跟踪：衡量活动之间的病毒传播
  • 网络效应：识别转换率最高的活动

所需的 Cordova 插件

推荐插件

安装这些 Cordova 插件，以增强推荐链接共享体验。

社交分享插件： 

cordova plugin add cordova-plugin-x-socialsharing

剪贴板插件： 

cordova plugin add cordova-plugin-clipboard

注：虽然生成短链接不需要这些插件，但它们通过启用本地共享和剪贴板功能，大大增强了用户体验。