이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Android용 AFS 네이티브 구현

Google 모바일 광고 SDK는 검색 광고 맞춤 스타일도 지원합니다. 앱에서 이미 Google 모바일 광고 SDK를 사용하는 경우 AFSMA SDK 버전을 대신 사용하는 것이 좋습니다.

18.1.0 이하에서 버전 19.0.0 이상으로 업그레이드하는 경우 이전 가이드를 참조하세요.

기본 요건

이 구현 가이드에서는 다음 사항에 대해 잘 알고 있다고 가정합니다.

검색 광고 맞춤 스타일을 사용하는 애드센스 맞춤 검색 광고
Android 앱 개발

AFS Native SDK 가져오기

SDK 추가

앱에 AFS Native SDK를 추가하려면 다음 단계를 따르세요.

애플리케이션 모듈 디렉터리 내에서 build.gradle 파일을 엽니다. dependencies 아래에 최신 버전의 SDK에 대한 새 빌드 규칙을 추가합니다.

dependencies {
  implementation 'com.google.android.gms:play-services-afs-native:19.0.3'
}

최상위 수준 build.gradle에 google() 저장소 또는 maven { url "https://maven.google.com" }에 대한 참조가 포함되어 있는지 확인합니다.

프로젝트에 Google Play 독립형 버전 매처 플러그인을 포함하려면 이 안내를 따르세요. 이 플러그인을 적용하면 AFS Native SDK가 호환되지 않는 버전의 Google Play 서비스와 함께 사용될 때 앱이 빌드되도록 허용하지 않고 런타임 비정상 종료를 일으킬 가능성이 있는 경우 Gradle 빌드 오류가 발생합니다. 또는 프로젝트에 failOnVersionConflict() ResolutionStrategy를 적용하여 프로젝트에 호환되지 않는 Google Play 서비스 버전이 사용될 때 빌드 오류가 발생하도록 합니다. 변경사항을 저장하고 툴바에서 Sync Project with Gradle Files를 클릭합니다.

Android 지원 라이브러리 대신 AndroidX 사용

SDK 버전 17.0.0부터는 앱에서 Android 지원 라이브러리 대신 Jetpack (AndroidX) 라이브러리를 사용해야 합니다. 호환성 요구사항:

com.android.tools.build:gradle을 v3.2.1 이상으로 설정합니다.
compileSdkVersion을 28 이상으로 설정합니다.
Jetpack (AndroidX)을 사용하도록 앱을 업데이트합니다. AndroidX로 이전의 안내를 따릅니다.

클래스

앱에 AFS 네이티브 광고를 게재하려면 다음 클래스를 구현합니다.

SearchAdController

이 클래스는 광고를 비동기식으로 요청하고, 광고를 캐시 및 검색하고, 렌더링하는 역할을 합니다.
각 광고 컨텍스트에는 별도의 SearchAdController가 필요합니다. 예를 들어 검색결과 목록과 함께 광고를 표시하는 화면과 특정 제품의 세부정보와 함께 광고를 표시하는 화면이 있는 경우 사례마다 하나씩 SearchAdController의 개별 인스턴스 두 개를 만들어야 합니다.
생성자에는 웹 속성 코드 (게시자 ID), 반환된 광고에 적용할 스타일 ID 및 SearchAdOptions가 제공되어야 합니다. 생성자에 제공된 Context는 SearchAdController를 포함하고 광고 View를 게재할 위치인 Activity여야 합니다.
loadAds를 호출하여 신규 사용자 검색을 나타내고 비동기 광고 요청을 시작합니다. loadAds에 대한 이전 호출에서 로드된 광고는 새 호출이 발생할 때 내부 광고 캐시에서 삭제됩니다.
createAdView로 View를 만들어 광고 소재를 표시합니다.
광고가 로드되면 이전에 createAdView로 생성된 View로 populateAdView를 호출하여 캐시된 광고를 해당 View로 렌더링합니다. 채워질 View 외에, 광고를 고유하게 식별하는 임의의 문자열인 adKey를 제공하세요. 이렇게 하면 캐시에서 반환된 특정 광고 소재가 adKey와 연결되므로 향후 populateAdView 호출에 동일한 adKey가 전달되면 동일한 광고가 반환됩니다. 예를 들어 populateAdView가 adKey="keyA"로 처음 호출되어 하이킹 부츠 광고를 렌더링하는 경우 adKey="keyA"를 사용한 populateAdView를 호출할 때마다 동일한 하이킹 부츠 광고가 게재됩니다. loadAds를 새로 호출하면 캐시된 광고 및 연결된 광고 키가 모두 삭제됩니다.

