친구 초대 미션

친구 초대 미션은 [Client Admin]에서 프로모션 등록 시 설정할 수 있는 게임 미션입니다. 친구 초대 코드를 공유하여 신규 유저를 초대하면 초대한 유저와 초대받은 유저가 모두 리워드를 받을 수 있습니다. 언어별 설정 방법이 다르므로 개발 언어를 먼저 확인해 주세요!

---

Android

런처 Activity 내 선언된 Javascript Interface 에 sharedInviteLink 케이스를 추가합니다. 해당 코드 실행 시 OS 공유 시트를 노출 시키게 됩니다.

Interface function	Description
sharedInviteLink()	친구 초대 링크 공유 시 호출되는 함수 parameters inviteCode - 발급된 초대코드 infoMessage - 안내 메세지 link - 초대 링크

// 블리피 Launcher Web <-> App 인터페이스 규격
class ExampleWebAppInterface(private val mContext: Context) {
    ...
    @JavascriptInterface
    fun sharedInviteLink(inviteCode: String, infoMessage: String, link: String) {
        // 초대 미션 공유
        val msg = "초대코드: $inviteCode\n$infoMessage\n$link"

        // Android Sharesheet를 통해 텍스트 콘텐츠를 공유합니다.
        val sendIntent: Intent = Intent().apply {
            action = Intent.ACTION_SEND
            putExtra(Intent.EXTRA_TEXT, msg)
            type = "text/plain"
        }
        
        val shareIntent = Intent.createChooser(sendIntent, null)
        mContext.startActivity(shareIntent)
    }
    ...
}

---

iOS

1. 링크 공유 시트 노출을 위한 구조체 생성

친구 초대 데이터를 전달 받고 iOS 앱 안에서 공유 시트를 노출 시키는 구조체를 생성합니다.

• 공유 시트 노출을 위해 UIViewControllerRepresentable 사용

// ShareSheet.swift
import SwiftUI
import UIKit

// postMessage로 넘어오는 문자열을 JSON 형태로 파싱하기 위해 선언
// inviteCode - 발급된 초대코드
// infoMessage - Client Admin에 입력된 안내 메세지
// link - Client Admin에 입력된 초대 링크
struct InviteLink: Codable {
    var inviteCode: String
    var infoMessage: String
    var link: String
}

// 공유하기 시트
struct ShareSheet: UIViewControllerRepresentable {
    var items: [Any] // 공유할 항목

    func makeUIViewController(context: Context) -> UIActivityViewController {
        let controller = UIActivityViewController(activityItems: items, applicationActivities: nil)
        return controller
    }

    func updateUIViewController(_ uiViewController: UIActivityViewController, context: Context) {
        // 업데이트가 필요할 경우 여기에 로직 추가
    }
}

2. WebView 구조체에서 Script Message 핸들링 추가

• WKWebView 의 userContentController 에서 친구 초대 링크 공유 관련 이벤트 처리 로직을 추가합니다.

• 런처는 postMessage 문자열 데이터 형태로 전달하기 때문에 JSON 형태로 디코딩 과정이 필요합니다.

• 디코딩된 데이터를 부모 contentView의 onSharedInviteLink 콜백 함수에 전달합니다.

// LauncherWebView.swift
import WebKit
import SwiftUI

struct LauncherWebView: UIViewRepresentable {
    ...
    // 초대 링크 처리할 콜백 함수
    let onSharedInviteLink: (String, String, String) -> Void
    
    class Coordinator: NSObject, WKNavigationDelegate, WKScriptMessageHandler {
        ...
        func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
            // 런처 친구초대 링크 공유 이벤트 수신 시 처리
            if message.name == "sharedInviteLink" {
                // 메시지의 body는 JSON.stringify 문자열이라 디코딩 필요
                if let jsonString = message.body as? String,
                   let jsonData = jsonString.data(using: .utf8) {
                    do {
                        // JSON 문자열을 ShareSheet 클래스 내 InviteLink 구조체로 디코딩
                        let inviteData = try JSONDecoder().decode(InviteLink.self, from: jsonData)
                        // 부모의 onSharedInviteLink 메서드 호출
                        parent.onSharedInviteLink(inviteData.inviteCode, inviteData.infoMessage, inviteData.link)
                    } catch {
                        print("Failed to decode JSON: (error.localizedDescription)")
                    }
                } else {
                    print("Failed to convert message body to String or Data")
                }
            }
        }
        ...
    }
    
    ...
    func makeUIView(context: Context) -> WKWebView {
        ...
        // javascript에서 전달하는 이벤트 등록
        contentController.add(context.coordinator, name: "sharedInviteLink")
        ...
    }
    ...
    
    static func dismantleUIView(_ uiView: WKWebView, coordinator: Self.Coordinator) {
        uiView.configuration.userContentController.removeScriptMessageHandler(forName: "sharedInviteLink")
    }
}

