WebView 직접 연동

애드팝콘 SSP SDK 연동 없이 URL만을 이용하여 연동하고자 할 때 사용되는 가이드입니다.

• 변경 사항

  • 2025-04-18

    • flutter_webview 환경 내에서의 직접 연동 방식 가이드 추가

  • 2025-02-19

    • 2.2 Interfaces 내, 2.2.5 pushUrl api 설정 추가 및 샘플 코드 내, pushUrl 처리 로직 추가

1. Landing URL 내 파라미터 설정

애드팝콘 SSP 사업팀으로부터 전달 받은 URL에 포함된 매크로를 직접 치환한 뒤, 웹뷰로 URL을 호출해 주어야 합니다. 이벤트 페이지 주소는 팝콘텐츠에 따라 조금씩 다르지만, 파라미터 구조는 동일합니다.

https://reward-webview.adpopcornpopcontents.com/fortune/?userId={USN}&clientSessionId={CLIENT_SESSION_ID}&pageId=1

• userId : 매체의 앱키와 이벤트 페이지에서 발생하는 리워드를 지급 받을 유저의 unique한 id를 조합하여 id가 생성됩니다. 앱키는 애드팝콘 SSP 사업실로부터 전달 받을 수 있습니다.

  • android, ios

    • {appKey}:{USN}

      • 800296516:test_user_id

• clientSessionId

  • android

    • adid:{adid}

      • adid:08283f4e-2094-4e96-94e5-5b95b536827d

  • ios

    • idfa:{idfa}

      • idfa:99ED0000-75E0-43BD-BB25-8AE5A61B6437

위 조건에 따라 매크로 치환을 할 경우 아래와 같은 랜딩 URL이 나오게 됩니다.

https://reward-webview.adpopcornpopcontents.com/fortune/?userId=800296516:test_userId&clientSessionId=adid:08283f4e-2094-4e96-94e5-5b95b536827d&pageId=1

2. 웹뷰 내 JavascriptInterface 설정

이벤트 페이지의 원활한 동작을 위해 아래 가이드를 참고하여 JavascriptInterface 설정을 진행해 주어야 합니다.

2.1 공통 사항

• 호출은 nativeBridge 객체로 호출합니다. 이에 아래와 같이 각 OS 환경에 맞게 nativeBridge를 등록해 주어야 합니다. 단, flutter_inappwebview 사용 시에는 nativeBridge가 아닌, 각 func 이름으로 각각 handlerName을 등록해야 합니다.

Android

webView = new WebView(context.getApplicationContext());
webView.addJavascriptInterface(this, "nativeBridge");

iOS

flutter_inappwebview

webview_flutter

• 이벤트 페이지에서 기기별 호출 형식은 아래와 같습니다.

Android

window.nativeBridge.fncName() // -> no params
window.nativeBridge.fncName(JSON.stringify({
    params: { ,,, } // -> params
}))

iOS

flutter_inappwebview

webview_flutter

• 인터페이스에 대한 콜백은 nativeCallback 객체로 호출합니다.

window.nativeCallback.fncName()

2.2 Interfaces

2.2.1 onPageLoaded()

• 설명 : 웹뷰가 정상적으로 로드 되었음을 확인합니다.

• 콜백 : onPageLoaded()가 호출된 이후에 웹뷰 로드 성공 여부를 콜백으로 전달해 주어야 합니다.

// AOS
window.nativeBridge.onPageLoaded()

// iOS
window.webkit.messageHandlers.nativeBridge.postMessage(JSON.s
    fncName: "onPageLoaded"
}))

/**
* 웹뷰 로드 성공 여부를 '0', '1'로 구분하여 SDK에서 onPageLoaded 콜백
* @Param {('0' | '1')} success 성공 여부
*/
window.nativeCallback.onPageLoaded = (success: '0' | '1') =>
// '0': 로드 실패
// '1': 로드 성공
}

