Cordova SDK - SKAdNetwork 지원

팔로우
Avatar
Jared Ornstead
Updated
문서

SKAdNetwork 지원

SKAdNetwork는 iOS 앱 인스톨 캠페인을 위한 Apple의 개인정보 보호 중심의 어트리뷰션 프레임워크입니다. Singular 코르도바 SDK는 대시보드에서 구성된 전환 모델에 따라 자동으로 전환 값을 업데이트하는 관리 모드에서 기본적으로 SKAdNetwork를 활성화합니다.

추가 구성이 필요하지 않습니다: 최신 Cordova SDK를 사용하는 경우, SKAdNetwork가 즉시 작동합니다. 기본 기능을 위해 코드를 변경하거나 추가 설정이 필요하지 않습니다.

SKAN 모드 이해

관리 모드(기본값)

관리 모드에서는 대시보드에서 구성한 전환 모델에 따라 Singular가 자동으로 전환 값 업데이트를 처리합니다. 최소한의 코드가 필요하고 최적의 전환 추적을 제공하므로 대부분의 앱에 권장되는 방식입니다.

  • 자동 업데이트: Singular는 사용자 이벤트 및 구성된 모델을 기반으로 모든 전환 값 업데이트를 관리합니다.
  • 대시보드 구성: 코드 변경 없이 Singular 대시보드에서 전환 모델을 디자인할 수 있습니다.
  • 최적화: Apple의 제약 조건 내에서 전환 가치 업데이트를 극대화하는 Singular의 전문성을 활용하세요.
  • 24시간 창 관리: Singular는 데이터 수집을 극대화하기 위해 SKAdNetwork의 24시간 업데이트 윈도우를 지능적으로 처리합니다.

수동 모드(고급)

수동 모드에서는 전환 값 업데이트를 완벽하게 제어할 수 있으며, SKAN 전환 값 업데이트 시기와 방법을 결정하기 위한 사용자 지정 로직을 구현할 수 있습니다. 관리 모드로는 충족할 수 없는 특정 요구 사항이 있는 경우에만 이 모드를 사용하세요.

고급 기능: 수동 모드를 사용하려면 전환 값 업데이트 기간 및 제한 사항 등 Apple의 SKAdNetwork 제약 조건을 신중하게 구현하고 이해해야 합니다. 대부분의 앱은 관리 모드를 사용해야 합니다.

SKAdNetwork 지원 비활성화하기

SKAdNetwork 추적은 기본적으로 활성화되어 있습니다. 비활성화하려면 SingularConfig 객체를 빌드할 때 skAdNetworkEnabled 구성 속성을 false로 설정하세요.

JavaScript 
// Create configuration
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Disable SKAdNetwork
singularConfig.withSkAdNetworkEnabled(false);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

수동 모드 구성

사용자 지정 전환 값 로직을 구현하려면 수동 모드를 활성화하고 제공된 SDK 메서드를 사용하여 앱의 수명 주기 동안 전환 값을 업데이트하고 모니터링하세요.

수동 모드 활성화

전환 값 업데이트를 제어하려면 SingularConfig 객체를 빌드할 때 manualSkanConversionManagement 구성 속성을 true로 설정합니다.

JavaScript 
// Create configuration with manual SKAN mode
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Enable manual SKAN conversion management
singularConfig.withManualSkanConversionManagement();

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

중요: 수동 업데이트 방법은 manualSkanConversionManagement 이 활성화된 경우에만 작동합니다. 관리 모드가 활성화되어 있으면 수동 업데이트는 무시됩니다.

전환 값 업데이트(SKAN 2.0-3.0)

skanUpdateConversionValue 방법을 사용하여 사용자 지정 로직에 따라 SKAdNetwork 전환 값을 수동으로 업데이트할 수 있습니다. 전환 값은 0에서 63 사이의 정수여야 합니다.

JavaScript 
// Check if running on iOS
if (device.platform === 'iOS') {
  // User completed signup - update conversion value to 7
  function onUserSignUp() {
    // Track the sign-up event
    cordova.plugins.SingularCordovaSdk.event('SignUp');

    // Update SKAN conversion value
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(7, function(success) {
      if (success) {
        console.log('Conversion value updated successfully');
      } else {
        console.warn('Failed to update conversion value');
      }
    });
  }

  // User completed purchase - update based on purchase amount
  function onPurchaseComplete(purchaseAmount) {
    // Track revenue event
    cordova.plugins.SingularCordovaSdk.revenue('USD', purchaseAmount);

    // Calculate conversion value based on purchase tier
    var conversionValue = calculateConversionValue(purchaseAmount);
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(conversionValue, function(success) {
      if (success) {
        console.log('Conversion value updated to: ' + conversionValue);
      }
    });
  }

  function calculateConversionValue(amount) {
    // Your custom logic to determine conversion value
    if (amount >= 100) return 63;  // High value
    if (amount >= 50) return 40;   // Medium value
    if (amount >= 10) return 20;   // Low value
    return 10;                      // Minimal value
  }
}

