문서

Flutter SDK - 메서드 참조

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

광고 구매

Singular.adRevenue 메서드

자세한 광고 데이터 정보로 광고 구매 이벤트를 추적합니다. 이 메서드를 사용하면 애드 네트워크 데이터, 게재 위치 정보, 구매 금액 등 애플리케이션에 표시된 광고에서 발생한 구매을 보고할 수 있습니다.

서명

static void adRevenue(SingularAdData adData)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_ad_data.dart';

// Create ad data object
SingularAdData adData = SingularAdData(
  'AdMob',
  'USD',
  0.99
)
  ..withAdPlatfom('Android')
  ..withAdType('Rewarded')
  ..withAdGroupId('group_123')
  ..withAdGroupName('Rewarded Video Group')
  ..withAdGroupType('rewarded_video')
  ..withImpressionId('impression_abc123')
  ..withAdPlacementName('main_menu')
  ..withAdUnitId('ca-app-pub-123456789')
  ..withAdUnitName('Main Menu Rewarded Video');

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

clearGlobalProperties

Singular.clearGlobalProperties 메서드

설정된 모든 글로벌 속성을 제거합니다. 글로벌 프로퍼티는 SDK에서 추적하는 모든 이벤트에 자동으로 추가되는 키-값 쌍입니다.

서명

static void clearGlobalProperties()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Clear all global properties
Singular.clearGlobalProperties();

createReferrerShortLink

Singular.createReferrerShortLink 메서드

추천 추적을 위한 Singular 쇼트 링크를 생성합니다. 이 메서드는 추천 어트리뷰션을 추적하기 위해 사용자가 공유할 수 있는 짧은 링크를 생성합니다.

서명

static void createReferrerShortLink(
  String baseLink,
  String referrerName,
  String referrerId,
  Map<String, String> passthroughParams,
  ShortLinkCallback completionHandler
)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Create a referrer short link
Singular.createReferrerShortLink(
  'https://yourapp.sng.link/A1b2c',
  'John Doe',
  'user_12345',
  {
    'promo_code': 'SUMMER2025',
    'campaign': 'referral_program'
  },
  (String? shortLink, String? error) {
    if (error != null) {
      print('Error creating short link: $error');
    } else {
      print('Short link created: $shortLink');
    }
  }
);

customRevenue

Singular.customRevenue 메서드

지정된 이벤트 이름, 통화 및 금액으로 커스텀 구매 이벤트를 추적합니다. 이 메서드는 인앱 구매나 광고 구매과 관련이 없는 구매을 추적하는 데 사용됩니다.

서명

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

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue event
Singular.customRevenue('Subscription_Purchase', 'USD', 9.99);

customRevenueWithAttributes

Singular.customRevenueWithAttributes 메서드

추가 속성이 있는 커스텀 구매 이벤트를 추적합니다. 이 메서드는 더 자세한 추적을 위해 사용자 지정 키-값 쌍을 포함할 수 있도록 하여 기본 사용자 지정 구매 추적을 확장합니다.

서명

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

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue with additional attributes
Singular.customRevenueWithAttributes(
  'Premium_Upgrade',
  'USD',
  29.99,
  {
    'subscription_tier': 'premium',
    'billing_cycle': 'annual',
    'promotion_code': 'ANNUAL20'
  }
);

customRevenueWithAllAttributes

Singular.customRevenueWithAllAttributes 메서드

제품 SKU, 제품 이름, 제품 카테고리, 제품 수량, 사용자 지정 속성을 포함한 모든 가능한 속성을 사용하여 사용자 지정 구매 이벤트를 추적합니다.

서명

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

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue with all attributes
Singular.customRevenueWithAllAttributes(
  'In_Game_Purchase',
  'USD',
  4.99,
  'gold_pack_500',
  'Gold Pack 500',
  'virtual_currency',
  1,
  {
    'payment_method': 'credit_card',
    'discount_applied': 'false'
  }
);

event

Singular.event 메서드

이벤트 이름만 있는 간단한 이벤트를 추적합니다. 이것은 Singular SDK에서 가장 기본적인 형태의 이벤트 추적입니다.

Signature

static void event(String eventName)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Track a simple event
Singular.event('Level_Completed');

eventWithArgs

Singular.eventWithArgs 메서드

