NestAds Flutter SDK

NestAds Flutter SDK(이하 Flutter SDK)는 광고 트래킹 및 로그 수집을 위한 SDK입니다.

이 문서는 설치 및 사용 방법을 안내합니다.

준비

요구 사양

  • Flutter 3.24.0 이상
  • Dart 3.5.0 이상
  • iOS 14.0 이상
  • 최소 SDK 버전: 23 (Android 6.0 Marshmallow)
  • 타겟 SDK 버전: 34 (Android 14)

Dependencies

참고: 외부 라이브러리 의존성

NestAds Flutter SDK는 아래 라이브러리를 사용합니다.

설치

  1. pubspec.yaml 파일에 의존성 설정

pubspec.yaml 파일의 dependencies 하위에 아래과 같이 Flutter SDK에 대한 의존성을 추가합니다.

패키지 추가 시 들여 쓰기에 주의합니다.

dependencies:
  nestads: [최신버전]

터미널(Terminal)에 아래 명령어를 입력해 패키지를 추가할 수도 있습니다.

flutter pub add nestads
  1. Flutter SDK 설치

터미널(Terminal)에 아래 명령어를 입력해 추가한 SDK의 패키지를 설치할 수 있습니다.

flutter pub get

사용법

이제 Dart 코드에서 다음과 같이 사용할 수 있습니다.

import 'package:nestads/nestads.dart';

초기화

main() 함수 안에서 NestAds Flutter SDK 초기화 메서드인 NestAds.instance.initialize()을 호출합니다.

초기화 시 userId와 deviceInfo(osName, deviceBrand, deviceModel) 는 필수 값입니다.

예제 코드

void main() {
    await NestAds.instance.initialize(
        userId: 'user_id', //36자리 UUID
        deviceInfo: {
          'osName': 'Android',
          'deviceBrand': 'samsung',
          'deviceModel': 'SM-S926N',
        }
    );
}

초기화 하지 않는 경우 sendTrackingLog 메서드를 호출할 때 에러가 발생합니다.

트래킹 적재 사이즈, 시간 설정

NestAds.instance.setTrackingLogOptions() 함수를 통해 적재 개수와 적재 시간을 설정할 수 있습니다.

로그 적재 사이즈가 다 차거나, 적재 사이즈가 부족해도 적재 시간이 되면 로그를 전송하게 됩니다.

해당 메서드를 호출하지 않을 않은 경우 디폴트 값으로 10개, 5초로 설정됩니다.

예제 코드

void main() {
    NestAds.instance.setTrackingLogOptions(size: 10, duration: 5);
}

이벤트 트래킹

NestAds.instance.sendTrackingLog() 함수를 통해 이벤트 트래킹을 수행할 수 있습니다.

필수 값

  • type: 로그 타입
  • eventId: 로그 이벤트 ID
  • placementId: 게재 위치 ID

옵션 값

  • misc: 랭커 응답에 포함된 misc 값
  • requestId: 부모앱에서 직접 생성한 요청 ID
  • impressionOrder: 실제 이벤트 노출 순서 (1부터 시작)

참고: requestId 또는 misc.requestId 중 하나는 반드시 포함되어야 합니다.

이 함수는 랭커 응답과 비랭커 응답으로 나뉘어 동작합니다.

랭커 응답의 경우, 랭커 응답의 misc 값을 전부 넣어 보냅니다.

예제 코드

랭커 응답으로 받은 이벤트를 로깅하는 경우

void main() {
     NestAds.instance.sendTrackingLog(
        type: 'VIEW', 
        eventId: event['event_id'], 
        placementId: event['placement_id'], 
        impressionOrder: event['impression_order'] // 랭커에서 준 순서를 바꿔서 노출한 경우 사용
        misc: event['misc'], // 랭커 응답에 들어가 있는 misc 값 그대로
      );
    }

랭커 응답으로 받지 않은 이벤트를 로깅하는 경우

비랭커 응답의 경우 requestId를 만들어서 넣어줍니다.

예제 코드

void main() {
    NestAds.instance.sendTrackingLog(
          type: 'VIEW', 
          requestId: event['request_id'],
          eventId: event['event_id'], 
          placementId: event['placement_id'],
          impressionOrder: event['impression_order']
      );
    }

전송 실패 처리 방식

  1. 재전송 로직 전송 실패 시, 2초~60초 간격으로 최대 5회까지 재시도합니다. 모든 재시도 후에도 실패하면 로그를 로컬에 저장합니다.

  2. 로컬 로그 처리 로컬에 저장된 로그가 있을 경우, 재초기화되거나 새로운 로그를 전송할 때 함께 전송됩니다. sendPendingTrackingLogs 함수를 통해 로컬에 쌓여 있는 로그를 전송할 수 있습니다.

로그 저장 및 전송

NestAds.instance.savePendingTrackingLogsToLocal() 함수를 통해 현재까지 저장된 로그를 로컬에 저장합니다.

NestAds.instance.sendPendingTrackingLogs() 함수를 통해 로컬에 저장된 로그를 서버로 전송합니다.

예제 코드

await NestAds.instance.savePendingTrackingLogsToLocal(); // 현재까지 저장된 로그를 로컬에 저장
await NestAds.instance.sendPendingTrackingLogs(); // 로컬에 저장된 로그를 서버로 전송

Libraries

nestads_dev