Flutter SDK - 구성 방법 참조

팔로우
Avatar
Jared Ornstead
Updated

Flutter SDK - 구성 참조

이 문서는 Flutter 애플리케이션용 Singular SDK에서 사용할 수 있는 모든 구성 옵션에 대한 포괄적인 참조를 제공합니다. SingularConfig 객체를 사용하면 추적 설정, 어트리뷰션 옵션, 개인정보 보호 제어 등을 포함하여 SDK의 동작을 사용자 정의할 수 있습니다. 각 구성 속성은 설명, 서명 및 실제 사용 예제와 함께 제공됩니다.

brandedDomains

SingularConfig.brandedDomains 속성

SDK가 Singular Links로 처리해야 하는 커스텀 링크 도메인입니다. 트래킹 링크에 사용하는 모든 브랜디드 도메인을 추가하세요. 설정하지 않으면 Manage Links 페이지에 등록된 sng.link 도메인만 인식됩니다. 기본값은 빈 목록입니다.

서명

List<String> brandedDomains

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.brandedDomains = ['go.yourcompany.com', 'promo.yourcompany.com'];

clipboardAttribution

SingularConfig.clipboardAttribution 속성

디바이스 클립보드에 복사된 딥링크를 추적하기 위해 클립보드 어트리뷰션을 활성화합니다. 활성화하면 SDK는 앱 실행 시 클립보드에서 Singular 링크를 확인합니다.

서명

bool clipboardAttribution

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.clipboardAttribution = true;

collectOAID

SingularConfig.collectOAID 속성

안드로이드 기기에서 OAID(익명 디바이스 식별자)를 수집할 수 있도록 설정합니다. OAID는 주로 중국에서 사용되는 광고 식별자입니다.

서명

bool collectOAID

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.collectOAID = true;

conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback 속성

SKAdNetwork 전환 값이 업데이트될 때 트리거되는 콜백 함수를 설정합니다(iOS만 해당). 이 콜백은 새로운 전환 값을 파라미터로 받습니다.

시그니처

ConversionValueUpdatedCallback? conversionValueUpdatedCallback

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.conversionValueUpdatedCallback = (int conversionValue) {
  print('SKAdNetwork conversion value updated: $conversionValue');
};

conversionValuesUpdatedCallback

SingularConfig.conversionValuesUpdatedCallback 속성

SKAdNetwork 4.0+ 전환 값에 대한 콜백 함수를 설정합니다(iOS 16.1+에만 해당). 이 콜백은 미세 전환 값, 거친 전환 값, 잠금 상태를 수신합니다.

서명

ConversionValuesUpdatedCallback? conversionValuesUpdatedCallback

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.conversionValuesUpdatedCallback = (int conversionValue, int coarse, bool lock) {
  print('Fine: $conversionValue, Coarse: $coarse, Locked: $lock');
};

customSdid

SingularConfig.customSdid 속성

사용자 지정 Singular 디바이스 ID(SDID)를 설정합니다. 이를 통해 SDK에서 생성된 장치 식별자를 사용하는 대신 고유한 장치 식별자를 제공할 수 있습니다.

서명

String? customSdid

사용 예

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.customSdid = 'my_custom_device_id_123';

customUserId

SingularConfig.customUserId 속성

SDK 초기화 중에 사용자 지정 사용자 식별자를 설정합니다. 이렇게 하면 모든 이벤트가 시작부터 애플리케이션의 사용자 ID와 연결됩니다.

서명

String? customUserId

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.customUserId = 'user_12345';

deviceAttributionCallback

BETA 기능 - 디바이스 어트리뷰션 데이터를 사용할 수 있을 때 호출되는 콜백 함수를 설정합니다.

SingularConfig.deviceAttributionCallback 속성

디바이스 어트리뷰션 데이터를 수신하는 콜백 함수를 설정합니다. 이 콜백은 Singular 서버에서 어트리뷰션 정보를 사용할 수 있게 되면 트리거됩니다.

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

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

시그니처

DeviceAttributionCallback? deviceAttributionCallback

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.deviceAttributionCallback = (Map<String, dynamic> attributes) {
  print('Attribution data received:');
  attributes.forEach((key, value) {
    print('  $key: $value');
  });
};

didSetSdidCallback

SingularConfig.didSetSdidCallback 속성

SDK에서 Singular 디바이스 ID(SDID)가 설정된 후 트리거되는 콜백 함수를 설정합니다.

시그니처

SdidAccessorCallback? didSetSdidCallback

사용 예제

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.didSetSdidCallback = (String sdid) {
  print('SDID has been set: $sdid');
};

enableLogging

SingularConfig.enableLogging 속성

Singular SDK에 대한 디버그 로깅을 활성화합니다. 활성화하면 SDK가 디버깅 및 문제 해결에 도움이 되는 자세한 로그를 출력합니다.

서명

bool enableLogging

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.enableLogging = true;

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval 속성