전환 값 업데이트(SKAN 4.0)

iOS 16.1+의 경우, skanUpdateConversionValues 메서드를 사용하여 미세값, 거친값, 잠금 파라미터로 SKAdNetwork 4.0 전환값을 업데이트할 수 있습니다. 이렇게 하면 전환 값 업데이트를 보다 세밀하게 제어할 수 있습니다.

JavaScript 
// Check if running on iOS
if (device.platform === 'iOS') {
  function updateSKAN4ConversionValue(fineValue, coarseValue, shouldLock) {
    // Map coarse value string to number
    var coarseMap = { low: 0, medium: 1, high: 2 };

    // Update SKAdNetwork 4.0 conversion values
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValues(
      fineValue,
      coarseMap[coarseValue],
      shouldLock,
      function(success) {
        if (success) {
          console.log('SKAN 4.0 updated: fine=' + fineValue + ', coarse=' + coarseValue + ', lock=' + shouldLock);
        }
      }
    );
  }

  // Example: High-value user completes tutorial
  function onTutorialComplete() {
    updateSKAN4ConversionValue(15, 'medium', false);
  }

  // Example: Premium purchase - lock the value
  function onPremiumPurchase() {
    updateSKAN4ConversionValue(63, 'high', true);
  }
}

현재 전환 값 가져오기

Singular SDK가 추적한 현재 전환 값을 가져옵니다. 현재 상태를 기반으로 조건부 로직을 구현하는 데 유용하며 관리 모드와 수동 모드 모두에서 작동합니다.

JavaScript 
// Check if running on iOS
if (device.platform === 'iOS') {
  function checkAndUpdateConversionValue() {
    cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(currentValue) {
      if (currentValue !== null) {
        console.log('Current conversion value: ' + currentValue);

        // Only update if current value is below threshold
        if (currentValue < 30) {
          cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(30, function(success) {
            if (success) {
              console.log('Updated conversion value to 30');
            }
          });
        }
      } else {
        console.warn('Conversion value not available');
      }
    });
  }
}

전환 값 업데이트 모니터링

전환 값이 변경될 때마다 실시간 알림을 받도록 핸들러를 설정하세요. 이를 통해 전환 값 업데이트 및 로그 분석에 대응하거나 다른 앱 동작을 트리거할 수 있습니다.

JavaScript 
// Create configuration with conversion value handler
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Set up conversion value update handler
singularConfig.withConversionValueUpdatedHandler(function(conversionValue) {
  console.log('Conversion value updated to: ' + conversionValue);

  // Log the update to your analytics
  logConversionValueUpdate(conversionValue);

  // Trigger app-specific behavior
  if (conversionValue >= 50) {
    unlockPremiumFeature();
  }
});

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

function logConversionValueUpdate(value) {
  // Your analytics logging logic
  console.log('Analytics: SKAN CV = ' + value);
}

function unlockPremiumFeature() {
  // Your custom logic
  console.log('Premium feature unlocked based on high conversion value');
}

모범 사례: 전환 값 핸들러를 사용하여 앱 전체에서 현재 전환 상태에 대한 동기화된 보기를 유지하세요. 이는 사용자 지정 로직을 디버깅하고 올바르게 작동하는지 확인하는 데 특히 유용합니다.

추가 리소스: SKAdNetwork 설정 및 모범 사례에 대한 종합적인 가이드는 Singular의 SKAdNetwork 가이드를 참조하세요.

앱 트래킹 투명성(ATT) 지원

ATT(앱 추적 투명성)는 기기의 IDFA(광고주 식별자)에 액세스하고 사용자 데이터를 공유하기 전에 사용자 동의를 요구하는 Apple의 개인정보 보호 프레임워크입니다. iOS 어트리뷰션과 사용자 획득 캠페인의 정확도를 극대화하기 위해서는 ATT를 올바르게 구현하는 것이 중요합니다.

어트리뷰션에 ATT가 중요한 이유

iOS 14.5부터 앱은 IDFA에 액세스하기 전에 ATT 프레임워크를 통해 사용자 권한을 요청해야 합니다. IDFA 없이도 핑거프린팅과 확률적 방법을 사용하여 어트리뷰션이 가능하지만, IDFA를 사용하면 어트리뷰션 정확도가 크게 향상되고 결정론적 매칭을 제공합니다.

  • 결정론적 어트리뷰션: IDFA는 광고 노출을 인스톨로 직접 연결하는 정밀한 디바이스 수준의 어트리뷰션을 가능하게 합니다.
  • 애드 네트워크 최적화: 애드 네트워크는 IDFA 액세스를 통해 캠페인을 더 잘 최적화하고 더 정확한 리포팅을 제공할 수 있습니다.
  • 사용자 수준 인사이트: IDFA에 액세스하면 보다 세분화된 사용자 행동 분석 및 코호트 추적이 가능합니다.