SearchAdOptions

이 객체를 SearchAdController 생성자에 전달하여 광고가 요청되고 표시되는 방식을 맞춤설정합니다. SearchAdOptions.Builder에서 build()를 호출하여 SearchAdOptions 객체를 만듭니다.

View

SearchAdController에서 createAdView()를 호출하여 광고를 포함할 View 객체를 만듭니다. 한 번에 최대 1개의 광고를 표시하지만 동일한 View를 재활용하여 시간이 지남에 따라 다양한 광고를 표시할 수 있습니다.

SearchAdRequest

SearchAdRequest로 SearchAdController에서 loadAds 메서드를 호출하여 비동기 광고 요청을 시작합니다. SearchAdRequest.Builder에서 build()를 호출하여 SearchAdRequest 객체를 만듭니다.

AdListener

이 인터페이스를 구현하고 SearchAdController 생성자에 전달하여 여러 상태의 콜백을 등록합니다.
참고: 취소된 요청 (첫 번째 호출이 해결되기 전에 다른 loadAds 호출로 선점된 loadAds 호출)에서는 AdListener 콜백이 호출되지 않습니다.

구현 예시

아래 예는 샘플 Activity에서 SearchAdController를 만드는 방법을 보여줍니다.

//  MainActivity.java implementation
//  (MainActivity is a subclass of Activity)

SearchAdController adController;
// adContainer where we will place our ads in this example.
ViewGroup adContainer;

protected void onCreate(Bundle bundle){
  super.onCreate(bundle);
  adContainer = (ViewGroup) findViewById(...);
  // Specify ad options (not required).
  SearchAdOptions.Builder adOptionsBuilder = new SearchAdOptions.Builder();
  adOptionsBuilder.setAdType(SearchAdOptions.AD_TYPE_TEXT);
  adOptionsBuilder.setPrefetch(true);
  adOptionsBuilder.setNumAdsRequested(3);
  // Provide a callback to trigger when ads are loaded.
  AdListener adListener = new AdListener() {
    public void onAdLoaded() {
      createAndShowAd();
    }
  };
  // Instantiate the SearchAdController.
  adController = new SearchAdController(this, "your-client-id", "your-style-id",
                                        adOptionsBuilder.build(), adListener);
}

사용자가 쿼리를 시작하면 SearchAdRequest를 만들고 SearchAdController에서 loadAds를 호출하여 비동기 광고 요청을 시작합니다.

// Create the request.
SearchAdRequest.Builder requestBuilder = new SearchAdRequest.Builder();
requestBuilder.setQuery("user query here");
// Load the ads.
adController.loadAds(requestBuilder.build());

onAdLoaded 콜백을 구현하여 로드된 광고를 광고 뷰에 채웁니다.

private void createAndShowAd() {
  // Create a new view that will contain the ad.
  View adView = adController.createAdView();
  // Attach the new view to the view hierarchy.
  adContainer.addView(adView);
  // Display the ad inside the adView. We need to provide an adKey to
  // indicate which ad is to be displayed in the adView. In this example, 
  // since we only have one ad, we can provide any constant string. However, 
  // if you intend to display multiple ads, each ad you wish to display
  // should be given a unique adKey of your choosing.
  adController.populateAdView(adView, "demoAd");
}

지정한 검색어와 관련된 광고가 adView에 표시됩니다.

오류 조사

SearchAdController에는 onAdLoaded() 메서드가 있는 AdListener 객체가 있어야 광고를 표시할 준비가 되었음을 앱에 알릴 수 있습니다. 또한 오류를 감지하고 수정할 수 있도록 onAdFailedToLoad() 메서드를 구현해야 합니다. 예를 들어 다음 AdListener를 사용하여 구현을 디버그할 수 있습니다.

AdListener adListener = new AdListener() {
    public void onAdLoaded() {
        // Called when an ad is loaded.
        Toast.makeText(MainActivity.this, "Ad Loaded",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example).
        Toast.makeText(MainActivity.this, "Ad Left Application",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
    }

    @Override
    public void onAdFailedToLoad(int errorCode) {
        // Called when an ad request failed.
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
};

onAdFailedToLoad() 콜백 메서드에서 사용되는 상수는 AdListener에서 정의됩니다.