언리얼 엔진 SDK - 메서드 레퍼런스

팔로우
Avatar
Jared Ornstead
Updated

언리얼 엔진 SDK - 메서드 레퍼런스

Singular 언리얼 엔진 SDK는 언리얼 엔진 애플리케이션을 위한 포괄적인 트래킹 및 어트리뷰션 기능을 제공합니다. 이 레퍼런스에서는 사용 가능한 모든 SDK 메서드를 시그니처 및 사용 예제와 함께 설명합니다.

리퍼러 쇼트링크 생성

리퍼러 쇼트 링크 생성

사용자 간 어트리뷰션 및 바이럴 성장 캠페인을 추적하기 위해 공유할 수 있는 짧은 Singular 링크를 생성합니다.

서명

C++ 
static void CreateReferrerShortLink(
    FString baseLink,
    FString referrerName,
    FString referrerId,
    TMap<FString, FString> args
);

사용 예시

C++ 
// Create a referrer short link
FString BaseLink = TEXT("https://example.sng.link/abc123");
FString ReferrerName = TEXT("John Doe");
FString ReferrerId = TEXT("user_12345");

TMap<FString, FString> PassthroughParams;
PassthroughParams.Add(TEXT("campaign"), TEXT("summer_promo"));
PassthroughParams.Add(TEXT("level"), TEXT("5"));

USingularSDKBPLibrary::CreateReferrerShortLink(
    BaseLink,
    ReferrerName,
    ReferrerId,
    PassthroughParams
);

DeviceAttributionCallbackHandler

디바이스 어트리뷰션 콜백

BETA 기능: 이 콜백은 일반 제공 기능이 아니며 Singular이 고객님의 계정에 대해 활성화해야 합니다. 활성화되지 않은 경우 델리게이트가 전혀 호출되지 않습니다. 활성화를 요청하려면 고객 성공 매니저에게 문의하세요.

설치 후 사용자의 첫 세션 중에 Singular의 어트리뷰션 결과를 브로드캐스트하는 Blueprint 할당 가능 멀티캐스트 델리게이트입니다. Android와 iOS 모두에서 사용할 수 있습니다.

페이로드: SingularDeviceAttributionData는 문자열 대 문자열 맵이므로 모든 값이 텍스트로 전달됩니다. Singular이 반환하는 숫자 필드는 델리게이트 호출 전에 변환됩니다.

값이 있는 필드만 포함되므로 값을 읽기 전에 키의 존재 여부를 확인하세요. 대부분의 설치에서는 일부 필드만 반환되며, 어떤 필드가 포함되는지는 Singular이 매칭한 터치포인트에 따라 달라집니다.

키 유형 참고
network FString 콜백이 호출될 때 항상 포함됩니다. 터치포인트가 매칭되지 않은 경우 "Organic"입니다.
campaign_id FString 터치포인트가 제공하는 경우 포함됩니다.
campaign_name FString 터치포인트가 제공하는 경우 포함됩니다.
subcampaign_id FString 터치포인트가 제공하는 경우 포함됩니다. 모든 소스에서 제공되지는 않습니다.
subcampaign_name FString 터치포인트가 제공하는 경우 포함됩니다. 모든 소스에서 제공되지는 않습니다.
creative_id FString 터치포인트가 제공하는 경우 포함됩니다. 모든 소스에서 제공되지는 않습니다.
creative_name FString 터치포인트가 제공하는 경우 포함됩니다. 모든 소스에서 제공되지는 않습니다.
passthrough FString 링크에 패스스루 값이 첨부된 경우 포함됩니다.
match_type FString 터치포인트가 제공하는 경우 포함됩니다. 값 목록이 필요하면 Singular에 문의하세요.
click_timestamp FString 터치포인트가 제공하는 경우 포함됩니다. epoch 마이크로초이며, 초 단위로 변환하려면 1,000,000으로 나누세요.

시그니처

C++
// Blueprint-assignable delegate on USingularDelegates
UPROPERTY(BlueprintAssignable, Category = "Singular-SDK")
FDeviceAttributionCallbackHandler DeviceAttributionCallbackHandler;

// Your handler must match this signature
UFUNCTION()
void OnDeviceAttribution(const FSingularDeviceAttributionCallbackHandler& AttributionData);

사용 예시

C++
// Bind the delegate, for example in BeginPlay
void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();

    USingularDelegates* Delegates = FindComponentByClass<USingularDelegates>();
    if (Delegates)
    {
        Delegates->DeviceAttributionCallbackHandler.AddDynamic(
            this, &AMyGameMode::OnDeviceAttribution);
    }
}