지정된 시간 초과 간격(초)으로 ODM(온 디바이스 매칭)을 사용하도록 설정합니다. ODM은 데이터를 Singular 서버로 전송하기 전에 로컬에서 디바이스 식별자를 일치시켜 어트리뷰션 정확도를 향상시킵니다.

서명

int enableOdmWithTimeoutInterval

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.enableOdmWithTimeoutInterval = 5; // 5 seconds timeout

espDomains

SingularConfig.espDomains 속성

Singular Links를 감싸는 이메일 서비스 제공업체(ESP)의 도메인입니다. 이 도메인으로 링크가 도착하면 SDK가 리디렉션을 따라가 원래의 Singular Link를 복원하므로 클릭이 정상적으로 어트리뷰션됩니다. 기본값은 빈 목록입니다.

서명

List<String> espDomains

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.espDomains = ['sl.esp.link', 'links.youresp.com'];

facebookAppId

SingularConfig.facebookAppId 속성

페이스북 어트리뷰션 연동을 위한 페이스북 앱 ID를 설정합니다. 이를 통해 페이스북 광고 캠페인에 대한 적절한 어트리뷰션 추적이 가능합니다.

서명

String? facebookAppId

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.facebookAppId = '1234567890123456';

globalProperties

SingularConfig.globalProperties 속성

SDK 초기화 중 글로벌 프로퍼티 목록을 설정합니다. 이 프로퍼티는 SDK가 추적하는 모든 이벤트에 자동으로 포함됩니다.

서명

List<SingularGlobalProperty> globalProperties

사용 예시

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.globalProperties = [
  SingularGlobalProperty('app_version', '2.5.0', true),
  SingularGlobalProperty('user_tier', 'premium', false)
];

imei

SingularConfig.imei 속성

추적할 디바이스 IMEI(국제 모바일 장비 식별자)를 설정합니다. 이 속성은 주로 IMEI가 일반적인 디바이스 식별자인 특정 아시아 시장에서 사용됩니다.

서명

String? imei

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.imei = '123456789012345';

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers 속성

SDK 초기화 중 광고 식별자(iOS의 경우 IDFA, Android의 경우 GAID) 수집을 제한합니다. 활성화하면 SDK가 광고 ID를 수집하거나 전송하지 않습니다.

서명

bool limitAdvertisingIdentifiers

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.limitAdvertisingIdentifiers = true;

limitDataSharing

SingularConfig.limitDataSharing 속성

SDK 초기화 중 타사와의 데이터 공유를 제한합니다. 활성화하면 SDK가 애드 네트워크 및 기타 파트너와의 어트리뷰션 데이터 공유를 제한합니다.

서명

bool? limitDataSharing

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.limitDataSharing = true;

logLevel

SingularConfig.logLevel 속성

SDK의 로깅 수준을 설정합니다. 값이 높을수록 디버깅을 위해 더 자세한 로깅 출력이 제공됩니다.

사용 가능한 레벨은 다음과 같습니다:

  • NONE = -1

  • VERBOSE = Log.VERBOSE(Android 상수, 숫자 값 2)

  • DEBUG = Log.DEBUG (3)

  • INFO = Log.INFO (4)

  • WARNING = Log.WARN (5)

  • ERROR = Log.ERROR (6)

서명

int logLevel

사용 예제

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.logLevel = 5; // Maximum logging detail

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement 속성

수동 SKAdNetwork 전환 값 관리를 활성화합니다(iOS만 해당). 활성화하면 SDK가 전환 값을 자동으로 업데이트하지 않으므로 전환 값 설정 시기와 방법을 완전히 제어할 수 있습니다.

서명

bool manualSkanConversionManagement

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.manualSkanConversionManagement = true;

pushNotificationsLinkPaths

SingularConfig.pushNotificationsLinkPaths 속성

푸시 알림 페이로드에서 Singular Link를 찾을 위치입니다. 각 항목은 페이로드를 따라가는 키 목록이므로, 앱이 수신하는 페이로드 형태마다 항목을 하나씩 추가하세요. 기본값은 [[]]입니다.

서명

List<List<String>> pushNotificationsLinkPaths

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.pushNotificationsLinkPaths = [
  ['sng_link'],                             // Top-level key
  ['data', 'url'],                          // Nested path
  ['rootObj', 'nestedObj', 'singularLink'], // Deep nested path
];

sdidReceivedCallback

SingularConfig.sdidReceivedCallback 속성

서버에서 SDID(Singular Device ID)를 수신하거나 로컬 스토리지에서 검색할 때 트리거되는 콜백 함수를 설정합니다.

서명

SdidAccessorCallback? sdidReceivedCallback

사용 예

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.sdidReceivedCallback = (String sdid) {
  print('SDID received: $sdid');
};

sessionTimeout

SingularConfig.sessionTimeout 속성

세션 타임아웃 기간을 초 단위로 설정합니다. 이 기간이 지나면 앱이 다시 열릴 때 SDK는 새 세션으로 간주합니다.

서명

