Flutter SDK - SDK 메서드 참조

문서

Flutter SDK - SDK 메서드 레퍼런스

이 포괄적인 참조 문서에는 Flutter 애플리케이션용 Singular SDK에서 사용 가능한 모든 메서드가 설명되어 있습니다. SDK는 초기화, 이벤트 추적, 구매 보고, 어트리뷰션, 데이터 개인정보 보호 규정 준수 및 구성을 위한 기능을 제공합니다. 각 메서드에는 개발자가 Singular의 SDK 기능을 애플리케이션에 연동하는 데 도움이 되는 설명, 서명 및 실제 사용 예제가 함께 제공됩니다.

광고 구매

Singular.adRevenue 메서드

자세한 광고 데이터 정보로 광고 구매 이벤트를 추적합니다. 이 메서드를 사용하면 애플리케이션에 표시된 광고에서 발생한 구매을 다양한 파라미터와 함께 보고하여 광고 성과를 분류하고 분석할 수 있습니다.

시그니처

static void adRevenue(SingularAdData? adData)

사용 예시

// Create ad data object
final adData = SingularAdData("AdMob", "USD", 0.05)
    .withNetworkName("Google")
    .withAdType("Rewarded")
    .withAdPlacementName("level_complete")
    .withAdUnitId("ca-app-pub-123456789/1234567890");

// Track ad revenue event
Singular.adRevenue(adData);

clearGlobalProperties

Singular.clearGlobalProperties 메서드

이전에 설정된 모든 글로벌 속성을 제거합니다. 사용자가 애플리케이션에서 로그아웃할 때와 같이 전역 속성을 재설정해야 할 때 유용합니다.

서명

static void clearGlobalProperties()

사용 예시

// Clear all global properties, for example when a user logs out
Singular.clearGlobalProperties();

createReferrerShortLink

Singular.createReferrerShortLink 메서드

공유 및 어트리뷰션에 사용할 수 있는 리퍼러 정보가 포함된 짧은 링크를 생성합니다. 이 메서드는 사용자와 공유할 수 있는 추적 가능한 링크를 생성하여 설치 및 활동을 특정 리퍼럴 소스에 어트리뷰션할 수 있도록 합니다.

서명

static void createReferrerShortLink(String baseLink, String referrerName, String referrerId, Map args, ShortLinkCallback shortLinkCallback)

사용 예시

// Create a short link for referral
Singular.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Referrer Name
    "aq239897", // Referrer ID
    {
        "channel": "sms", 
        "campaign": "summer_promo"
    }, // Passthrough parameters
    (String? data, String? error) {
        if (error != null) {
            print("Error creating short link: $error");
        } else {
            print("Generated short link: $data");
            // Share the link with users
        }
    }
);

customRevenue

Singular.customRevenue 메서드

지정된 이벤트 이름, 통화 및 금액으로 사용자 지정 구매 이벤트를 추적합니다. 이를 통해 보다 구체적인 구매 추적을 위해 사용자 지정 이름으로 구매 이벤트를 추적할 수 있습니다.

  • 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.
  • 통화 코드는 모두 대문자이어야 하며 3글자로 구성된 ISO 4217 통화 코드를 준수해야 합니다.

서명

static void customRevenue(String eventName, String currency, double amount)

사용 예

// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99);

customRevenueWithAllAttributes

Singular.customRevenueWithAllAttributes 메서드

지정된 이벤트 이름, 통화, 금액, 상세 제품 정보로 사용자 지정 구매 이벤트를 추적합니다. 이를 통해 제품 세부 정보와 함께 포괄적인 구매 추적이 가능합니다.

  • 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.
  • 통화 코드는 모두 대문자이어야 하며 세 글자로 구성된 ISO 4217 통화 코드를 준수해야 합니다.

서명

static void customRevenueWithAllAttributes(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)

사용 예

// Track a custom revenue event with detailed product information
Singular.customRevenueWithAllAttributes(
    "item_purchased",
    "USD",
    19.98,
    "SKU123456",
    "Premium Sword",
    "Weapons",
    2,
    9.99
);

customRevenueWithAttributes

Singular.customRevenueWithAttributes 메서드

지정된 이벤트 이름, 통화, 금액 및 추가 사용자 지정 속성을 사용하여 사용자 지정 구매 이벤트를 추적합니다. 이를 통해 사용자 지정 매개변수를 사용하여 보다 자세한 구매 추적이 가능합니다.

  • 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.
  • 통화 코드는 모두 대문자이어야 하며 세 글자로 구성된 ISO 4217 통화 코드를 준수해야 합니다.