// Read the attribution data
void AMyGameMode::OnDeviceAttribution(const FSingularDeviceAttributionCallbackHandler& AttributionData)
{
    for (const TPair<FString, FString>& Pair : AttributionData.SingularDeviceAttributionData)
    {
        UE_LOG(LogTemp, Log, TEXT("%s = %s"), *Pair.Key, *Pair.Value);
    }
}

GetLimitDataSharing

데이터 공유 제한 상태 조회

개인정보 보호 규정 준수를 위해 현재 데이터 공유 제한 상태를 확인합니다.

서명

C++ 
static bool GetLimitDataSharing();

사용 예

C++ 
// Check if data sharing is limited
bool IsLimited = USingularSDKBPLibrary::GetLimitDataSharing();

if (IsLimited)
{
    UE_LOG(LogTemp, Log, TEXT("Data sharing is currently limited"));
}
else
{
    UE_LOG(LogTemp, Log, TEXT("Data sharing is enabled"));
}

초기화

Singular SDK 초기화

API 자격 증명, 추적 설정, 개인정보 보호 옵션을 포함한 구성 매개변수로 Singular SDK를 초기화합니다.

서명

C++ 
static bool Initialize(
    FString apiKey,
    FString apiSecret,
    int sessionTimeout = 60,
    FString customUserId = TEXT(""),
    bool skAdNetworkEnabled = true,
    bool manualSkanConversionManagement = false,
    int waitForTrackingAuthorizationWithTimeoutInterval = 0,
    bool oaidCollection = false,
    bool enableLogging = false,
    int logLevel = 0,
    bool clipboardAttribution = false,
    FString facebookAppId = TEXT(""),
    FString customSdid = TEXT("")
);

사용 예시

C++ 
// Initialize SDK with required parameters
FString ApiKey = TEXT("SDK KEY");
FString ApiSecret = TEXT("SDK SECRET");

bool Success = USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                    // Session timeout in seconds
    TEXT(""),             // Custom user ID (optional)
    true,                 // SKAdNetwork enabled
    false,                // Manual SKAN conversion management
    0,                    // Wait for tracking authorization timeout
    false,                // OAID collection
    true,                 // Enable logging for debugging
    3,                    // Log level (0-5)
    false,                // Clipboard attribution
    TEXT(""),             // Facebook App ID (optional)
    TEXT("")              // Custom SDID (optional)
);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("Singular SDK initialized successfully"));
}
else
{
    UE_LOG(LogTemp, Error, TEXT("Failed to initialize Singular SDK"));
}

IsAllTrackingStopped

모든 추적이 중지되었는지 확인

개인정보 보호 규정 준수 또는 사용자 기본 설정을 위해 모든 추적이 중지되었는지 여부를 확인합니다.

서명

C++ 
static bool IsAllTrackingStopped();

사용 예

C++ 
// Check tracking status
bool IsTrackingStopped = USingularSDKBPLibrary::IsAllTrackingStopped();

if (IsTrackingStopped)
{
    UE_LOG(LogTemp, Warning, TEXT("Tracking is currently stopped"));
    // Update UI to reflect tracking status
}
else
{
    UE_LOG(LogTemp, Log, TEXT("Tracking is active"));
}

데이터 공유 제한

데이터 공유 제한 설정

GDPR 및 CCPA와 같은 개인정보 보호 규정 준수를 위해 사용자 데이터를 제3자와 공유할지 여부를 제어합니다.

서명

C++ 
static void LimitDataSharing(bool shouldLimitDataSharing);

사용 예시

C++ 
// Limit data sharing when user opts out
USingularSDKBPLibrary::LimitDataSharing(true);
UE_LOG(LogTemp, Log, TEXT("Data sharing has been limited"));

// Enable data sharing when user opts in
USingularSDKBPLibrary::LimitDataSharing(false);
UE_LOG(LogTemp, Log, TEXT("Data sharing has been enabled"));

ResumeAllTracking

모든 추적 재개

추적이 중지된 후 다시 활성화하여 SDK가 데이터 수집 및 이벤트 보고를 재개할 수 있도록 합니다.

서명

C++ 
static void ResumeAllTracking();

사용 예시

C++ 
// Resume tracking when user grants consent
USingularSDKBPLibrary::ResumeAllTracking();
UE_LOG(LogTemp, Log, TEXT("Tracking has been resumed"));

SendEvent

사용자 지정 이벤트 보내기