키-값 쌍 형태의 추가 속성으로 이벤트를 추적합니다. 이를 통해 사용자 정의 매개변수를 사용하여 보다 자세한 이벤트 추적이 가능합니다.

서명

static void eventWithArgs(String eventName, Map args)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Track event with custom attributes
Singular.eventWithArgs('Level_Completed', {
  'level_number': 10,
  'score': 8500,
  'time_seconds': 245,
  'difficulty': 'hard'
});

getGlobalProperties

Singular.getGlobalProperties 메서드

현재 설정된 모든 글로벌 프로퍼티의 맵을 반환합니다. 글로벌 프로퍼티는 SDK에서 추적하는 모든 이벤트에 자동으로 포함됩니다.

Signature

static Future<Map<String, String>> getGlobalProperties()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Get all global properties
Map<String, String> properties = await Singular.getGlobalProperties();
print('Current global properties: $properties');

getLimitDataSharing

Singular.getLimitDataSharing 메서드

데이터 공유 제한의 현재 상태를 반환합니다. 이 메서드는 현재 타사와의 데이터 공유가 제한되어 있는지 여부를 확인합니다.

서명

static Future<bool> getLimitDataSharing()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Check if data sharing is limited
bool isLimited = await Singular.getLimitDataSharing();
print('Data sharing limited: $isLimited');

핸들 푸시 알림

Singular.handlePushNotification 메서드

푸시 알림 어트리뷰션을 처리합니다. 앱이 푸시 알림을 수신할 때 이 메서드를 호출하여 알림 기반 앱 실행에 대한 어트리뷰션 추적을 활성화해야 합니다.

서명

static void handlePushNotification(Map notification)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Handle incoming push notification
Map<String, dynamic> notificationData = {
  'title': 'New Offer Available',
  'body': 'Check out our latest deals',
  'campaign_id': 'summer_2025'
};

Singular.handlePushNotification(notificationData);

인앱 구매

Singular.inAppPurchase 메서드

인앱 구매 이벤트를 추적합니다. 이 메서드는 구매 추적 및 어트리뷰션을 위해 애플리케이션 내에서 이루어진 구매를 Singular에 보고합니다. Flutter in_app_purchase 패키지를사용하여 전체 거래 세부 정보가 포함된 구매 객체를 검색합니다.

SingularIAP purchase 객체는 플랫폼별 서브클래스 생성자를 사용하여 생성해야 합니다:

SingularIOSIAP(double revenue, String? currencyCode, String? productId, String? transactionId, String? receipt)

SingularAndroidIAP(double revenue, String? currencyCode, String? signature, String? receipt)

따라서 revenue 및 currencyCode 를 사용하여 적절한 SingularIAP 서브클래스를 먼저 빌드한 다음 플랫폼별 필드를 빌드하세요.

서명

static void inAppPurchase(String eventName, SingularIAP purchase)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';

// Build an iOS SingularIAP purchase object and send it to the SDK
const String eventName = 'iap_purchase'; // <= 32 ASCII chars
final SingularIAP purchase = SingularIOSIAP(
  4.99,               // revenue (double)
  'USD',              // currency code (String)
  'com.example.sku',  // productId (String)
  'transactionId123', // transactionID from AppStorePurchaseDetails (String)
  'base64_receipt'    // JWS receipt from StoreKit (String)
);

// OR, Build an Android SingularIAP purchase object and send it to the SDK
const String eventName = 'iap_purchase'; // <= 32 ASCII chars
final SingularIAP purchase = SingularAndroidIAP(
  4.99,               // revenue (double)
  'USD',              // currency code (String)
  'com.example.sku',  // Signature from GooglePlayPurchase (String)
  'originalJson_receipt'    // receipt Object from GooglePlayPurchase originalJson (String)
);

// Basic tracking
Singular.inAppPurchase(eventName, purchase);

인앱구매와 속성

Singular.inAppPurchaseWithAttributes 메서드

추가 사용자 지정 속성을 사용하여 인앱 구매 이벤트를 추적합니다. 이 메서드는 더 자세한 구매 추적을 위해 사용자 지정 키-값 쌍을 허용하여 기본 IAP 추적을 확장합니다.

서명

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