서명

static void customRevenueWithAttributes(String eventName, String currency, double amount, Map attributes)

사용 예

// Track a custom revenue event with additional parameters
Singular.customRevenueWithAttributes(
    "in_app_purchase",
    "USD",
    5.99,
    {
        "product_id": "com.app.gems_pack_small",
        "quantity": 1,
        "transaction_id": "T12345678",
        "receipt_id": "R98765432"
    }
);

event

Singular.event 메서드

지정된 이름의 간단한 이벤트를 추적합니다. 이 메서드를 사용하여 애플리케이션 내에서 사용자 행동과 참여를 추적할 수 있습니다.

  • 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.

서명

static void event(String eventName)

사용 예시

// Track a simple event
Singular.event("level_completed");

eventWithArgs

Singular.eventWithArgs 메서드

지정된 이름과 추가 사용자 지정 속성을 가진 이벤트를 추적합니다. 이를 통해 사용자 지정 매개변수를 사용하여 보다 상세한 이벤트 추적이 가능합니다.

  • 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.
  • 이벤트 속성 이름과 속성 값은 500자로 제한됩니다.

서명

static void eventWithArgs(String eventName, Map args)

사용 예

// Track an event with additional parameters
Singular.eventWithArgs(
    "level_completed",
    {
        "level_id": 5,
        "score": 12500,
        "time_spent": 120,
        "difficulty": "medium"
    }
);

getGlobalProperties

Singular.getGlobalProperties 메서드

현재 설정된 모든 글로벌 속성을 검색합니다. 이 메서드는 SDK에 설정된 모든 글로벌 프로퍼티가 포함된 맵으로 해석되는 Future를 반환합니다.

서명

static Future getGlobalProperties()

사용 예시

// Get all global properties
Singular.getGlobalProperties()

getLimitDataSharing

Singular.getLimitDataSharing 메서드

현재 데이터 공유 제한 상태를 검색합니다. 이 메서드는 현재 데이터 공유가 제한되어 있는지 여부를 나타내는 부울로 해석되는 Future를 반환합니다.

서명

static Future getLimitDataSharing()

사용 예시

// Check if data sharing is limited
Singular.getLimitDataSharing()

핸들 푸시 알림

Singular.handlePushNotification 메서드

어트리뷰션을 위한 푸시 알림 페이로드를 처리합니다. 앱이 푸시 알림을 수신할 때 이 메서드를 호출해야 Singular가 올바르게 어트리뷰션할 수 있습니다. 이 메서드는 iOS에서만 사용할 수 있습니다.

서명

static void handlePushNotification(Map pushNotificationPayload)

사용 예시

// Handle a received push notification
void onPushNotificationReceived(Map payload) {
  Singular.handlePushNotification(payload);
}

인앱 구매

Singular.inAppPurchase 메서드

이 메서드는 앱에서 트랜잭션을 관리하기 위해 Flutter IAP 패키지를 사용해야 합니다.

지정된 이벤트 이름과 구매 데이터로 인앱 구매 이벤트를 추적합니다. 이 메서드는 애플리케이션 내에서 발생한 인앱 구매를 보고하는 데 사용됩니다.

  • 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.

서명

static void inAppPurchase(String eventName, SingularIAP purchase)

사용 예시

import 'package:singular_flutter_sdk/singular_iap.dart';

singularPurchase = new SingularIOSIAP(
   product.price,
   product.currencyCode,
   purchase.productId,
   purchase.purchaseId,
   purchase.verificationData.serverVerificationData);

singularPurchase = new SingularAndroidIAP(
   product.price,
   product.currencyCode,
   purchase.singature,
   purchase.verificationData.serverVerificationData);

Singular.inAppPurchase(eventName, singularPurchase);

인앱 구매 속성

Singular.inAppPurchaseWithAttributes 메서드

이 메서드는 앱에서 트랜잭션을 관리하기 위해 Flutter IAP 패키지를 사용해야 합니다.

지정된 이벤트 이름, 구매 데이터 및 추가 사용자 정의 속성을 사용하여 인앱 구매 이벤트를 추적합니다. 이를 통해 커스텀 파라미터를 사용하여 보다 상세한 구매 추적이 가능합니다.

  • 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.

서명

static void inAppPurchaseWithAttributes(String eventName, SingularIAP purchase, Map attributes)