2.2.2 finish()

• 설명 : 현재 웹뷰를 종료합니다.

• 콜백 : 콜백 없음

// AOS
window.nativeBridge.finish()

// iOS
window.webkit.messageHandlers.nativeBridge.postMessage(JSON.s
    fncName: "finish"
}))

2.2.3 openExternalBrowser()

• 설명 : 외부 브라우저를 엽니다.

• 콜백 : 콜백 없음

// AOS
window.nativeBridge.openExternalBrowser("https://,,,")

// iOS
window.webkit.messageHandlers.nativeBridge.postMessage(JSON.s
    fncName: "openExternalBrowser",
    params: {
        url: "https://,,,"
    }
}))

2.2.4 registerBackKeyListener() - AndroidOnly

• 설명 : 디바이스 back key 동작 여부를 설정합니다. (안드로이드 디바이스에서만 사용됨)

• 콜백 : 없음

// AOS
window.nativeBridge.registerBackKeyListener()
/**
* 벡키 권한 전달 성공 여부를 '0', '1'로 구분하여 SDK에서 registerBack
* @param {('0' | '1')} success 성공 여부
*/
window.nativeCallback.registerBackKeyListener = (success: '0
// '0': Back Key 권한 얻지 못함
// '1': Back Key 권한 얻음
}
/**
* Back Key 이벤트 발생시 SDK에서 onBackKeyPress 콜백을 호출합니다.
*/
window.nativeCallback.onBackKeyPress()

2.2.5 pushUrl()

• 설명 : 현재 인앱 브라우저의 웹뷰 url을 변경합니다.

• 콜백 : 없음

• param

  • url: 변경될 url

  • replace(optional): 현재 인앱 브라우저 웹뷰의 history 스택 쌓을지 혹은 교체할지에 대한 옵션

    • replace는 옵셔널이며 디폴트 값은 false 입니다.

    • replace 값 false인 경우 현재 인앱 브라우저의 history 스택에 변경될 url을 쌓으면서 이동합니다

    • replace 값 true인 경우 현재 인앱 브라우저의 history 스택에 변경될 url로 교체하면서 이동합니다

// AOS
window.nativeBridge.pushUrl(JSON.stringify({
  url: "https://,,,",
  replace: true
}))

// iOS
window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({
	fncName: "pushUrl",
	params: {
		url: "https://,,,",
		replace: true
	}
}))

2.3 광고 클릭에 대한 이벤트 처리 추가

팝콘텐츠 이벤트 페이지 내, 스크립트로 동작하는 광고에 대한 클릭 처리 추가가 필요합니다.

아래 설정이 누락될 경우, 광고 클릭 시, 웹뷰 내에서 광고 페이지로 랜딩됩니다.

특히나, 외부 브라우저로 광고가 넘어가기 전, 실제로 유저의 클릭이 발생했는지에 대한 조건 처리가 필요합니다. 해당 처리가 누락되어 있을 경우 일부 광고에서 유저의 클릭 없이도 외부 페이지로 넘어갈 수 있습니다.

Android

// Android의 경우 웹뷰에 TouchListener를 연결하여, 유저가 실제로 touch 했는지를 체크 한 뒤, 
// 해당 flag 값을 클릭 이벤트 처리에서 활용합니다.
private boolean mIsClicked = false;

private void setWebViewSetting(){
      webView = new WebView(context.getApplicationContext());
      webView.addJavascriptInterface(this, "nativeBridge");
      webView.setOnTouchListener(mOnTouchListener);
}