사용 예시

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';
// Generate SingularIAP purchase as above
// Tracking with attributes
  Singular.inAppPurchaseWithAttributes(eventName, purchase, {
    'user_level': 42,
    'is_first_purchase': true,
    'gems_balance': 1500
  });

isAllTrackingStopped

Singular.isAllTrackingStopped 메서드

모든 추적이 중지되었는지 여부를 반환합니다. 이 메서드는 SDK가 현재 데이터를 수집하거나 전송하지 않는 상태인지 확인합니다.

서명

static Future<bool> isAllTrackingStopped()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Check if tracking is stopped
bool isStopped = await Singular.isAllTrackingStopped();
print('All tracking stopped: $isStopped');

limitDataSharing

Singular.limitDataSharing 메서드

타사와의 데이터 공유를 제한하거나 활성화합니다. 이 메서드는 SDK가 어트리뷰션 목적으로 애드 네트워크 및 기타 타사 서비스와 데이터를 공유할지 여부를 제어합니다.

서명

static void limitDataSharing(bool limitDataSharingValue)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Limit data sharing
Singular.limitDataSharing(true);

// Or enable data sharing
Singular.limitDataSharing(false);

registerDeviceTokenForUninstall

Singular 등록 디바이스 토큰 토큰 제거 메서드

제거 추적을 위해 디바이스의 푸시 알림 토큰을 등록합니다. 이를 통해 Singular는 사용자가 애플리케이션을 제거할 때 이를 감지할 수 있습니다.

서명

static void registerDeviceTokenForUninstall(String token)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Register device token for uninstall tracking
String deviceToken = 'your_device_push_token_here';
Singular.registerDeviceTokenForUninstall(deviceToken);

resumeAllTracking

Singular.resumeAllTracking 메서드

이전에 중지된 모든 추적을 재개합니다. 이 메서드는 추적이 중지된 후 데이터 수집 및 전송을 다시 활성화합니다.

서명

static void resumeAllTracking()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Resume tracking after it was stopped
Singular.resumeAllTracking();

setCustomUserId

Singular.setCustomUserId 메서드

추적할 사용자 지정 사용자 식별자를 설정합니다. 이 메서드는 이벤트를 애플리케이션의 사용자 시스템에서 특정 사용자 ID와 연결합니다.

서명

static void setCustomUserId(String customUserId)

사용 예제

import 'package:singular_flutter_sdk/singular.dart';

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

setDeviceCustomUserId

Singular.setDeviceCustomUserId 메서드

이 메서드는 가격이 책정되어 더 이상 사용되지 않습니다.

서명

static void setDeviceCustomUserId(String customUserId)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

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

setFCMDeviceToken

Singular.setFCMDeviceToken 메서드

파이어베이스 클라우드 메시징(FCM) 디바이스 토큰을 설정합니다. 이 메서드는 푸시 알림에 FCM을 사용하는 Android 디바이스 전용 메서드입니다.

서명

static void setFCMDeviceToken(String token)

사용 예제

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Set FCM token (Android only)
if (Platform.isAndroid) {
  String fcmToken = 'your_fcm_token_here';
  Singular.setFCMDeviceToken(fcmToken);
}

setGlobalProperty

Singular.setGlobalProperty 메서드

이후의 모든 이벤트에 포함될 글로벌 프로퍼티를 설정합니다. 글로벌 프로퍼티는 SDK에서 추적하는 모든 이벤트에 자동으로 추가되는 키-값 쌍입니다.

서명

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

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Set a global property
Singular.setGlobalProperty('user_type', 'premium', true);
Singular.setGlobalProperty('app_theme', 'dark', false);

setLimitAdvertisingIdentifiers

Singular.setLimitAdvertisingIdentifiers 메서드

광고 식별자(iOS의 경우 IDFA, Android의 경우 GAID) 수집을 제한합니다. 이 메서드는 SDK가 어트리뷰션을 위해 광고 ID를 수집하고 사용할지 여부를 제어합니다.

서명

static void setLimitAdvertisingIdentifiers(bool limit)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Limit advertising identifier collection
Singular.setLimitAdvertisingIdentifiers(true);

skanGetConversionValue

Singular.skanGetConversionValue 메서드

현재 SKAdNetwork 전환 값을 가져옵니다(iOS만 해당). 이 메서드는 SKAdNetwork 어트리뷰션에 설정된 전환 값을 가져옵니다.

서명