사용자 지정 이벤트를 이름으로 추적하여 애플리케이션 내에서 사용자 행동과 참여를 측정합니다.

서명

C++ 
static void SendEvent(FString eventName);

사용 예시

C++ 
// Track level completion event
USingularSDKBPLibrary::SendEvent(TEXT("level_completed"));

// Track tutorial start
USingularSDKBPLibrary::SendEvent(TEXT("tutorial_start"));

// Track user achievement
USingularSDKBPLibrary::SendEvent(TEXT("achievement_unlocked"));

SendEventWithArgs

속성과 함께 사용자 지정 이벤트 보내기

추가 속성이 있는 사용자 지정 이벤트를 추적하여 사용자 행동에 대한 자세한 컨텍스트를 제공합니다.

서명

C++ 
static void SendEventWithArgs(
    FString eventName,
    TMap<FString, FString> args
);

사용 예시

C++ 
// Track level completion with attributes
TMap<FString, FString> LevelAttributes;
LevelAttributes.Add(TEXT("level_name"), TEXT("Dark Forest"));
LevelAttributes.Add(TEXT("level_number"), TEXT("5"));
LevelAttributes.Add(TEXT("time_spent"), TEXT("245"));
LevelAttributes.Add(TEXT("score"), TEXT("8500"));

USingularSDKBPLibrary::SendEventWithArgs(
    TEXT("level_completed"),
    LevelAttributes
);

// Track item purchase with details
TMap<FString, FString> PurchaseAttributes;
PurchaseAttributes.Add(TEXT("item_id"), TEXT("sword_legendary"));
PurchaseAttributes.Add(TEXT("item_category"), TEXT("weapon"));
PurchaseAttributes.Add(TEXT("item_rarity"), TEXT("legendary"));

USingularSDKBPLibrary::SendEventWithArgs(
    TEXT("item_purchased"),
    PurchaseAttributes
);

SendRevenue

구매 이벤트 보내기

구매 창출 이벤트를 통화와 금액으로 추적하여 구매화 성과를 측정하세요.

서명

C++ 
static void SendRevenue(
    FString eventName,
    FString currency,
    float amount
);

사용 예시

C++ 
// Track in-app purchase revenue
USingularSDKBPLibrary::SendRevenue(
    TEXT("coin_pack_purchase"),
    TEXT("USD"),
    4.99f
);

// Track subscription purchase
USingularSDKBPLibrary::SendRevenue(
    TEXT("premium_subscription"),
    TEXT("EUR"),
    9.99f
);

SendRevenueWithArgs

속성과 함께 구매 이벤트 보내기

추가 속성으로 구매을 추적하여 거래에 대한 자세한 정보를 제공합니다.

서명

C++ 
static void SendRevenueWithArgs(
    FString eventName,
    FString currency,
    float amount,
    TMap<FString, FString> args
);

사용 예시

C++ 
// Track revenue with transaction details
TMap<FString, FString> TransactionAttributes;
TransactionAttributes.Add(TEXT("product_id"), TEXT("com.game.coins.large"));
TransactionAttributes.Add(TEXT("product_name"), TEXT("Large Coin Pack"));
TransactionAttributes.Add(TEXT("quantity"), TEXT("1"));
TransactionAttributes.Add(TEXT("payment_method"), TEXT("credit_card"));

USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("iap_purchase"),
    TEXT("USD"),
    9.99f,
    TransactionAttributes
);

SetCustomUserId

사용자 지정 사용자 ID 설정

사용자 지정 사용자 식별자를 할당하여 자체 ID 시스템을 사용하여 여러 디바이스 및 세션에서 사용자를 추적하세요.

서명

C++ 
static void SetCustomUserId(FString customUserId);

사용 예

C++ 
// Set custom user ID after login
FString UserId = TEXT("user_abc123xyz");
USingularSDKBPLibrary::SetCustomUserId(UserId);
UE_LOG(LogTemp, Log, TEXT("Custom user ID set: %s"), *UserId);

SetUninstallToken

제거 추적 토큰 설정

푸시 알림 토큰을 등록하여 사용자 리텐션 측정을 위한 제거 추적을 활성화합니다.

서명

C++ 
static void SetUninstallToken(FString token);

사용 예시

C++ 
// Set push notification token for uninstall tracking
FString PushToken = TEXT("abc123def456...");
USingularSDKBPLibrary::SetUninstallToken(PushToken);
UE_LOG(LogTemp, Log, TEXT("Uninstall token registered"));