3. WebView가 포함된 ContentView 내에서 ShareSheet 클래스 호출

WebView 에 실행된 런처에서 친구 초대 링크 공유에 대한 이벤트가 발생하면 ContentView에 선언된 onSharedInviteLink 콜백 함수가 호출 됩니다.

• shareItems state 값에 공유할 내용을 설정합니다.

• isShowingShareSheet state 값 변경을 통해 ShareSheet 노출 여부를 결정합니다.

// LauncherContentView.swift
import SwiftUI
import WebKit

struct LauncherContentView: View {
    ...
    // ShareSheet를 표시할 때 사용할 상태 변수
    @State private var isShowingShareSheet = false
    @State private var shareItems: [Any] = []
    
    var body: some View {
        LauncherWebView(
            url: URL(string: "런처 URL"),
            // 친구 초대 링크 공유 이벤트 핸들링 처리
            onSharedInviteLink: { inviteCode, infoMessage, link in
                // 공유할 항목 설정
                shareItems = ["\(infoMessage)\n\n초대코드 : \(inviteCode)\n\n\(link)"]
                // ShareSheet를 표시하도록 상태를 변경
                isShowingShareSheet = true
            },
        )
        .navigationBarBackButtonHidden(true)
        // ShareSheet를 표시하는 시트 추가
        .sheet(isPresented: $isShowingShareSheet) {
            ShareSheet(items: shareItems)
        }
    }
    ...
    
}

---

Flutter

🤝 OS 공유 시트 사용 시

1. 링크 공유 패키지 설치

아래 패키지를 설치하면 링크 공유 기능을 수행할 수 있습니다.

• 사용 패키지: share_plus

  • 해당 패키지는 플랫폼의 공유 대화상자를 통해 콘텐츠 공유를 가능하게 합니다.

flutter pub add share_plus

2. javascript handler 추가

런처를 사용하는 Screen 내 Javascript Handler 에 sharedInviteLink 타입을 추가합니다. handlerName 값은 BlpLauncher 로 설정해야 합니다.

Type	Description
sharedInviteLink	친구 초대 링크 공유 시 호출 inviteCode - 발급된 초대코드 infoMessage - 안내 메세지 link - 초대 링크

// lib/screens/bleepy_screen.dart
InAppWebView(
    key: webViewKey,
    initialUrlRequest:
        URLRequest(url: WebUri(widget.launcherUrl)),
    initialSettings: options,
    onWebViewCreated: (controller) {
        webViewController = controller;
        // 자바스크립트 핸들러 추가
        controller.addJavaScriptHandler(handlerName: 'BlpLauncher', callback: (message) {
            final data = jsonDecode(message[0]);
            final key = data['type'];
            switch (key) {
                ...
                // 추가
                case "sharedInviteLink":
                    sharedInviteLink(data["inviteCode"], data["infoMessage"], data["link"]);
                    break;
                default:
                    break;
            }
        });
    }
)

3. sharedInviteLink(inviteCode, infoMessage, link)

share_plus 패키지를 통해서 친구 초대 링크를 공유하는 기능을 수행합니다.

// lib/screens/bleepy_screen.dart
import 'package:share_plus/share_plus.dart';
// 친구초대 링크 공유하기
void sharedInviteLink(String infoMessage, String inviteCode, String link) async {
    try {
        // 메세지 예시
        const msg = "초대코드: $inviteCode\n$infoMessage\n$link"
        await Share.share(msg);
    } catch (error: any) {
        // Share API error
    }
}

🤝 카카오톡 공유 기능 사용 시

Flutter에서 카카오톡 공유 기능을 위해 추가적인 조치가 필요합니다. 카카오톡 실행 URL 오픈 시 필요한 아래 패키지를 설치해주세요.

flutter pub add url_launcher

flutter_inappwebview 내 shouldOverrideUrlLoading 에 아래 로직을 추가합니다.

• 기존 앱 존재 시 : 앱 실행

• 미설치 시 : 스토어 이동

