تنفيذ "إعلانات تقليص حجم الفيديو" (إصدار تجريبي)

Squeezeback

تُدرج إعلانات Squeezeback محتوى تطبيقك في عرض أصغر وتعرض إعلانًا مدمجًا مع المحتوى في المساحة المحيطة. يتيح هذا الشكل للمستخدمين التفاعل مع تطبيقك بينما يظل الإعلان مرئيًا. لعرض إعلانات صورية لا تغطي محتوى تطبيقك، اختَر هذا الشكل.

يتناول هذا الدليل كيفية طلب عرض إعلانات "squeezeback" في تطبيقك باستخدام GMA Next-Gen SDK.

قبل البدء

قبل المتابعة، عليك تنفيذ ما يلي:

تحميل إعلان

لتحميل كائن SqueezebackAd، يجب إنشاء طلب عرض الإعلان واستدعاء الطريقة load. يحفظ المثال التالي إعلان squeezeback الذي تم تحميله، ويسجّل لتلقّي أحداث الإعلانات، ويسجّل خطأً في حال تعذّر التحميل:

Kotlin

private fun loadSqueezebackAd() {
  val request = SqueezebackAdRequest.Builder(AD_UNIT_ID).build()

  SqueezebackAd.load(
    request,
    object : AdLoadCallback<SqueezebackAd> {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.w(TAG, "Squeezeback ad failed to load: $adError")
      }

      override fun onAdLoaded(ad: SqueezebackAd) {
        Log.d(TAG, "Squeezeback ad loaded.")

        // Capture the SqueezebackAd reference for later use.
        squeezebackAd = ad
        setAdEventCallback(ad)
      }
    },
  )
}

جافا

private void loadSqueezebackAd() {
  SqueezebackAdRequest request = new SqueezebackAdRequest.Builder(AD_UNIT_ID).build();

  SqueezebackAd.load(
      request,
      new AdLoadCallback<SqueezebackAd>() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.w(TAG, "Squeezeback ad failed to load: " + adError);
        }

        @Override
        public void onAdLoaded(@NonNull SqueezebackAd ad) {
          Log.d(TAG, "Squeezeback ad loaded.");

          // Capture the SqueezebackAd reference for later use.
          squeezebackAd = ad;
          setAdEventCallback(ad);
        }
      });
}

استبدِل AD_UNIT_ID بمعرّف وحدتك الإعلانية.

عرض الإعلان

لعرض إعلان "squeezeback" على الشاشة، استخدِم طريقة show:

Kotlin

private fun showSqueezebackAd(activity: Activity) {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = squeezebackAd
  if (ad != null) {
    ad.show(activity)
  } else {
    Log.d(TAG, "No ad to show.")
  }
}

جافا

private void showSqueezebackAd(@NonNull Activity activity) {
  // Use the ad reference saved from the onAdLoaded callback.
  if (squeezebackAd != null) {
    squeezebackAd.show(activity);
  } else {
    Log.d(TAG, "No ad to show.");
  }
}

ضبط لون الخلفية الاحتياطي

يعرض GMA Next-Gen SDK تلقائيًا خلفية رمادية داكنة خلف محتوى التطبيق والإعلان المصغّرَين. لتخصيص هذا اللون، حدِّد لون خلفية احتياطيًا في خيارات الإعلان عند عرضه. يضبط المثال التالي لون الخلفية الاحتياطي على الرمادي الداكن ويعرض الإعلان:

Kotlin

private fun showSqueezebackAdWithFallbackBackgroundColor(activity: Activity) {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = squeezebackAd
  if (ad != null) {
    val options =
      SqueezebackAdOptions.Builder()
        // Sets the fallback background color for the space behind the shrunken content and ad.
        .setFallbackBackgroundColor(Color.DKGRAY)
        .build()
    ad.show(activity, options)
  } else {
    Log.d(TAG, "No ad to show.")
  }
}

جافا

private void showSqueezebackAdWithFallbackBackgroundColor(@NonNull Activity activity) {
  // Use the ad reference saved from the onAdLoaded callback.
  if (squeezebackAd != null) {
    SqueezebackAdOptions options =
        new SqueezebackAdOptions.Builder()
            // Sets the fallback background color for the space behind the shrunken content and
            // ad.
            .setFallbackBackgroundColor(Color.DKGRAY)
            .build();
    squeezebackAd.show(activity, options);
  } else {
    Log.d(TAG, "No ad to show.");
  }
}

الاستماع إلى أحداث الإعلانات

