React Native SDK - リファラー・ショートリンクのサポート

ドキュメント

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

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

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

概要

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

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

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


実装要件

必要なコンポーネント

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

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

SDKメソッド

CreateReferrerShortLink

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

メソッドのシグネチャ

static createReferrerShortLink(
    baseLink: string,
    referrerName: string,
    referrerId: string,
    passthroughParams: Record<string, any>,
    completionHandler: (data: string | null, error?: string) => void
): void

パラメータ

  • baseLink:元の Singular トラッキングリンクの URL。
  • referrerName:参照元ユーザーの表示名
  • referrerId:参照元ユーザーの一意な識別子
  • passthroughParams:追加の動的パラメータを含むオブジェクト (オプション。空のオブジェクトを渡すか、何もない場合はNULLを渡す)
  • completionHandler:パラメータを含むコールバック関数(shortLinkURL: string | null, error?: string)

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


基本的な使用例

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

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import React from 'react';
import { View, Button, Alert, Share } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';

export default function ReferralScreen() {
  const handleShareReferral = () => {
    // Create custom parameters for the link
    const parameters = {
      channel: 'sms',
      campaign_id: 'summer_promo_2025',
      referral_type: 'friend_invite'
    };

    // Generate the short referrer link
    NativeSingular.createReferrerShortLink(
      'https://sample.sng.link/D52wc/cuvk?pcn=test',  // Base Singular Link
      'John Doe',                                      // Referrer name
      'user_12345',                                    // Referrer ID
      parameters,                                      // Custom parameters
      (shortLink, error) => {
        if (error) {
          // Error occurred during link creation
          console.error('Error creating short link:', error);
          Alert.alert('Error', 'Failed to create share link. Please try again.');
        } else if (shortLink) {
          // Success - short link was created
          console.log('Generated short link:', shortLink);

          // Share the link using React Native's Share API
          shareLink(shortLink);
        }
      }
    );
  };

  const shareLink = async (shortLink) => {
    try {
      const result = await Share.share({
        message: `Join me on this awesome app! ${shortLink}`,
        url: shortLink // iOS only
      });

      if (result.action === Share.sharedAction) {
        if (result.activityType) {
          console.log('Shared with activity type:', result.activityType);
        } else {
          console.log('Link shared successfully');
        }
      } else if (result.action === Share.dismissedAction) {
        console.log('Share dismissed');
      }
    } catch (error) {
      console.error('Error sharing link:', error);
      Alert.alert('Error', 'Failed to share link');
    }
  };

  return (
    <View>
      <Button title="Share Referral Link" onPress={handleShareReferral} />
    </View>
  );
}

高度な実装

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

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useState } from 'react';
import { View, Button, Alert, ActivityIndicator } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import Clipboard from '@react-native-clipboard/clipboard';

export default function ReferralManager({ userId, userName, baseLink }) {
  const [isGenerating, setIsGenerating] = useState(false);
  const [lastGeneratedLink, setLastGeneratedLink] = useState(null);

  const generateShortLink = (retryCount = 0) => {
    return new Promise((resolve, reject) => {
      const parameters = {
        channel: 'in_app',
        campaign_id: 'organic_referral',
        user_tier: 'premium',
        referral_timestamp: Date.now().toString()
      };

      NativeSingular.createReferrerShortLink(
        baseLink,
        userName,
        userId,
        parameters,
        (shortLink, error) => {
          if (error) {
            // Retry logic with exponential backoff
            if (retryCount < 3) {
              const delay = Math.pow(2, retryCount) * 1000; // 1s, 2s, 4s
              console.log(`Retrying in ${delay}ms... (Attempt ${retryCount + 1}/3)`);

              setTimeout(() => {
                generateShortLink(retryCount + 1)
                  .then(resolve)
                  .catch(reject);
              }, delay);
            } else {
              reject(new Error(error));
            }
          } else if (shortLink) {
            setLastGeneratedLink(shortLink);
            resolve(shortLink);
          } else {
            reject(new Error('Unknown error occurred'));
          }
        }
      );
    });
  };

  const handleShare = async () => {
    setIsGenerating(true);

    try {
      const shortLink = await generateShortLink();
      console.log('Short link generated:', shortLink);

      // Attempt to share
      const { Share } = require('react-native');
      const result = await Share.share({
        message: `${userName} invited you to join! ${shortLink}`,
        url: shortLink
      });

      if (result.action === Share.sharedAction) {
        console.log('Link shared successfully');
        // Track share event
        NativeSingular.event('referral_link_shared');
      }
    } catch (error) {
      console.error('Error in share flow:', error);

      // Fallback: Copy to clipboard if available
      if (lastGeneratedLink) {
        Clipboard.setString(lastGeneratedLink);
        Alert.alert(
          'Link Copied',
          'Failed to share, but the referral link has been copied to your clipboard!',
          [{ text: 'OK' }]
        );
      } else {
        Alert.alert(
          'Error',
          'Failed to generate referral link. Please check your connection and try again.',
          [{ text: 'OK' }]
        );
      }
    } finally {
      setIsGenerating(false);
    }
  };

  const copyToClipboard = () => {
    if (lastGeneratedLink) {
      Clipboard.setString(lastGeneratedLink);
      Alert.alert('Copied!', 'Referral link copied to clipboard');
    } else {
      Alert.alert('No Link', 'Please generate a link first');
    }
  };

  return (
    <View>
      {isGenerating ? (
        <ActivityIndicator size="large" />
      ) : (
        <>
          <Button 
            title="Share Referral Link" 
            onPress={handleShare}
            disabled={isGenerating}
          />
          {lastGeneratedLink && (
            <Button 
              title="Copy Link" 
              onPress={copyToClipboard}
            />
          )}
        </>
      )}
    </View>
  );
}

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

エラー処理

ネットワーク障害、無効なパラメータ、またはサーバーの問題を管理するために、コールバックに堅牢なエラー処理を実装します。

  • 再試行ロジック:一過性のネットワークエラーに対する指数関数的バックオフを実装します。
  • ユーザー・フィードバック:リンク作成失敗時に明確なエラーメッセージを表示
  • フォールバック・オプション:代替共有方法の提供(例:短いリンク作成に失敗した場合、完全なシンギュラーリンクを共有する
  • 検証:問題を早期に発見するために、createReferrerShortLink を呼び出す前にパラメータを検証します。

トラッキングと分析

リファラー情報を活用して、バイラルループを構築し、オーガニックな成長を測定する。

ベストプラクティス社内のユーザー識別システムと一致する一貫したリファラーIDを使用する。これにより、次のことが可能になります:

  • 新規インストールを特定の参照ユーザーに帰属させる。
  • 紹介に成功したユーザーに報酬を与える
  • バイラル係数とKファクターメトリクスの追跡
  • 最も価値のあるブランド支持者を特定

リンクの有効期限

共有戦略において、30日間のリンクライフサイクルを計画する。

重要:ショートリンクは30日で失効します。長期的なキャンペーンや持続的な共有機能の場合は、定期的に新しいショートリンクを生成するか、予備として完全なシンギュラーリンクを使用してください。


一般的な使用例

アプリ内紹介プログラム

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

  • 報酬システム:紹介者を追跡し、友達登録に成功したユーザーに報酬を与えます。
  • ソーシャル共有:SMS、WhatsApp、Eメール、ソーシャルメディア用のReact Native Share APIと統合します。
  • 個人的な招待:パーソナライゼーションのために、共有メッセージに紹介者の名前を含めます。

ユーザー生成コンテンツ

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

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

イベント招待

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

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