static Future<int> skanGetConversionValue()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Get current SKAdNetwork conversion value (iOS only)
if (Platform.isIOS) {
  int conversionValue = await Singular.skanGetConversionValue();
  print('Current conversion value: $conversionValue');
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution 메서드

앱을 SKAdNetwork 어트리뷰션에 등록합니다(iOS만 해당). 이 메서드를 호출해야 iOS 기기에서 SKAdNetwork 추적을 활성화할 수 있습니다.

서명

static void skanRegisterAppForAdNetworkAttribution()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

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

skanUpdateConversionValue

Singular.skanUpdateConversionValue 메서드

SKAdNetwork 전환 값을 업데이트합니다(iOS만 해당). 이 메서드는 사용자 품질 또는 인게이지먼트 수준을 나타내는 SKAdNetwork 어트리뷰션의 새로운 전환 값을 설정합니다.

서명

static void skanUpdateConversionValue(int conversionValue)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Update SKAdNetwork conversion value (iOS only)
if (Platform.isIOS) {
  Singular.skanUpdateConversionValue(5);
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues 메서드

대략적인 전환 값과 잠금 상태를 포함한 추가 파라미터로 SKAdNetwork 전환 값을 업데이트합니다(iOS 16.1 이상만 해당). 이 메서드를 사용하면 SKAdNetwork 포스트백을 보다 세밀하게 제어할 수 있습니다.

서명

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

사용 예시

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Update conversion values with coarse value and lock (iOS 16.1+)
if (Platform.isIOS) {
  Singular.skanUpdateConversionValues(
    10,    // fine conversion value
    1,     // coarse conversion value
    false  // lock status
  );
}

start

Singular.start 메서드

제공된 구성으로 Singular SDK를 초기화하고 시작합니다. 이 메서드는 다른 SDK 메서드보다 먼저 호출되어야 하며, 애플리케이션 라이프사이클에서 가능한 한 빨리 호출해야 합니다.

서명

static void start(SingularConfig config)

사용 예시

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';

// Create and configure the SDK
SingularConfig config = SingularConfig(
  'YOUR_API_KEY',
  'YOUR_SECRET_KEY'
)
  ..withLoggingEnabled()
  ..withSessionTimeoutInSec(60);

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

stopAllTracking

Singular.stopAllTracking 메서드

SDK에 의한 모든 추적을 중지합니다. 이 메서드는 모든 데이터 수집 및 전송을 중지하며, 일반적으로 사용자가 추적을 거부할 때 개인정보 보호 규정 준수를 위해 사용됩니다.

서명

static void stopAllTracking()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Stop all tracking (for privacy opt-out)
Singular.stopAllTracking();

trackingOptIn

Singular.trackingOptIn 메서드

사용자가 추적에 옵트인했음을 나타냅니다. 이 메서드는 사용자가 데이터 추적 및 어트리뷰션에 명시적으로 동의할 때 호출해야 합니다.

서명

static void trackingOptIn()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

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

trackingUnder13

Singular.trackingUnder13 메서드

사용자가 13세 미만임을 나타냅니다. 이 메서드를 사용하면 13세 미만 사용자에 대한 데이터 수집을 제한하는 COPPA 준수 모드가 활성화됩니다.

서명

static void trackingUnder13()

사용 예시

import 'package:singular_flutter_sdk/singular.dart';

// Enable COPPA compliance mode
Singular.trackingUnder13();

unsetCustomUserId

Singular.unsetCustomUserId 메서드

사용자 정의 사용자 식별자를 제거합니다. 이 메서드는 일반적으로 사용자가 로그아웃할 때 호출되며 이전에 설정된 모든 사용자 지정 사용자 ID를 지웁니다.

서명

static void unsetCustomUserId()

사용 예

import 'package:singular_flutter_sdk/singular.dart';

// Remove custom user ID on logout
Singular.unsetCustomUserId();

unsetGlobalProperty

Singular.unsetGlobalProperty 메서드

키별로 특정 전역 속성을 제거합니다. 이 메서드는 이전에 설정된 Singular 글로벌 프로퍼티를 지웁니다.

서명

static void unsetGlobalProperty(String key)

사용 예제

import 'package:singular_flutter_sdk/singular.dart';

// Remove a specific global property
Singular.unsetGlobalProperty('user_type');