ドキュメント

短いリファラーリンクの作成

ユーザー間のアトリビューションを可能にし、オーガニックな紹介からのアプリのインストールを追跡する、共有可能な短いリファラーリンクを生成します。

バージョン要件この機能を使用するには、SDKバージョン3.1.8以降が必要です。短いリンクは、作成後30日間有効です。

概要

ショートリファラーリンクとは

ショートリンクは、長い、パラメータいっぱいのシンギュラーリンクを、SMS、ソーシャルメディア、アプリ内招待で共有するのに便利な、コンパクトで安全なURLに変換します。

ショートリンクを動的に作成することで、ユーザーがお友達と共有し、アプリのダウンロードや使用を招待することができます。各ショートリンクは参照ユーザーを追跡するので、バイラルの成長を測定し、新規インストールを特定の支持者に帰属させることができます。

実装要件

必要なコンポーネント

ショートリファラーリンクを作成する前に、これらの要素を集めてください：

単一リンク：アプリのダウンロードにユーザーを誘導するベーストラッキングリンク。設定方法については、Singular Links FAQを参照してください。
動的パラメータ：リンクにコンテキストを追加するオプションのカスタムパラメータ。トラッキングリンクパラメータで利用可能なオプションを見る
リファラー情報：リンクを共有するユーザーの名前と ID を入力して、新規インストールのリファラーへの帰属を可能にします。

SDKメソッド

CreateReferrerShortLink

カスタムパラメータと成功およびエラー状態のコールバックハンドラを使用して、短いリファラーリンクを生成します。

メソッドのシグネチャ

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

パラメータ：

baseLink：元の Singular トラッキングリンクの URL。
referrerName：参照元ユーザーの表示名
referrerId：参照元ユーザーの一意な識別子
passthroughParams：追加の動的パラメータを含むオブジェクト (オプション。空のオブジェクトを渡すか、何もない場合は null を渡します)
resultHandler： onSuccessおよびonError コールバック関数を含むオブジェクト。

メソッドの完全なドキュメントについては、createReferrerShortLink のリファレンスを参照ください。

基本的な使用例

カスタムパラメータを指定してショートリンクを作成し、成功コールバックで共有ロジックを実装します。

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);
  }
}

高度な実装

再試行ロジック、ロード状態、クリップボードフォールバックを含む完全な紹介システムを実装します。

// 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日で失効します。長期的なキャンペーンや永続的な共有機能の場合は、定期的に新しいショートリンクを生成するか、予備として完全なシンギュラーリンクを使用してください。

一般的な使用例

アプリ内紹介プログラム

パーソナライズされた紹介リンクを使って、ユーザーがアプリから直接友達を招待できるようにします。

報酬システム：紹介者を追跡し、友達登録に成功したユーザーに報酬を与えます。
ソーシャル共有：SMS、WhatsApp、メール、ソーシャルメディア用の Cordova ソーシャル共有プラグインと統合します。
パーソナライズ招待:パーソナライズするために、共有メッセージに紹介者の名前を含めることができます。

ユーザー生成コンテンツ

ユーザーが他のユーザーと共有したいコンテンツを作成した際に、共有可能なリンクを作成します。

コンテンツのアトリビューション：どのコンテンツが最もアプリのインストールを促進したかを追跡
クリエイターの認識：新規ユーザーをコンテンツ作成者に帰属させ、ゲーミフィケーションを実現します。
キャンペーンタグ付け：コンテンツの種類やカテゴリーに基づいた動的なパラメータを追加

イベント招待

どの出席者が新規ユーザーを連れてきたかを追跡するイベント招待用のユニークなリンクを生成します。

イベントコンテキスト：リンクパラメータにイベントIDと詳細を含める
参加者のトラッキング：イベントからイベントへのバイラル拡散を測定
ネットワーク効果：コンバージョン率の高いイベントを特定

必要な Cordova プラグイン

推奨プラグイン

これらの Cordova プラグインをインストールすることで、紹介リンクの共有体験を向上させることができます。

ソーシャル共有プラグイン

cordova plugin add cordova-plugin-x-socialsharing

クリップボード・プラグイン

cordova plugin add cordova-plugin-clipboard

注：これらのプラグインはショートリンクの生成には必須ではありませんが、ネイティブの共有とクリップボード機能を有効にすることで、ユーザーエクスペリエンスを大幅に向上させます。

Cordova SDK - リファラーショートリンクのサポート

短いリファラーリンクの作成

概要

ショートリファラーリンクとは

実装要件

必要なコンポーネント

SDKメソッド

CreateReferrerShortLink

基本的な使用例

高度な実装

実装のベストプラクティス

エラー処理

トラッキングと分析

リンクの有効期限

一般的な使用例

アプリ内紹介プログラム

ユーザー生成コンテンツ

イベント招待

必要な Cordova プラグイン

推奨プラグイン