사용 예시

import 'package:singular_flutter_sdk/singular_iap.dart';

singularPurchase = new SingularIOSIAP(
   product.price,
   product.currencyCode,
   purchase.productId,
   purchase.purchaseId,
   purchase.verificationData.serverVerificationData);

singularPurchase = new SingularAndroidIAP(
   product.price,
   product.currencyCode,
   purchase.singature,
   purchase.verificationData.serverVerificationData);

// Track the purchase with additional attributes
Singular.inAppPurchaseWithAttributes(
    eventName, 
    singularPurchase,
    purchase,
    {
        "user_level": 42,
        "is_first_purchase": true,
        "gems_balance": 1500
    }
);

isAllTrackingStopped

Singular.isAllTrackingStopped 메서드

현재 모든 추적이 중지되었는지 확인합니다. 이 메서드는 현재 추적이 중지되었는지 여부를 나타내는 부울로 해석되는 Future를 반환합니다.

서명

static Future isAllTrackingStopped()

사용 예시

// Check if tracking is stopped
Singular.isAllTrackingStopped()

limitDataSharing

Singular.limitDataSharing 메서드

데이터 공유 제한 상태를 설정합니다. 사용자 동의 또는 개인정보 보호 요구 사항에 따라 데이터 공유를 제한하려면 이 메서드를 사용합니다.

서명

static void limitDataSharing(bool shouldLimitDataSharing)

사용 예시

// To limit data sharing (e.g., when user opts out) 
Singular.limitDataSharing(true);

// To enable full data sharing (e.g., when user opts in)
Singular.limitDataSharing(false);

registerDeviceTokenForUninstall

Singular.registerDeviceTokenForUninstall 메서드

제거 추적을 위한 디바이스 토큰을 등록합니다. 이 메서드는 제거 추적을 활성화하려면 푸시 알림 토큰과 함께 호출해야 합니다.

서명

static void registerDeviceTokenForUninstall(String deviceToken)

사용 예시

// Register device token for uninstall tracking
Singular.registerDeviceTokenForUninstall(token);

resumeAllTracking

Singular.resumeAllTracking 메서드

이전에 중지된 모든 추적 활동을 재개합니다. 추적이 중지된 후 다시 활성화하려면 이 메서드를 사용합니다.

서명

static void resumeAllTracking()

사용 예시

// Resume tracking, for example when user opts back in
Singular.resumeAllTracking();

setCustomUserId

Singular.setCustomUserId 메서드

현재 사용자에 대한 사용자 지정 사용자 아이디를 설정합니다. 이를 통해 Singular 데이터를 자체 사용자 식별 시스템과 연결할 수 있습니다.

서명

static void setCustomUserId(String customUserId)

사용 예

// Set custom user ID after user logs in
Singular.setCustomUserId(customUserId);

setDeviceCustomUserId

Singular.setDeviceCustomUserId 메서드

디바이스 수준에서 사용자 지정 사용자 ID를 설정합니다. 이를 통해 Singular 데이터를 디바이스 수준에서 자체 사용자 식별 시스템과 연결할 수 있습니다.

서명

static void setDeviceCustomUserId(String customUserId)

사용 예제

// Set device-level custom user ID
Singular.setDeviceCustomUserId(customUserId);

setFCMDeviceToken

Singular.setFCMDeviceToken 메서드

푸시 알림을 위한 Firebase 클라우드 메시징(FCM) 디바이스 토큰을 설정합니다. 이는 안드로이드 디바이스에서 앱 삭제 추적 및 푸시 알림 어트리뷰션에 사용됩니다.

서명

static void setFCMDeviceToken(String fcmToken)

사용 예제

// Set FCM token when received from Firebase
void onFCMTokenReceived(String token) {
    Singular.setFCMDeviceToken(token);
}

setGlobalProperty

Singular.setGlobalProperty 메서드

모든 이벤트와 함께 전송할 글로벌 프로퍼티를 설정합니다. 이를 통해 매번 속성을 지정하지 않고도 모든 이벤트에 일관된 속성을 추가할 수 있습니다.

서명

static Future setGlobalProperty(String key, String value, bool overrideExisting)

사용 예시

// Set a global property
Singular.setGlobalProperty("user_tier", "premium", true).then((isSuccess) {
    print("Global property set successfully: $isSuccess");
});

skanGetConversionValue

Singular.skanGetConversionValue 메서드