للتعامل مع أحداث يتم في مراحل نشاط الإعلان في squeezeback، عليك التسجيل في أحداث الإعلانات قبل عرض إعلانك. تُبلغ هذه الأحداث عن التفاعلات مع الإعلانات، مثل النقرات ومرّات الظهور. تُبلغ هذه الأحداث أيضًا عن الأحداث المتعلّقة بـ squeezeback، مثل وقت ظهور الإعلان أو تعذُّر ظهوره أو إخفائه.

Kotlin

private fun setAdEventCallback(squeezebackAd: SqueezebackAd) {
  squeezebackAd.adEventCallback =
    object : SqueezebackAdEventCallback {
      override fun onAdShown() {
        Log.d(TAG, "Squeezeback ad shown.")
      }

      override fun onAdHidden() {
        // Called when hide() is invoked or the user taps the close button.
        // The ad cannot be shown again after it is hidden.
        Log.d(TAG, "Squeezeback ad hidden.")
      }

      override fun onAdFailedToShow(error: FullScreenContentError) {
        Log.w(TAG, "Squeezeback ad failed to show: $error")
      }

      override fun onAdImpression() {
        Log.d(TAG, "Squeezeback ad recorded an impression.")
      }

      override fun onAdClicked() {
        Log.d(TAG, "Squeezeback ad recorded a click.")
      }

      override fun onAdShowedFullScreenContent() {
        Log.d(TAG, "Squeezeback ad showed full screen content.")
      }

      override fun onAdDismissedFullScreenContent() {
        Log.d(TAG, "Squeezeback ad dismissed full screen content.")
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        Log.w(TAG, "Squeezeback ad failed to show full screen content: $fullScreenContentError")
      }

      override fun onAdPaid(value: AdValue) {
        Log.d(TAG, "Squeezeback ad paid: ${value.valueMicros} ${value.currencyCode}")
      }
    }
}

جافا

private void setAdEventCallback(@NonNull SqueezebackAd squeezebackAd) {
  squeezebackAd.setAdEventCallback(
      new SqueezebackAdEventCallback() {
        @Override
        public void onAdShown() {
          Log.d(TAG, "Squeezeback ad shown.");
        }

        @Override
        public void onAdHidden() {
          // Called when hide() is invoked or the user taps the close button.
          // The ad cannot be shown again after it is hidden.
          Log.d(TAG, "Squeezeback ad hidden.");
        }

        @Override
        public void onAdFailedToShow(@NonNull FullScreenContentError error) {
          Log.w(TAG, "Squeezeback ad failed to show: " + error);
        }

        @Override
        public void onAdImpression() {
          Log.d(TAG, "Squeezeback ad recorded an impression.");
        }

        @Override
        public void onAdClicked() {
          Log.d(TAG, "Squeezeback ad recorded a click.");
        }

        @Override
        public void onAdShowedFullScreenContent() {
          Log.d(TAG, "Squeezeback ad showed full screen content.");
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          Log.d(TAG, "Squeezeback ad dismissed full screen content.");
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.w(
              TAG,
              "Squeezeback ad failed to show full screen content: " + fullScreenContentError);
        }

        @Override
        public void onAdPaid(@NonNull AdValue value) {
          Log.d(
              TAG,
              "Squeezeback ad paid: " + value.getValueMicros() + " " + value.getCurrencyCode());
        }
      });
}

بعد أن يغلق المستخدم الإعلان، يستدعي GMA Next-Gen SDK حدث إخفاء الإعلان، ولن تتمكّن من عرض الإعلان مرة أخرى.

إخفاء الإعلان

لإزالة الإعلان واستعادة محتوى تطبيقك بالحجم الكامل، يمكنك استدعاء الطريقة hide. يستدعي هذا الإجراء حدث إخفاء الإعلان. يتحقّق المثال التالي من مرجع إعلان squeezeback محفوظ ويخفي الإعلان إذا كان متاحًا:

Kotlin

private fun hideSqueezebackAd() {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = squeezebackAd
  if (ad != null) {
    ad.hide()
  } else {
    Log.d(TAG, "No ad to hide.")
  }
}

جافا

private void hideSqueezebackAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (squeezebackAd != null) {
    squeezebackAd.hide();
  } else {
    Log.d(TAG, "No ad to hide.");
  }
}

حذف الموارد الإعلانية

لتجنُّب تسرُّب الذاكرة، تخلَّص من مرجعك إلى عنصر الإعلان عندما ينتهي تطبيقك من استخدام الإعلان. يزيل المثال التالي الإعلان:

Kotlin

private fun cleanUpSqueezebackAd() {
  squeezebackAd?.destroy()
  squeezebackAd = null
}

جافا

private void cleanUpSqueezebackAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (squeezebackAd != null) {
    squeezebackAd.destroy();
    squeezebackAd = null;
  }
}