double sessionTimeout

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.sessionTimeout = 60.0; // 60 seconds

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut 속성

짧은 링크를 확인하기 위한 시간 초과 기간을 초 단위로 설정합니다. 이 값은 SDK가 시간 초과 전에 짧은 링크가 해결될 때까지 기다리는 시간을 결정합니다.

서명

double shortLinkResolveTimeOut

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.shortLinkResolveTimeOut = 10.0; // 10 seconds

singularLinksHandler

SingularConfig.singularLinksHandler 속성

Singular 링크(딥링크)에 대한 콜백 핸들러를 설정합니다. 이 콜백은 사용자가 Singular 짧은 링크 또는 디퍼드 딥링크를 통해 앱을 열 때 트리거됩니다.

서명

SingularLinksHandler? singularLinksHandler

사용 예시

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_link_params.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.singularLinksHandler = (SingularLinkParams params) {
  print('Deep link received:');
  print('  Deep link: ${params.deeplink}');
  print('  Passthrough: ${params.passthrough}');
  print('  Is deferred: ${params.isDeferred}');
};

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled 속성

SKAdNetwork 연동을 활성화 또는 비활성화합니다(iOS만 해당). 활성화하면 SDK가 SKAdNetwork 어트리뷰션 및 전환 값 업데이트를 자동으로 처리합니다.

서명

bool skAdNetworkEnabled

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.skAdNetworkEnabled = true;

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval 속성

iOS에서 앱 추적 투명성(ATT) 승인을 기다리는 시간 제한 간격을 초 단위로 설정합니다. 사용자가 ATT 프롬프트에 응답하거나 타임아웃에 도달할 때까지 SDK는 초기화를 지연합니다.

서명

int waitForTrackingAuthorizationWithTimeoutInterval

사용 예시

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.waitForTrackingAuthorizationWithTimeoutInterval = 30; // 30 seconds

전체 구성 예제

다음은 Flutter 애플리케이션에 대해 여러 옵션을 사용하여 Singular SDK를 구성하는 방법을 보여주는 포괄적인 예제입니다.

Dart 
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_link_params.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initSingularSDK();
  }

  void initSingularSDK() {
    // Create configuration object
    SingularConfig config = SingularConfig(
      'YOUR_API_KEY',
      'YOUR_SECRET_KEY'
    );

    // Enable logging for debugging
    config.enableLogging = true;
    config.logLevel = 4;

    // Set custom user ID if available
    config.customUserId = 'user_12345';

    // Configure session timeout
    config.sessionTimeout = 60.0;

    // Enable clipboard attribution
    config.clipboardAttribution = true;

    // Configure SKAdNetwork (iOS)
    config.skAdNetworkEnabled = true;
    config.manualSkanConversionManagement = false;
    config.waitForTrackingAuthorizationWithTimeoutInterval = 30;

    // Set conversion value callbacks (iOS)
    config.conversionValueUpdatedCallback = (int conversionValue) {
      print('SKAdNetwork conversion value updated: $conversionValue');
    };

    config.conversionValuesUpdatedCallback = (int cv, int coarse, bool lock) {
      print('SKAdNetwork values - Fine: $cv, Coarse: $coarse, Lock: $lock');
    };

    // Configure deep link handling
    config.singularLinksHandler = (SingularLinkParams params) {
      print('Singular Link detected');
      print('Deep link: ${params.deeplink}');
      print('Passthrough params: ${params.passthrough}');
      print('Is deferred: ${params.isDeferred}');

      // Handle deep link navigation
      if (params.deeplink != null) {
        // Navigate to appropriate screen based on deep link
      }
    };

    // Set short link timeout
    config.shortLinkResolveTimeOut = 10.0;

    // Configure attribution callback
    config.deviceAttributionCallback = (Map<String, dynamic> attributes) {
      print('Attribution data received:');
      attributes.forEach((key, value) {
        print('  $key: $value');
      });
    };

    // Configure SDID callbacks
    config.sdidReceivedCallback = (String sdid) {
      print('SDID received: $sdid');
    };

    config.didSetSdidCallback = (String sdid) {
      print('SDID has been set: $sdid');
    };

    // Set global properties
    config.globalProperties = [
      SingularGlobalProperty('app_version', '2.5.0', true),
      SingularGlobalProperty('user_tier', 'premium', false),
      SingularGlobalProperty('environment', 'production', true)
    ];

    // Configure Facebook integration
    config.facebookAppId = '1234567890123456';

    // Privacy settings
    config.limitDataSharing = false;
    config.limitAdvertisingIdentifiers = false;

    // Android-specific settings
    config.collectOAID = true;

    // Enable On-Device Matching
    config.enableOdmWithTimeoutInterval = 5;

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

    print('Singular SDK initialized successfully');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Singular Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: Scaffold(
        appBar: AppBar(
          title: Text('Singular SDK Demo'),
        ),
        body: Center(
          child: Text('Singular SDK Initialized'),
        ),
      ),
    );
  }
}