현재 SKAdNetwork 전환 값을 가져옵니다. 이 메서드는 iOS에만 해당되며, SKAdNetwork 어트리뷰션에 사용되는 현재 전환 값으로 확인되는 Future를 반환합니다.

서명

static Future skanGetConversionValue()

사용 예시

// Get the current SKAdNetwork conversion value
if (Platform.isIOS) {
    Singular.skanGetConversionValue().then((conversionValue) {
        print("Current conversion value: $conversionValue");
    });
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution 메서드

앱을 SKAdNetwork 어트리뷰션에 등록합니다. 이 메서드는 iOS에만 해당되며, SKAdNetwork 어트리뷰션을 활성화하기 위해 호출해야 합니다.

서명

static void skanRegisterAppForAdNetworkAttribution()

사용 예시

// Register for SKAdNetwork attribution
if (Platform.isIOS) {
    Singular.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue 메서드

SKAdNetwork 전환 값을 업데이트합니다. 이 메서드는 iOS 전용으로, SKAdNetwork 어트리뷰션에 사용되는 전환 값을 수동으로 업데이트할 수 있습니다.

서명

static Future skanUpdateConversionValue(int conversionValue)

사용 예시

// Update the SKAdNetwork conversion value
if (Platform.isIOS) {
    Singular.skanUpdateConversionValue(5).then((isSuccess) {
        print("Conversion value updated successfully: $isSuccess");
    });
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues 메서드

추가 파라미터로 SKAdNetwork 전환 값을 업데이트합니다. 이 메서드는 iOS 16.1 이상에만 적용되며, SKAdNetwork 4.0 어트리뷰션의 미세, 거친, 잠금 값을 업데이트할 수 있습니다.

서명

static void skanUpdateConversionValues(int conversionValue, int coarse, bool lock)

사용 예시

// Update the SKAdNetwork 4.0 conversion values
if (Platform.isIOS) {
    Singular.skanUpdateConversionValues(
        5,       // fine value (0-63)
        1,       // coarse value (0=low, 1=medium, 2=high)
        false    // lock
    );
}

start

Singular.start 메서드

제공된 설정으로 Singular SDK를 초기화합니다. Singular SDK 사용을 시작하기 위해 가장 먼저 호출해야 하는 메서드입니다.

서명

static void start(SingularConfig config)

사용 예시

// Create configuration object
SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');

// Configure additional options if needed
config.customUserId = "user-123456";
config.sessionTimeout = 60;

// Initialize the SDK
Singular.start(config);

stopAllTracking

Singular.stopAllTracking 메서드

모든 추적 활동을 중지합니다. 이 메서드를 사용하면 사용자가 옵트아웃할 때 또는 개인 정보 보호를 준수하기 위해 추적을 비활성화할 수 있습니다.

서명

static void stopAllTracking()

사용 예시

// Stop tracking, for example when user opts out.
Singular.stopAllTracking();

trackingOptIn

Singular.trackingOptIn 메서드

사용자가 추적에 옵트인했음을 나타냅니다. 사용자가 추적 및 데이터 수집에 명시적으로 동의할 때 이 메서드를 호출합니다.

서명

static void trackingOptIn()

사용 예시

// User has opted in to tracking
Singular.trackingOptIn();

trackingUnder13

Singular.trackingUnder13 메서드

사용자가 13세 미만임을 나타냅니다. 이 메서드를 호출하면 13세 미만 사용자에 대한 COPPA 및 기타 규정을 준수할 수 있습니다.

서명

static void trackingUnder13()

사용 예시

// Notifies Singular the User is under 13 years old, GDPR_UNDER_13 flag applied.
Singular.trackingunder13();

unsetCustomUserId

Singular.unsetCustomUserId 메서드

이전에 설정된 사용자 지정 사용자 아이디를 제거합니다. 사용자가 로그아웃하거나 이벤트를 더 이상 현재 사용자 ID에 연결하지 않으려는 경우 이 메서드를 호출하세요.

서명

static void unsetCustomUserId()

사용 예시

// Clear custom user ID when user logs out
Singular.unsetCustomUserId();

unsetGlobalProperty

Singular.unsetGlobalProperty 메서드

이전에 설정된 전역 속성을 제거합니다. 특정 글로벌 프로퍼티를 더 이상 이벤트와 함께 전송하지 않으려면 이 메서드를 호출하세요.

서명

static void unsetGlobalProperty(String key)

사용 예시

// Remove a global property
Singular.unsetGlobalProperty("user_tier");