Υλοποίηση διαφημίσεων εικόνας-εντός-εικόνας (beta)

Εικόνα-σε-εικόνα

Οι διαφημίσεις εικόνας-εντός-εικόνας (PiP) εμφανίζονται σε ένα αιωρούμενο παράθυρο που παραμένει πάνω από το περιεχόμενο της οθόνης, όπως άρθρα, ροές ή gameplay. Αυτή η μορφή επιτρέπει στους χρήστες να αλληλεπιδρούν με την εφαρμογή σας ενώ η διαφήμιση παραμένει ορατή. Για να εμφανίσετε διαφημίσεις που δεν καταλαμβάνουν ολόκληρη την οθόνη, επιλέξτε αυτήν τη μορφή. Μάθετε περισσότερα σχετικά με τις διαφημίσεις εικόνας-εντός-εικόνας .

Αυτός ο οδηγός καλύπτει την υποβολή αιτημάτων και την εμφάνιση διαφημίσεων picture-in-picture στην εφαρμογή σας χρησιμοποιώντας GMA Next-Gen SDK .

Πριν ξεκινήσετε

Πριν συνεχίσετε, κάντε τα εξής:

Φόρτωση διαφήμισης

Για να φορτώσετε ένα PictureInPictureAd , δημιουργήστε ένα αίτημα για διαφήμιση και καλέστε τη μέθοδο load :

Κότλιν 

private fun loadPictureInPictureAd() {
  val request = PictureInPictureAdRequest.Builder(AD_UNIT_ID).build()

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

      override fun onAdLoaded(ad: PictureInPictureAd) {
        Log.d(TAG, "Picture-in-Picture ad loaded.")

        // Capture the PictureInPictureAd reference for later use.
        pipAd = ad
        setAdEventCallback(ad)
      }
    },
  )
}

Ιάβα 

private void loadPictureInPictureAd() {
  PictureInPictureAdRequest request = new PictureInPictureAdRequest.Builder(AD_UNIT_ID).build();

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

        @Override
        public void onAdLoaded(@NonNull PictureInPictureAd ad) {
          Log.d(TAG, "Picture-in-Picture ad loaded.");

          // Capture the PictureInPictureAd reference for later use.
          pipAd = ad;
          setAdEventCallback(ad);
        }
      });
}

Αντικαταστήστε AD_UNIT_ID με το αναγνωριστικό ενότητας διαφημίσεών σας.

Εμφάνιση της διαφήμισης

Για να εμφανίσετε τη διαφήμιση εικόνας-εντός-εικόνας στην οθόνη, διαμορφώστε τις επιλογές εικόνας-εντός-εικόνας και καλέστε τη μέθοδο show . Το ακόλουθο παράδειγμα ορίζει την προεπιλεγμένη θέση της διαφήμισης και το εύρος παρουσίασης στην οθόνη:

Κότλιν 

private fun showPictureInPictureAd(activity: Activity) {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    val options =
      PictureInPictureAdOptions.Builder()
        // Uses the Google Mobile Ads SDK's default screen position.
        .setPosition(PictureInPictureAdPosition.DEFAULT)
        // Binds the ad lifecycle to the host screen.
        .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
        .build()
    ad.show(activity, options)
  } else {
    Log.d(TAG, "No ad to show.")
  }
}

Ιάβα 

private void showPictureInPictureAd(@NonNull Activity activity) {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    PictureInPictureAdOptions options =
        new PictureInPictureAdOptions.Builder()
            // Uses the Google Mobile Ads SDK's default screen position.
            .setPosition(PictureInPictureAdPosition.DEFAULT)
            // Binds the ad lifecycle to the host screen.
            .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
            .build();
    pipAd.show(activity, options);
  } else {
    Log.d(TAG, "No ad to show.");
  }
}

Ορίστε τη θέση

Από προεπιλογή, GMA Next-Gen SDK εμφανίζει μια διαφήμιση picture-in-picture στην κάτω δεξιά γωνία της οθόνης κατά την πρώτη εμφάνισή της ή στην τελευταία γνωστή θέση, εάν είχε εμφανιστεί προηγουμένως. Για να προσαρμόσετε το σημείο εμφάνισης της διαφήμισης, ορίστε τη θέση στις επιλογές picture-in-picture. Το ακόλουθο παράδειγμα ορίζει τη θέση πάνω από το περιεχόμενο στην επάνω αριστερή γωνία της οθόνης:

Κότλιν 

private fun createTopLeftPositionOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Sets the ad position to the top-left corner of the screen.
    .setPosition(PictureInPictureAdPosition.TOP_LEFT)
    .build()
}

Ιάβα 

private PictureInPictureAdOptions createTopLeftPositionOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Sets the ad position to the top-left corner of the screen.
      .setPosition(PictureInPictureAdPosition.TOP_LEFT)
      .build();
}

Για όλες τις διαθέσιμες θέσεις, ανατρέξτε PictureInPictureAdPosition .

Ορισμός του εύρους παρουσίασης