...
import 'dart:io';
import 'package:url_launcher/url_launcher.dart';

InAppWebView(
  ...
  shouldOverrideUrlLoading: (controller, navigationAction) async {
    var uri = navigationAction.request.url!;
  
    if(Platform.isIOS) {
      // iOS - kakao
      if (uri.toString().startsWith("kakaolink://")) {
        if (await canLaunchUrl(uri)) {
          // KakaoTalk is installed, launch it
          await launchUrl(uri, mode: LaunchMode.externalApplication);
        } else {
          // KakaoTalk is not installed, redirect to App Store
          const appStoreUrl = "https://apps.apple.com/app/id362057947";
          await launchUrl(Uri.parse(appStoreUrl), mode: LaunchMode.externalApplication);
        }
  
        return NavigationActionPolicy.CANCEL;
      }
    }
  
    if(Platform.isAndroid) {
      // AOS - kakao
      if (uri.toString().startsWith("intent:")) {
        final fallbackUrl = Uri.tryParse(uri.queryParameters['browser_fallback_url'] ?? '');
  
        if (fallbackUrl != null && await canLaunchUrl(fallbackUrl)) {
          await launchUrl(fallbackUrl, mode: LaunchMode.externalApplication);
        } else {
          final kakaolinkUrl = uri.toString().replaceFirst("intent:", "");
  
          try {
            await launchUrl(Uri.parse(kakaolinkUrl), mode: LaunchMode.externalApplication);
          } catch (e) {
            print("Failed to launch KakaoLink URL: $e");
  
            // KakaoTalk is not installed, redirect to Google Play Store
            const appStoreUrl = "https://play.google.com/store/apps/details?id=com.kakao.talk";
            await launchUrl(Uri.parse(appStoreUrl), mode: LaunchMode.externalApplication);
          }
        }
        return NavigationActionPolicy.CANCEL;
      }
    }
  
    return NavigationActionPolicy.ALLOW;
  },
  ...
)

iOS 환경의 경우 Info.plist 파일 내 kakaolink 값을 추가해주세요.

// ios/Runner/Info.plist
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>kakaolink</string>
</array>

---

React Native

🤝 OS 공유 시트 사용 시

기본 제공되는 Share API 를 통해 친구 초대 링크를 공유하는 기능을 수행합니다. WebView 의 onMessage 함수 내에 해당 케이스를 추가합니다.

Type	Description
sharedInviteLink	친구 초대 링크 공유 시 호출되는 함수 inviteCode - 발급된 초대코드 infoMessage - 안내 메세지 link - 초대 링크

// src/screens/launcher/Launcher.tsx
import {WebView, WebViewMessageEvent} from 'react-native-webview';
export default function Launcher() {
    // WebView에서 보내온 메세지 처리
    const onMessage = (e: WebViewMessageEvent) => {
        const {type, inviteCode, infoMessage, link}
            = JSON.parse(e.nativeEvent.data);
        switch (type) {
            ...
            // 추가
            case 'sharedInviteLink':
                sharedInviteLink(inviteCode, infoMessage, link);
                break;
            }
        };
        return (
            <View>
                <WebView
                    ...
                    onMessage={onMessage}
                    ...
                />
            </View>
        );
    }
}

1. sharedInviteLink(inviteCode, infoMessage, link)

Share API 를 통해서 친구 초대 링크를 공유하는 기능을 수행합니다.

// src/screens/launcher/Launcher.tsx
import { Share } from 'react-native';
// 친구초대 링크 공유하기
const sharedInviteLink = async (inviteCode: string, infoMessage: string, link: string) => {
    try {
        // 메세지 예시
        const msg = '{infoMessage}\n초대코드 : {inviteCode}\n\n{link}'
        await Share.share({
            message: msg,
        });
    } catch (error: any) {
        // Share API error
    }
};

🤝 카카오톡 공유 기능 사용 시

React Native 앱으로 개발된 경우, 카카오톡 공유 기능을 위해 추가적인 조치가 필요합니다. 올바른 URL 스키마 처리를 위해 아래 패키지를 설치해주세요.

npm install react-native-url-polyfill

패키지 설치가 완료되면 WebView 관련 설정을 추가합니다.

• originWhiteList

• domStorageEnabled

• onShouldStartLoadWithRequest

handleShouldStartLoadWithRequest 메서드 내에서 AOS, iOS 플랫폼 별 처리를 진행합니다. 앱이 설치된 경우는 앱을 실행하고, 앱 미설치 시 스토어로 이동하게 됩니다.