권장 사항: Singular는 ATT 프롬프트를 구현하고 사용자 동의를 요청할 것을 강력히 권장합니다. 사용자에게 혜택(맞춤화된 광고, 더 나은 앱 경험)을 설명하여 옵트인 비율을 극대화하세요.

구현 요구 사항

iOS 14.5 이상(iOS 18 포함)의 경우, 추적을 위해 IDFA에 액세스하기 전에 사용자 동의를 요청하기 위해 ATTrackingManager 프레임워크를 사용합니다. Singular SDK는 ATT를 지원하므로 동의 전에 초기화할 수 있고 동의가 승인되거나 시간 초과가 발생할 때까지 이벤트를 지연시킬 수 있습니다.

1단계: ATT 프레임워크 구성 추가하기

사용자 대상 사용 설명으로 Info.plist 파일을 업데이트하여 iOS 앱이 ATT 프레임워크를 지원하도록 구성합니다.

  1. Info.plist에 추가합니다: iOS 프로젝트의 Info.plist 파일( platforms/ios/[YourAppName]/[YourAppName]-Info.plist)에 NSUserTrackingUsageDescription 키를 포함하세요.
  2. 명확한 설명 제공: 앱에 추적 권한이 필요한 이유에 대한 명확한 설명을 추가하여 ATT 프롬프트에서 사용자에게 표시합니다.
Info.plist 
<key>NSUserTrackingUsageDescription</key>
<string>This app uses tracking to provide personalized ads and improve your experience.</string>

중요: 사용 설명은 ATT 프롬프트에서 사용자에게 표시됩니다. 추적을 통해 사용자에게 어떤 이점이 있는지 명확하고 간결하며 솔직하게 설명하세요.

2단계: ATT 지원 플러그인 설치

타사 Cordova 플러그인을 설치하여 앱에서 ATT 기능을 활성화합니다. cordova-plugin-tracking-transparency 플러그인은 Apple의 ATTrackingManager에 자바Script 인터페이스를 제공합니다.

bash 
cordova plugin add cordova-plugin-tracking-transparency

플러그인 참조: 자세한 문서와 사용 예제는 cordova-plugin-tracking-transparency GitHub 리포지토리를 참조하세요.

3단계: SDK 대기 시간 구성하기

waitForTrackingAuthorizationWithTimeoutInterval 속성을 설정하여 초기화하기 전에 사용자의 ATT 응답을 기다리도록 Singular SDK를 구성합니다. 이 지연 시간은 사용자가 권한을 부여하는 경우 IDFA를 캡처할 수 있도록 합니다.

중요: Singular SDK가 첫 세션을 보내기 전에 항상 ATT 동의를 요청하고 IDFA를 검색하세요. 그렇게 하지 않으면 해당 디바이스의 어트리뷰션 데이터에 대한 IDFA가 영구적으로 손실됩니다.

JavaScript 
// Create configuration with ATT wait timeout
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Wait up to 5 minutes for ATT consent
singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

권장 값: 앱에 ATT 프롬프트가 표시되는 경우 시간 제한을 300초(5분)로 설정하세요. 이렇게 하면 프롬프트가 지연되거나 표시되지 않을 경우 사용자 경험이 저하되지 않고 사용자가 프롬프트를 보고 응답할 수 있는 충분한 시간을 확보할 수 있습니다.

4단계: ATT 동의 요청

앱에서 ATT 요청 플로우를 구현하여 사용자 경험의 적절한 시점에 사용자에게 추적 권한을 요청하는 메시지를 표시합니다.

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

function initializeApp() {
  // Check if running on iOS
  if (device.platform === 'iOS') {
    // Request ATT authorization
    cordova.plugins.idfa.requestPermission().then(function(response) {
      var status = response.tracking;
      console.log('ATT Status:', status);
      // Possible values: 'authorized', 'denied', 'restricted', 'notDetermined'

      // Initialize Singular after ATT prompt
      initializeSingular();
    }).catch(function(error) {
      console.error('ATT Error:', error);
      // Initialize Singular even if ATT fails
      initializeSingular();
    });
  } else {
    // Android - initialize immediately
    initializeSingular();
  }
}

function initializeSingular() {
  // Create configuration with wait timeout
  var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    "YOUR_SDK_KEY",
    "YOUR_SDK_SECRET"
  );

  singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
  singularConfig.withLoggingEnabled();

  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(singularConfig);
  console.log('Singular SDK initialized');
}