private View.OnTouchListener mOnTouchListener = new View.OnTouchListener() {
      private float startX;
      private float startY;
      private int CLICK_ACTION_THRESHOLD = 200;
      
      @Override
      public boolean onTouch(View v, MotionEvent event) {
	switch (event.getAction()) {
	      case MotionEvent.ACTION_DOWN:
		startX = event.getX();
		startY = event.getY();
		break;
	      case MotionEvent.ACTION_UP:
		float endX = event.getX();
		float endY = event.getY();
		if (isAClick(startX, endX, startY, endY)) {
		      mIsClicked = true;
		}
		break;
	}
	return false;
      }

      private boolean isAClick(float startX, float endX, float startY, float endY) {
	float differenceX = Math.abs(startX - endX);
	float differenceY = Math.abs(startY - endY);
	if (differenceX > CLICK_ACTION_THRESHOLD/* =5 */ || differenceY > CLICK_ACTION_THRESHOLD) {
	      return false;
	}
	return true;
      }
};

private WebViewClient mWebViewClient = new WebViewClient(){
      @Override
      public boolean shouldOverrideUrlLoading(final WebView view, WebResourceRequest request) {
            try {
                  String url;
                  if (Build.VERSION.SDK_INT >= 21) {
                        url = request.getUrl().toString();
                  } else {
                        url = view.getUrl();
                  }
                  return urlLoading(view, url);
            } catch (Exception e) {
                  e.printStackTrace();
                  return false;
            }
      }

      @Override
      public boolean shouldOverrideUrlLoading(final WebView view, final String url) {
            try {
                  return urlLoading(view, url);
            } catch (Exception e) {
                  e.printStackTrace();
                  return false;
            }
      }

      @Override
      public void onPageFinished(final WebView view, String url) {
         super.onPageFinished(view, url);
      }
      
      private boolean urlLoading(WebView view, String url) {
            if (mIsClicked && url != null) {
                  mIsClicked = false;
                  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));
                  intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                  context.startActivity(intent);
                  return true;
             } else {
                  view.loadUrl(url);
                  return false;
            }
      }
};

iOS

flutter_inwebappview

webview_flutter

2.4 Sample Code

아래 플랫폼별 샘플 코드는 2.2 Interfaces 구현과 관련된 사항만 간략히 작성해둔 코드이며, 이에 아래 코드를 참고하여 개발 환경에 맞게 세팅하면 됩니다.

Android

public class AdPopcornSSPPopContentsAdActivity extends Activity{
   private boolean enableOnPageCallback = false;
   private boolean enableBackKeyCallback = false;
   private final String REGISTER_BACKKEY_ON_SCRIPT = "window.nativeCallback.registerBackKeyListener('1')";
   private final String REGISTER_BACKKEY_OFF_SCRIPT = "window.nativeCallback.registerBackKeyListener('0')";
   private final String PRESS_BACKKEY_SCRIPT = "window.nativeCallback.onBackKeyPress()";
   private final String ON_PAGE_LOADED_SCRIPT = "window.nativeCallback.onPageLoaded('1')";
   private Boolean isNeedToClearHistory = false;
   private boolean mIsClicked = false;
   
   @Override
   protected void onCreate(Bundle savedInstanceState) {
      // TODO Auto-generated method stub
      super.onCreate(savedInstanceState);
      
      webView= new NonLeakingWebView(context.getApplicationContext());
      webView.getSettings().setJavaScriptEnabled(true);
      webView.setWebViewClient(mWebViewClient);
      webView.addJavascriptInterface(this, "nativeBridge");
      webView.setOnTouchListener(mOnTouchListener);
   }
   
   // Android의 경우 웹뷰에 TouchListener를 연결하여, 유저가 실제로 touch 했는지를 체크 한 뒤, 
   // 해당 flag 값을 클릭 이벤트 처리에서 활용합니다.
   private View.OnTouchListener mOnTouchListener = new View.OnTouchListener() {
      private float startX;
      private float startY;
      private int CLICK_ACTION_THRESHOLD = 200;
      
      @Override
      public boolean onTouch(View v, MotionEvent event) {
	switch (event.getAction()) {
	      case MotionEvent.ACTION_DOWN:
		startX = event.getX();
		startY = event.getY();
		break;
	      case MotionEvent.ACTION_UP:
		float endX = event.getX();
		float endY = event.getY();
		if (isAClick(startX, endX, startY, endY)) {
		      mIsClicked = true;
		}
		break;
	}
	return false;
      }

      private boolean isAClick(float startX, float endX, float startY, float endY) {
	float differenceX = Math.abs(startX - endX);
	float differenceY = Math.abs(startY - endY);
	if (differenceX > CLICK_ACTION_THRESHOLD/* =5 */ || differenceY > CLICK_ACTION_THRESHOLD) {
	      return false;
	}
	return true;
      }
   };
   
