코르도바 SDK - 리퍼러 쇼트 링크 지원

팔로우
Avatar
Jared Ornstead
Updated
문서

짧은 리퍼러 링크 생성하기

사용자 간 어트리뷰션을 가능하게 하는 공유 가능한 짧은 리퍼러 링크를 생성하고 오가닉 추천을 통해 앱 설치를 추적하세요.

버전 요구 사항: 이 기능을 사용하려면 SDK 버전 3.1.8 이상이 필요합니다. 짧은 링크는 생성 후 30일 동안 활성 상태로 유지됩니다.

개요

짧은 리퍼러 링크란?

짧은 링크는 매개변수로 가득 찬 긴 Singular 링크를 SMS, 소셜 미디어 또는 인앱 초대를 통해 공유하기 편리한 작고 안전한 URL로 변환합니다.

짧은 링크를 동적으로 생성하여 사용자가 친구와 공유하여 앱을 다운로드하고 사용하도록 초대할 수 있습니다. 각 짧은 링크는 추천한 사용자를 추적하여 바이럴 성장을 측정하고 특정 지지자에게 신규 설치를 할당할 수 있습니다.

구현 요구 사항

필수 구성 요소

짧은 리퍼러 링크를 만들기 전에 다음 요소를 수집하세요:

  • Singular 링크: 사용자를 앱 다운로드로 안내하는 기본 추적 링크입니다. 설정 지침은 Singular 링크 FAQ를참조하세요.
  • 동적 파라미터: 링크에 컨텍스트를 추가하기 위한 선택적 사용자 지정 매개변수입니다. 추적 링크 파라미터에서사용 가능한 옵션 보기
  • 리퍼러 정보: 링크를 공유하는 사용자의 이름과 ID로, 신규 인스톨을 리퍼러에게 어트리뷰션할 수 있도록 합니다.

SDK 메서드

리퍼러 쇼트링크 생성

사용자 지정 파라미터와 성공 및 오류 상태에 대한 콜백 핸들러가 포함된 짧은 리퍼러 링크를 생성합니다.

메서드 서명: 

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

파라미터:

  • baseLink: 원본 Singular 추적 링크 URL
  • referrerName: 추천 사용자의 표시 이름
  • referrerId: 추천 사용자의 고유 식별자
  • 패스스루 파라미터: 추가 동적 매개변수가 포함된 객체(선택 사항, 빈 객체를 전달하거나 없는 경우 null)
  • 결과 핸들러: 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);

구현 모범 사례

오류 처리

콜백에서 강력한 오류 처리를 구현하여 네트워크 장애, 잘못된 매개변수 또는 서버 문제를 관리하세요.

  • 재시도 로직: 일시적인 네트워크 오류에 대한 지수 백오프를 구현하세요.
  • 사용자 피드백: 링크 생성 실패 시 명확한 오류 메시지 표시
  • 폴백 옵션: 대체 공유 방법 제공(예: 짧은 링크 생성에 실패한 경우 전체 Singular 링크 공유)
  • 유효성 검사: createReferrerShortLink 으로 호출하기 전에 매개변수를 확인하여 문제를 조기에 포착하세요.

추적 및 분석

리퍼러 정보를 활용하여 바이럴 루프를 구축하고 유기적 성장을 측정하세요.

모범 사례: 내부 사용자 식별 시스템과 일치하는 일관된 리퍼러 ID를 사용하세요. 이를 통해 다음을 수행할 수 있습니다:

  • 특정 추천 사용자에게 신규 설치 속성 부여
  • 성공적인 추천에 대해 사용자에게 보상 제공
  • 바이럴 계수 및 K-요인 지표 추적
  • 가장 가치 있는 브랜드 옹호자 식별

링크 만료

공유 전략에서 30일의 링크 수명 주기를 계획하세요.

중요: 짧은 링크는 30일 후에 만료됩니다. 장기 캠페인 또는 지속적인 공유 기능의 경우 주기적으로 새로운 짧은 링크를 생성하거나 전체 Singular 링크를 대체로 사용하세요.

일반적인 사용 사례

인앱 추천 프로그램

맞춤화된 추천 링크를 통해 사용자가 앱에서 직접 친구를 초대할 수 있도록 하세요.

  • 보상 시스템: 추천을 추적하고 성공적인 친구 가입에 대해 사용자에게 보상을 제공하세요.
  • 소셜 공유: SMS, WhatsApp, 이메일, 소셜 미디어를 위한 Cordova 소셜 공유 플러그인과 연동하세요.
  • 개인 초대: 개인화를 위해 공유 메시지에 추천인 이름을 포함하세요.

사용자 생성 콘텐츠

사용자가 다른 사람들과 공유하고 싶은 콘텐츠를 생성할 때 공유 가능한 링크를 생성하세요.

  • 콘텐츠 어트리뷰션: 어떤 콘텐츠가 가장 많은 앱 설치를 유도하는지 추적하세요.
  • 크리에이터 인식: 게임화를 위해 신규 사용자를 콘텐츠 크리에이터에게 어트리뷰션하세요.
  • 캠페인 태깅: 콘텐츠 유형 또는 카테고리에 따라 동적 파라미터 추가

이벤트 초대

이벤트 초대를 위한 고유 링크를 생성하여 어떤 참석자가 신규 사용자를 데려왔는지 추적할 수 있습니다.

  • 이벤트 컨텍스트: 링크 매개변수에 이벤트 ID 및 세부 정보를 포함하세요.
  • 참석자 추적: 이벤트에서 이벤트로의 바이럴 확산 측정
  • 네트워크 효과: 전환율이 가장 높은 이벤트 식별

필수 Cordova 플러그인

권장 플러그인

추천 링크 공유 환경을 개선하려면 다음 Cordova 플러그인을 설치하세요.

소셜 공유 플러그인: 

cordova plugin add cordova-plugin-x-socialsharing

클립보드 플러그인: 

cordova plugin add cordova-plugin-clipboard

참고: 이러한 플러그인은 짧은 링크를 생성하는 데 반드시 필요한 것은 아니지만 기본 공유 및 클립보드 기능을 활성화하여 사용자 경험을 크게 향상시킵니다.