ドキュメント

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'
  }
);

イベント

Singular.event メソッド

イベント名のみのシンプルなイベントを追跡します。これはSingular SDKで最も基本的なイベントトラッキングです。

シグネチャ

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によって追跡されるすべてのイベントに自動的に含まれます。

シグネチャ

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');

handlePushNotification

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);

inAppPurchase

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);

inAppPurchaseWithAttributes

Singular.inAppPurchaseWithAttributesメソッド

カスタム属性を追加したアプリ内課金イベントをトラッキングします。このメソッドは、基本的なIAPトラッキングを拡張し、より詳細な購入トラッキングのためのカスタムKey-Valueペアを許可します。

シグネチャ

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');

リミットデータ共有

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);

アンインストールのためのデバイストークンの登録

Singular.registerDeviceTokenForUninstallメソッド

アンインストール追跡のためにデバイスのプッシュ通知トークンを登録します。これにより、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);

レジュームオールトラッキング

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 メソッド

Firebase Cloud Messaging (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メソッド

粗い変換値やロックステータス（iOS 16.1+のみ）などの追加パラメータでSKAdNetworkの変換値を更新します。このメソッドは、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
  );
}

開始

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();

トラッキングオプトイン

Singular.trackingOptInメソッド

ユーザーがトラッキングをオプトインしたことを示します。このメソッドは、ユーザがデータのトラッキングとアトリビューションに明示的に同意したときに呼び出されるべきです。

シグネチャ

static void trackingOptIn()

使用例

import 'package:singular_flutter_sdk/singular.dart';

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

トラッキングアンダー13

Singular.trackingUnder13 メソッド

ユーザーが13歳未満であることを示します。このメソッドはCOPPAコンプライアンスモードを有効にし、13歳未満のユーザーのデータ収集を制限します。

シグネチャ

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 メソッド

特定のグローバル・プロパティをキーによって削除します。このメソッドは、以前に設定された単一のグローバル・プロパティを消去します。

シグニチャ

static void unsetGlobalProperty(String key)

使用例

import 'package:singular_flutter_sdk/singular.dart';

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