흐름 이해

초기화 지연을 설정하면 앱 흐름은 다음과 같이 작동합니다:

  1. 세션 녹화가 시작됩니다: 앱이 열리면 Singular SDK가 세션 및 사용자 이벤트를 기록하기 시작하지만 아직 Singular 서버로 전송하지는 않습니다.
  2. 동의를 기다리는 중입니다: SDK는 앱 추적 투명성 동의가 승인/거부되거나 설정된 시간이 경과할 때까지 기다립니다.
  3. 데이터 전송: 동의가 해결되거나 시간 초과가 발생하면 SDK는 세션과 대기 중인 모든 이벤트를 (IDFA를 사용하거나 사용하지 않고) Singular 서버로 전송합니다.
  4. 어트리뷰션이 시작됩니다: 그러면 Singular가 어트리뷰션 프로세스를 시작하고, 사용 가능한 경우 IDFA를 활용합니다.

ATT 시나리오

다음 표에는 가능한 시나리오와 IDFA 사용 가능 여부가 요약되어 있습니다:

시나리오 IDFA 사용 가능성
사용자가 동의 대화 상자를 보고 설정된 시간이 경과하기 전에 동의를 부여합니다. IDFA를 사용할 수 있음
사용자가 동의 대화 상자를 보고 설정된 시간이 경과하기 전에 동의를 거부합니다. IDFA를 사용할 수 없음
설정된 시간이 만료된 후 사용자에게 동의 대화 상자가 표시되고 동의를 허용합니다. 동의를 받은 후에 보고된 사용자 이벤트에 대해서만 IDFA를 사용할 수 있습니다.
설정된 시간이 만료되면 사용자에게 동의 대화 상자가 표시되고 동의를 거부합니다. IDFA를 사용할 수 없는 경우
사용자에게 동의 대화 상자가 표시되고 아무런 조치 없이 앱을 종료한 다음 설정된 시간이 만료된 후 앱을 열고 동의를 부여합니다. 대기 중인 모든 이벤트는 앱이 다시 열릴 때 Singular 서버로 전송됩니다. 이러한 이벤트에는 IDFA를 사용할 수 없습니다. 동의가 부여된 후 추적된 모든 이벤트에는 IDFA가 연결됩니다.
사용자에게 동의 대화 상자가 표시되고 아무 조치 없이 앱을 종료한 후 나중에 앱을 열고 동의를 거부합니다. 대기 중인 모든 이벤트는 앱이 다시 열리면 Singular 서버로 전송됩니다. 이러한 이벤트 또는 이후 추적된 이벤트에 대해서는 IDFA를 사용할 수 없습니다.

ATT 모범 사례

  • 사전 프롬프트 메시지: 사용자에게 추적 권한이 필요한 이유와 이를 통해 얻을 수 있는 혜택(더 나은 광고, 향상된 경험)을 설명하는 사전 ATT 화면을 표시하세요. 이를 통해 옵트인 비율을 크게 높일 수 있습니다.
  • 타이밍이 중요합니다: 앱을 처음 실행할 때 바로 표시하지 말고 앱 흐름의 자연스러운 순간에 ATT 프롬프트를 표시하세요. 사용자가 먼저 앱을 경험하게 하여 신뢰를 쌓을 수 있도록 하세요.
  • 시간 제한 구성: waitForTrackingAuthorizationWithTimeoutInterval 을 30-300초로 설정합니다. 시간 초과 후, Singular는 SKAN 4.0 어트리뷰션을 진행합니다(IDFA 없음).
  • 철저하게 테스트하세요: 승인 및 거부 시나리오를 모두 테스트하여 사용자의 선택에 관계없이 앱이 올바르게 작동하는지 확인하세요.
  • 사용자의 선택권을 존중하세요: 추적을 거부한 사용자에게 반복적으로 메시지를 표시하거나 옵트인하도록 압력을 가하는 공격적인 메시지를 표시하지 마세요.
  • 오류 처리: restricted (예: 자녀 보호 기능) 또는 notDetermined 상태의 추적 상태를 확인하고 분석을 위해 로그를 기록합니다.
  • SKAN 4.0 연동: 전환 값 업데이트가 ATT 동의와 일치하는지 확인하여 SKAN 포스트백을 최적화합니다(예: 이벤트를 0-63 값에 매핑하기 위해 Singular의 대시보드 사용).

앱 스토어 검토: ATT를 제대로 구현하지 않거나 프레임워크를 우회하려는 앱은 앱 스토어 검토 과정에서 거부될 수 있습니다. 구현이 Apple의 가이드라인을 따르고 사용자의 개인정보 보호 선택권을 존중하는지 확인하세요.

추가 리소스