SkanGetConversionValue

SKAdNetwork 전환 가치 가져오기

iOS 앱의 현재 SKAdNetwork 전환 값을 가져옵니다(iOS만 해당).

서명

C++ 
static int SkanGetConversionValue();

사용 예시

C++ 
// Get current SKAdNetwork conversion value (iOS only)
int ConversionValue = USingularSDKBPLibrary::SkanGetConversionValue();
UE_LOG(LogTemp, Log, TEXT("Current conversion value: %d"), ConversionValue);

SkanRegisterAppForAdNetworkAttribution

애드 네트워크 어트리뷰션을 위한 앱 등록

어트리뷰션 추적을 위해 앱을 Apple의 SKAdNetwork 프레임워크에 등록합니다(iOS만 해당).

서명

C++ 
static void SkanRegisterAppForAdNetworkAttribution();

사용 예시

C++ 
// Register for SKAdNetwork attribution (iOS only)
USingularSDKBPLibrary::SkanRegisterAppForAdNetworkAttribution();
UE_LOG(LogTemp, Log, TEXT("Registered for SKAdNetwork attribution"));

SkanUpdateConversionValue

SKAdNetwork 전환 값 업데이트

사용자 인게이지먼트와 구매화를 반영하도록 SKAdNetwork 전환 값을 업데이트합니다(iOS만 해당).

서명

C++ 
static bool SkanUpdateConversionValue(int conversionValue);

사용 예시

C++ 
// Update conversion value based on user actions (iOS only)
int NewValue = 10;
bool Success = USingularSDKBPLibrary::SkanUpdateConversionValue(NewValue);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("Conversion value updated to: %d"), NewValue);
}
else
{
    UE_LOG(LogTemp, Warning, TEXT("Failed to update conversion value"));
}

SkanUpdateConversionValues

세분화된 값과 거친 값으로 SKAdNetwork 전환 값 업데이트하기

iOS 16.1+에 대해 세분화된 전환 값, 거친 값 및 잠금 상태로 SKAdNetwork를 업데이트합니다(iOS 전용).

서명

C++ 
static void SkanUpdateConversionValues(
    int conversionValue,
    int coarse,
    bool lock
);

사용 예시

C++ 
// Update conversion values with fine and coarse values (iOS 16.1+)
int FineValue = 25;
int CoarseValue = 1;  // 0 = low, 1 = medium, 2 = high
bool Lock = false;    // Set to true to prevent further updates

USingularSDKBPLibrary::SkanUpdateConversionValues(FineValue, CoarseValue, Lock);
UE_LOG(LogTemp, Log, TEXT("Updated conversion values: fine=%d, coarse=%d"), FineValue, CoarseValue);

StopAllTracking

모든 추적 중지

사용자 개인정보 보호 기본 설정 또는 규제 요구사항을 준수하기 위해 모든 SDK 추적 활동을 완전히 중지합니다.

서명

C++ 
static void StopAllTracking();

사용 예시

C++ 
// Stop tracking when user withdraws consent
USingularSDKBPLibrary::StopAllTracking();
UE_LOG(LogTemp, Warning, TEXT("All tracking has been stopped"));

TrackingOptIn

추적 옵트인 기록

사용자가 GDPR 준수를 위해 추적에 명시적으로 동의했음을 Singular에 알립니다.

서명

C++ 
static void TrackingOptIn();

사용 예시

C++ 
// Record user opt-in for GDPR compliance
USingularSDKBPLibrary::TrackingOptIn();
UE_LOG(LogTemp, Log, TEXT("User has opted in to tracking"));

TrackingUnder13

사용자를 13세 미만으로 표시

COPPA 준수 및 아동 개인정보 보호를 위해 사용자가 13세 미만임을 Singular에 알립니다.

서명

C++ 
static void TrackingUnder13();

사용 예시

C++ 
// Mark user as under 13 for COPPA compliance
USingularSDKBPLibrary::TrackingUnder13();
UE_LOG(LogTemp, Log, TEXT("User marked as under 13 years old"));

UnsetCustomUserId

사용자 지정 사용자 아이디 제거

일반적으로 로그아웃 또는 계정 전환 시 사용되는 이전에 설정된 사용자 지정 사용자 아이디를 지웁니다.

서명

C++ 
static void UnsetCustomUserId();

사용 예

C++ 
// Clear custom user ID on logout
USingularSDKBPLibrary::UnsetCustomUserId();
UE_LOG(LogTemp, Log, TEXT("Custom user ID has been cleared"));