Από προεπιλογή, GMA Next-Gen SDK συνδέει μια διαφήμιση picture-in-picture στην τρέχουσα οθόνη κεντρικού υπολογιστή. GMA Next-Gen SDK απορρίπτει τη διαφήμιση όταν η ιεραρχία προβολής της οθόνης κεντρικού υπολογιστή δεν υπάρχει πλέον στη μνήμη. Για να διατηρήσετε τη διαφήμιση ορατή μετά την αφαίρεση της οθόνης κεντρικού υπολογιστή από τη μνήμη, ορίστε το εύρος παρουσίασης στην εφαρμογή:

Κότλιν 

private fun createApplicationScopedOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Keeps the ad visible beyond the host screen's lifecycle.
    .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
    .build()
}

Ιάβα 

private PictureInPictureAdOptions createApplicationScopedOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Keeps the ad visible beyond the host screen's lifecycle.
      .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
      .build();
}

Για περισσότερες πληροφορίες, ανατρέξτε στην ενότητα Διατήρηση της διαφήμισης ορατής σε όλες τις οθόνες .

Ορισμός της επιστροφής κλήσης συμβάντος διαφήμισης

Για να διαχειριστείτε συμβάντα κύκλου ζωής διαφημίσεων εικόνας σε εικόνα, ορίστε την επανάκληση συμβάντος στη διαφήμισή σας πριν από την εμφάνισή της. Αυτή η επανάκληση αναφέρει τυπικά συμβάντα, όπως κλικ και εμφανίσεις. Αυτή η επανάκληση αναφέρει επίσης συμβάντα που αφορούν συγκεκριμένα την εικόνα σε εικόνα, όπως πότε εμφανίζεται ή αποκρύπτεται η διαφήμιση:

Κότλιν 

private fun setAdEventCallback(pipAd: PictureInPictureAd) {
  pipAd.adEventCallback =
    object : PictureInPictureAdEventCallback {
      override fun onAdShown() {
        Log.d(TAG, "Picture-in-Picture ad shown.")
      }

      override fun onAdHidden() {
        Log.d(TAG, "Picture-in-Picture ad hidden.")
      }

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

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

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

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

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

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

Ιάβα 

private void setAdEventCallback(@NonNull PictureInPictureAd pipAd) {
  pipAd.setAdEventCallback(
      new PictureInPictureAdEventCallback() {
        @Override
        public void onAdShown() {
          Log.d(TAG, "Picture-in-Picture ad shown.");
        }

        @Override
        public void onAdHidden() {
          Log.d(TAG, "Picture-in-Picture ad hidden.");
        }

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

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

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

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

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

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

Απόκρυψη της διαφήμισης

Για να αφαιρέσετε την αιωρούμενη διαφήμιση από την οθόνη, καλέστε τη μέθοδο hide . Αυτή η μέθοδος καλεί την επανάκληση συμβάντος ad hidden:

Κότλιν 

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

Ιάβα 

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

Καθαρισμός διαφημιστικών πόρων

Για να αποφύγετε διαρροές μνήμης, αποσύρετε την αναφορά σας στο αντικείμενο διαφήμισης όταν η εφαρμογή σας ολοκληρώσει τη χρήση της διαφήμισης. Για παράδειγμα, όταν η εφαρμογή σας δεν εμφανίζει πλέον ή δεν αλληλεπιδρά ξανά με τη διαφήμιση. Για διαφημίσεις σε επίπεδο οθόνης, αποσύρετε την αναφορά όταν η εφαρμογή σας καταργήσει την οθόνη υποδοχής από τη μνήμη. Για διαφημίσεις σε επίπεδο εφαρμογής, διατηρήστε την αναφορά διαφήμισης ενώ ο χρήστης πλοηγείται σε οθόνες και αποσύρετε την αναφορά όταν ο χρήστης απορρίψει τη διαφήμιση:

Κότλιν 

private fun cleanUpPictureInPictureAd() {
  pipAd?.destroy()
  pipAd = null
}

Ιάβα 

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

Διατηρήστε την διαφήμιση ορατή σε όλες τις οθόνες

Όταν ορίζετε το εύρος παρουσίασης στην εφαρμογή, η διαφήμιση εικόνας-εντός-εικόνας παραμένει ορατή ακόμα και όταν η εφαρμογή σας καταργήσει την οθόνη φιλοξενίας από τη μνήμη. Για να αλληλεπιδράσει με ή να παραβλέψει τη διαφήμιση όταν ο χρήστης απομακρύνεται από την οθόνη φιλοξενίας, η εφαρμογή σας πρέπει να διατηρήσει την πρόσβαση στη διαφήμιση εικόνας-εντός-εικόνας. Συνιστούμε να διατηρείτε τη διαφήμιση σε ένα singleton σε επίπεδο εφαρμογής ή σε έναν κοινόχρηστο διαχειριστή κατάστασης αντί για τη μεταβλητή παρουσίας μιας μόνο οθόνης.

Για ένα παράδειγμα του πώς να διατηρήσετε μια διαφήμιση ορατή σε όλες τις οθόνες, δείτε τα δείγματα εφαρμογών μας: