필수 조건

원활한 연동 과정을 위해 Singular Flutter SDK를 설치하기 전에 다음 필수 단계를 완료해 주세요.

설치

SDK 패키지 설치

pubspec.yaml 의존성 관리자를 사용하여 프로젝트에 Singular Flutter SDK를 추가하십시오. 이 SDK는 iOS 및 Android용 네이티브 Singular SDK에 대한 Dart 바인딩을 제공합니다. iOS 및 Android용 네이티브 Singular SDK에 대한 Dart 바인딩을 제공합니다.

SDK 종속성 추가

1. pubspec.yaml 업데이트: 프로젝트의 pubspec.yaml 파일에 Singular Flutter SDK 의존성을 추가하세요:
   pubspec.yaml

   dependencies:
     flutter:
       sdk: flutter
     singular_flutter_sdk: ^1.8.0

2. 의존성 설치: 터미널에서 프로젝트 디렉터리로 이동한 후 다음 명령어를 실행하세요:
   bash

   flutter packages get

플랫폼 구성

iOS 구성

iOS 어트리뷰션 추적을 위해 AdServices 프레임워크 지원을 활성화하려면 iOS 전용 설정을 완료하십시오.

AdServices 프레임워크 추가

Apple Search Ads 어트리뷰션 및 iOS 14.3 이상 SKAdNetwork 연동을 위해서는 AdServices 프레임워크가 필요합니다.

1. iOS 프로젝트로 이동: Flutter 프로젝트의 iOS 디렉터리를 열고 Xcode 작업 공간을 찾습니다.
   • Flutter 프로젝트의 ios 폴더로 이동합니다.
   • Xcode에서 Runner.xcworkspace 를 엽니다(CocoaPods를 사용하는 경우 .xcworkspace 를 사용하고, 그렇지 않은 경우 .xcodeproj 를 사용하십시오).
2. AdServices 프레임워크 추가: Xcode 프로젝트 설정에서 프레임워크를 구성하십시오.
   • Xcode에서 프로젝트의 타겟(예: "Runner")을 선택합니다.
   • General 탭으로 이동합니다.
   • " 프레임워크, 라이브러리 및 임베디드 콘텐츠" 섹션으로 스크롤합니다.
   • '+' 버튼을 클릭합니다.
   • AdServices.framework 를 검색하여 추가합니다.
   • 프레임워크 상태를 '선택적 (Optional)'으로 설정합니다(이전 iOS 버전과의 호환성을 보장합니다).

Android 구성

SDK가 제대로 작동하도록 필요한 권한과 종속성을 추가하도록 Android 빌드 파일을 구성하십시오.

필수 권한 추가

AndroidManifest.xml 파일의 <manifest> 태그 아래에 다음 권한을 추가하여 핵심 SDK 기능을 활성화하십시오.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

삼성 갤럭시 스토어 지원

삼성 갤럭시 스토어에서 설치 리퍼러 추적을 활성화하려면 AndroidManifest.xml 에 다음을 추가하십시오:

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

전달 의존성

Gradle 구성에서 Singular SDK에 대한 전이적 종속성을 비활성화한 경우, 다음 필수 종속성을 수동으로 추가하십시오:

dependencies {
    // Required for install referrer tracking
    implementation 'com.android.installreferrer:installreferrer:2.2'

    // Required for App Set ID
    implementation 'com.google.android.gms:play-services-appset:16.0.0'
}

ProGuard 구성

릴리스 APK를 빌드할 때 ProGuard(또는 R8)가 SDK 클래스를 제거하거나 난독화할 수 있습니다. Singular 기능을 유지하려면 다음 keep 규칙을 추가하십시오.

1. ProGuard 파일 찾기: Flutter 프로젝트의 android/app/proguard-rules.pro 경로로 이동합니다.
2. keep 규칙 추가: 다음 규칙을 추가하여 SDK 클래스를 보존하세요:
   android/app/proguard-rules.pro

   # Preserve Singular SDK classes
   -keep class com.singular.sdk.** { *; }
   
   # Preserve Android Install Referrer library
   -keep public class com.android.installreferrer.** { *; }
   
   # Uncomment if using Singular revenue tracking with Google Play Billing Library
   #-keep public class com.android.billingclient.** { *; }

SDK 연동

앱이 실행될 때마다 Singular SDK를 초기화하십시오. SDK 초기화는 모든 Singular 어트리뷰션 기능에 필수적이며, 사용자 유지율 지표를 계산하기 위한 새로운 세션을 생성합니다.

SDK 클래스 임포트

메인 애플리케이션 파일(일반적으로 ` main.dart`)의 상단에 Singular SDK 클래스를 임포트하십시오.

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

SDK 초기화

SDK 자격 증명을 사용하여 SingularConfig 객체를 생성하고, 선택적 기능을 구성한 후, start() 메서드를 사용하여 SDK를 초기화하십시오.

기본 초기화

1. 인증 정보 가져오기: Singular 계정에로그인하고 'Developer Tools > SDK Integration > SDK Keys'로이동하여 SDK 키와 시크릿을 확인하세요.
2. 구성 생성: 자격 증명을 사용하여 SingularConfig 객체를 인스턴스화합니다.
3. 구성 추가: 선택적으로 속성 설정기를 사용하여 SDK 동작을 구성합니다( 구성 참조 참조).
4. SDK 초기화: Singular.start()를 호출하여 SDK를 시작합니다.

초기화 예시

앱의 진입점(일반적으로 메인 StatefulWidget의 initState() 메서드 내)에서 SDK를 초기화합니다.

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

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

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

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

    // Create configuration with credentials
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // Enable debug logging
    config.enableLogging = true;
    config.logLevel = 4;

    // Set session timeout (in seconds)
    config.sessionTimeout = 60.0;

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

고급 구성 예시

초기화 중에 SingularConfig 객체에 추가 속성을 설정하여 여러 SDK 기능을 구성한 후 start() 를 호출합니다.

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

  void initializeSingularSDK() {
    // Create configuration with credentials
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // User identification
    config.customUserId = 'user_123456';

    // Privacy settings
    config.limitDataSharing = false;
    
    // Deep linking handler
    config.singularLinksHandler = (SingularLinkParams params) {
      print('Deep link received: ${params.deeplink}');
      print('Passthrough params: ${params.passthrough}');
      print('Is deferred: ${params.isDeferred}');
      // Handle navigation based on deep link
    };

    // Short link timeout
    config.shortLinkResolveTimeOut = 10.0;

    // Facebook integration
    config.facebookAppId = 'YOUR_FACEBOOK_APP_ID';

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

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

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

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

    // Debugging
    config.enableLogging = true;
    config.logLevel = 4;

    // Session timeout
    config.sessionTimeout = 60.0;

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

고급 구성

Google Ads iOS 연동 전환 측정 필수 사항

앱에서 iOS 14.5 이상 사용자를 대상으로 하는 Google Ads 캠페인을 실행하는 경우, iOS 연동 전환 측정(ICM)을 지원하려면 추가적인 SDK 구성 단계가 필요합니다. 여기에는 다음이 포함됩니다:

• Google의 기기 내 측정(ODM) SDK 연동
• Singular iOS SDK v12.8.1 이상으로 업데이트(Unity의 경우 v5.5.0 이상, Flutter/Cordova의 경우 v1.8.0 이상, React Native의 경우 v3.9.0 이상)
• -ObjC 링크어 플래그 추가 및 SingularConfig 에서 enableOdmWithTimeoutInterval 활성화

참고: enableOdmWithTimeoutInterval를 활성화하면 SDK 초기화가 지연되고 딥 링크 콜백이 연기될 수 있습니다. 재작업을 방지하려면 초기 SDK 구현 단계에서 이 설정을 완료하십시오.

전체 iOS ICM 기술 요구 사항 참조