   @JavascriptInterface
   public void onPageLoaded() {
      try {
         enableOnPageCallback = true;
      }catch(Exception e){}
   }
   
   @JavascriptInterface
   public void finish() {
      try {
         super.finish();
      }catch(Exception e){}
   }
   
   @JavascriptInterface
   public void openExternalBrowser(String url){
      try{
         Intent openBrowser = new Intent(Intent.ACTION_VIEW);
         Uri u = Uri.parse(url);
         openBrowser.setData(u);
         context.startActivity(openBrowser);
      }catch(Exception e){}
   }
   
   @JavascriptInterface
   public void registerBackKeyListener(){
      try{
         enableBackKeyCallback = true;
         callJavascript(REGISTER_BACKKEY_ON_SCRIPT);
         return;
      }catch(Exception e){}
      callJavascript(REGISTER_BACKKEY_OFF_SCRIPT);
   }
   
   @JavascriptInterface
   public void pushUrl(String url, boolean replace){
      try{   	
   	nonLeakingWebView.post(new Runnable() {
   	   @Override
   	   public void run() {
   	      nonLeakingWebView.loadUrl(url);
   	      if(replace)
                  isNeedToClearHistory = true;
   	      else
   	          isNeedToClearHistory = false;
   				}
   	   });
     }catch(Exception e){}
   }

   
   @Override
   public void onBackPressed() {
       try {
          if(enableBackKeyCallback) {
             callJavascript(PRESS_BACKKEY_SCRIPT);
          }
          else{
             super.onBackPressed();
          }
       }catch (Exception e){e.printStackTrace();}
   }
   
   public void callJavascript(final String script){
      try {
         if(webView!= null){
            webView.post(new Runnable() {
               @Override
               public void run() {
                  webView.evaluateJavascript(script, null);
               });
         }
      }catch(Exception e){}
   }

   private WebViewClient mWebViewClient = new WebViewClient(){
      @Override
      public boolean shouldOverrideUrlLoading(final WebView view, WebResourceRequest request) {
            try {
                  String url;
                  if (Build.VERSION.SDK_INT >= 21) {
                        url = request.getUrl().toString();
                  } else {
                        url = view.getUrl();
                  }
                  return urlLoading(view, url);
            } catch (Exception e) {
                  e.printStackTrace();
                  return false;
            }
      }

      @Override
      public boolean shouldOverrideUrlLoading(final WebView view, final String url) {
            try {
                  return urlLoading(view, url);
            } catch (Exception e) {
                  e.printStackTrace();
                  return false;
            }
      }

      @Override
      public void onPageFinished(final WebView view, String url) {
         super.onPageFinished(view, url);
         if(!isPageLoaded && enableOnPageCallback)
            callJavascript(ON_PAGE_LOADED_SCRIPT);
         isPageLoaded = true;
         if(isNeedToClearHistory)
            nonLeakingWebView.clearHistory();
         isNeedToClearHistory = false;
      }
      
      private boolean urlLoading(WebView view, String url) {
         if (mIsClicked && url != null) {
            mIsClicked = false;
            Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
            context.startActivity(intent);
            return true;
         } else {
            view.loadUrl(url);
            return false;
         }
      }
   };
} // end of AdPopcornSSPPopContentsAdActivity

iOS

flutter_inappwebview

webview_flutter