Flutter

1. Plugin Integration

적용할 최신 버전은 CHANGELOG.md 파일을 참고해주세요.

1.1 Plugin 설치

개발하시는 Flutter 프로젝트의 폴더로 이동하시어 아래의 명령을 수행하여 plugin 을 설치합니다.

flutter pub add s2offerwall_flutter

추후 plugin 이 업데이트 되는 경우 아래의 명령을 수행하시어 최신 버전의 plugin 으로 적용하실 수 있습니다.

flutter pub upgrade

// 또는 pubspec.yaml 파일의 dependencies: 아래의 s2offerwall_flutter:^버전코드 부분 수정한 후 
flutter pub get

Plugin 을 사용하기 위하여 아래의 import 구문을 추가합니다.

import 'package:s2offerwall_flutter/s2offerwall_flutter.dart';

1.2 APP_ID 설정하기

Android 의 경우에는 AndroidMenifest.xml 파일에 설정하며, iOS 의 경우에는 info.plist 파일에 설정합니다.

또는 plugin 제공하는 setAppId() 함수를 사용할 수 있습니다.

S2OfferwallFlutter.setAppId("YOUR_APP_ID");

// Android 와 iOS 의 APP_ID 를 다르게 설정해야한다면 아래의 함수를 사용하세요.
S2OfferwallFlutter.setAppIdForAndroid("YOUR_APP_ID_FOR_ANDROID");
S2OfferwallFlutter.setAppIdForIOS("YOUR_APP_ID_FOR_IOS");

1.3 SDK 초기화

APP_ID 를 설정한 후 SDK 초기화 함수를 호출합니다.

S2OfferwallFlutter.initSdk();

SDK 초기화 성공 또는 실패 여부는 EventListener 를 등록하여 확인할 수 있습니다. initSDK() 호출 전에 설정해야합니다.

S2OfferwallFlutter.onInitCompleted((success) {
  if (success is bool && success) {
    print("SDK 초기화 성공");
  } 
  else {
    print("SDK 초기화 실패");
  }
});

// EventListner 를 등록한 후 초기화 함수를 호출합니다.
S2OfferwallFlutter.initSdk();

1.4 사용자 식별값 설정하기

광고 참여를 위해서는 사용자 식별값이 설정되어야합니다. 일반적으로 매체의 로그인 ID 가 사용되며 아래의 API 를 호출하여 SDK 에 사용자 식별값을 설정합니다. 이렇게 설정된 식별값은 이후 사용자가 광고 참여를 완료하는 시점에 매체의 서버로 callback 이 호출되는데 그때 pub_user_nm 파라메터로 전달됩니다.

사용자 식별값의 경우 로그인 ID 를 바로 사용하지 마시고 개인 정보 이슈가 없도록 가급적 Hash 또는 암호화된 값으로 전달해주시기 바랍니다.

// 사용자 식별값 설정하기
S2OfferwallFlutter.setUserName("USER_IDENTIFIER" [,"화면 표시용 명칭"]);

// 사용자 식별값 초기화
S2OfferwallFlutter.resetUserName();

SDK v1.0.19 부터 setUserName() 에 displayName 파라메터가 추가되었습니다. 해당 파라메터는 오퍼월내 이벤트에서 랭킹 등을 표시할 때 사용되며 유저의 앱 내 닉네임 등으로 전달해주시면 됩니다. Snap 오퍼월의 다양한 이벤트들을 100% 활용하기 위하여 displayName 파라메터가 필요하므로 가급적 적용해주시기 바랍니다.

유저의 닉네임등이 노출되면 안되는 경우에는 원하시는 형태로 마스킹 처리 후 (예: 우리****) 전달해주시기 바랍니다.

사용자가 광고를 참여하는 시점에 아직 사용자 식별값이 설정되지 않았다면 onLoginRequested() 이벤트가 호출됩니다. 이 이벤트에서 사용자 식별값을 설정하도록 구현해주세요.

S2OfferwallFlutter.onLoginRequested((param) {
    print("로그인 이벤트 수신");
    S2OfferwallFlutter.setUserName("USER_IDENTIFIER", "화면 표시용 명칭");
});

2. 오퍼월 띄우기

아래의 함수를 호출하여 오퍼월을 띄웁니다. Android 에서는 S2OfferwallActivity 를 사용하여 오퍼월을 보여주며, iOS 에서는 S2OfferwallViewController 를 modal 창으로 띄워서 오퍼월을 표시합니다.

S2OfferwallFlutter.showOfferwall("PLACEMENT_NAME");

플레이스먼트는 Snapplay 사이트에서 설정할 수 있습니다. 그리고 추가적으로 "main" 이라는 특별한 플레이스먼트가 있습니다. 메인 오퍼월은 여러개의 플레이스먼트 오퍼월을 조합하여 하나의 화면에 표시해주는 오퍼월입니다. 메인 오퍼월을 띄우고자 할 때에는 플레이스먼트 이름 대신에 별도로 정의된 S2Offerwall.main 상수를 사용합니다.

앱 추적 동의 설정

iOS 의 경우에는 IDFA 수집을 위한 추적 허용을 명시적으로 사용자에게 동의받아야합니다. 앱 추척(App Tracking Transparency, ATT) 동의 창을 띄우기 위해서는 우선 info.plist 파일에 Tracking Usage Description 항목을 작성해야합니다. (iOS의 2.2 APP_ID 설정하기 참고).

이후 앱 추적 동의 창을 띄우기 위한 아래의 함수를 호출합니다. 앱 추적 동의 창은 앱이 시작되는 시점에 띄우는 것을 권장합니다. 아래 함수 호출시 Android 의 경우에는 아무런 동작을 하지 않습니다.

S2OfferwallFlutter.presentATTPopup();

3. Sample Code

아래는 버튼을 클릭하면 Offerwall 을 띄우는 가장 간단한 구현 코드입니다.

import 'package:flutter/material.dart';
import 'package:s2offerwall_flutter/s2offerwall_flutter.dart';

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {

  @override
  void initState() {
    super.initState();

    S2OfferwallFlutter.presentATTPopup();

    S2OfferwallFlutter.setAppIdForIOS("IOS_APP_ID");
    S2OfferwallFlutter.setAppIdForAndroid("ANDROID_APP_ID");
    
    S2OfferwallFlutter.onLoginRequested((param) {
      S2OfferwallFlutter.setUserName("USER_IDENTIFIER","화면 표시용 명칭");
    });
    
    S2OfferwallFlutter.initSdk();
  }

  void _showOfferwall() {
    S2OfferwallFlutter.showOfferwall(S2Offerwall.main);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(        
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(widget.title),
      ),
      body: Center(
        child: Text(
              'show Offerwall',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _showOfferwall,
        tooltip: 'showOfferwall',
        child: const Icon(Icons.add),
      ),
    );
  }
}