import 'react-native-url-polyfill/auto';
import {Alert, Linking, Platform} from 'react-native';

export default function Launcher() {
  ...
  const handleShouldStartLoadWithRequest = (event: any): boolean => {
    const url = event.url;

    // 1. Android intent scheme process
    if (Platform.OS === 'android' && url.startsWith('intent:')) {
      const handleAndroidIntent = async () => {
        try {
          const kakaoUrl = url.replace('intent:', '');
          const fallbackUrl = new URLSearchParams(kakaoUrl).get(
            'browser_fallback_url',
          );
          const canOpen = await Linking.canOpenURL(kakaoUrl);

          if (canOpen) {
            // run KakaoTalk
            await Linking.openURL(kakaoUrl);
          } else if (fallbackUrl) {
            // move to fallback URL
            await Linking.openURL(fallbackUrl);
          } else {
            // move to Google Play Store
            const playStoreUrl =
              'https://play.google.com/store/apps/details?id=com.kakao.talk';
            await Linking.openURL(playStoreUrl);
          }
        } catch (error) {
          console.error('Error handling intent URL:', error);
        }
      };

      handleAndroidIntent();
      return false; // WebView load stop
    }
  
    // 2. IOS kakaolink process
    if (Platform.OS === 'ios' && url.startsWith('kakaolink://')) {
      const handleIosKakaoLink = async () => {
        try {
          const canOpen = await Linking.canOpenURL(url);
          if (canOpen) {
            await Linking.openURL(url);
          } else {
            const appStoreUrl = 'https://apps.apple.com/app/id362057947';
            await Linking.openURL(appStoreUrl);
          }
        } catch (error) {
          console.error('Error handling Kakao URL on iOS:', error);
        }
      };
      handleIosKakaoLink();
      return false; // WebView load stop
    }

    return true; // WebView load allow
  };
  ...

  return (
    <View>
      <WebView
        ref={webviewRef}
        source={{
          uri: route.params.url,
        }}
        originWhitelist={['kakaolink', 'intent', 'http', 'https']}
        javaScriptEnabled={true}
        domStorageEnabled={true}
        cacheEnabled={false}
        // 카카오톡 공유하기 처리
        onShouldStartLoadWithRequest={handleShouldStartLoadWithRequest}
      />
    </View>
  );
}

Android 추가 처리

AndroidManifest.xml 파일 내 수정이 필요합니다.

• <queries></queries> 선언을 통해 kakaolink 외부 intents를 명시합니다.

• <application> 및 <activity> 태그 내 android:exported 속성 값을 true로 설정합니다.

// android/app/src/main/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <!-- Declare queries for external intents -->
    <queries>
      <!-- KakaoTalk-specific intent -->
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="kakaolink" />
      </intent>
    </queries>

    <application
      ...
      android:exported="true">
      <activity
        ...
        android:exported="true">
        ...
      </activity>
    </application>
</manifest>

```

iOS

Info.plist 파일 내 kakaolink URL 스키마 추가가 필요합니다.

// ios/{projectName}/Info.plist
...
<!-- KakaoTalk URL Scheme Support -->
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>kakaolink</string>
</array>
...

---

Web

Web 도메인의 서비스인 경우 블리피 런처에서 기본적으로 Web Share API사용하게 됩니다.

친구 초대 미션 사용 시 임베디드 코드 내 유저의 회원가입 시점 추가 전달이 필요합니다.

Type	Description
signUpAt	신규 유저 판단을 위한 회원가입 일시를 전달해야 합니다. timestamp 형식 (10자리) ex) 1717143687

<!-- {signUpAt} 영역에 로그인된 회원의 회원가입 일시 전달 (timestamp) -->
<div style="height: 100%; max-width: 960px">
  <iframe
    src="https://web-launcher.bleepy.io?userKey={userKey}&secretKey={secretKey}&signUpAt={signUpAt}"
    style="overflow: hidden; width: 100%; height: 100%"
    allowfullscreen
    sandbox="allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox allow-top-navigation"
    id="bleepy-iframe"
    allow="web-share;clipboard-read; clipboard-write"
  />
</div>

개발에 대한 추가 설명이 더 필요하신가요?

"[Client Admin] 로그인 → 오른쪽 하단 채널톡 위젯" 클릭 후 개발 카테고리에 문의 남겨주시면 기술 개발팀에서 확인 후 연락드리겠습니다.