Loslegen mit Vungle – Windows SDK v.5.1+

Nutzen Sie diesen Leitfaden, um unser SDK einfach in Ihre Apps zu integrieren und um mit der Monetarisierung zu beginnen.

<p>Die Code-Beispiele in diesem Leitfaden sind in C#. Beispiel-App-Dateien in C#, C++, Visual Basic und DirectX+XAML finden Sie in unsererGitHub Repository.

Inhalt

Bevor Sie anfangen

  • Dieser Leitfaden ist für das Vungle Windows SDK 5.1 oder neuer. Den Leitfaden zur Integration des Vungle Windows SDK Version 1.3.16 und älter finden Sie hier: Loslegen mit Vungle – Windows SDK V. 1.0 – V.1.3.16.
  • Für die Integration ist ein Vungle-Konto erforderlich; daher müssen Sie einen Vungle-Konto erstellen, wenn Sie noch keines besitzen.
  • Navigieren Sie zu unserem Dashboard und fügen Sie Ihre App Ihrem Konto hinzu, falls Sie dies noch nicht getan haben. Sehen Sie im Abschnitt Einrichtung von und Berichte über Platzierungen nach, um mehr über die Einrichtung von Platzierungen im Vungle Dashboard zu erfahren.
  • Sie müssen Visual Studio 2015 verwenden, falls Sie für Windows 8.1 und Windows Phone 8.1 entwickeln, da Visual Studio 2017 diese Versionen nicht mehr unterstützt.
  • Die Zurück-Schaltfläche wird auf Mobilgeräten aber nicht auf PCs (Tastatur) unterstützt. Dies kann bei UWP-Builds zu einem Unterschied hinsichtlich des Verhaltens und des Benutzererlebnisses führen.
  • Bitte wechseln Sie Ihre Anwendung in den aktiven Modus, falls im Testmodus keine Werbungen zurückgegeben werden.

Laden Sie das SDK herunter und fügen Sie VungleSDK zu Ihrem Projekt hinzu

  1. Laden Sie das Vungle Windows SDK aus dem Vungle Dashboard herunter.
  2. Extrahieren Sie das Archiv.
  3. Erstellen Sie in Visual Studio mit Hilfe der für Ihre Anwendung und Programmiersprache passenden Vorlage ein neues Projekt.
  4. Ergänzen Sie die Vungle Windows SDK-Datei, die Sie heruntergeladen haben, mit einer Referenz auf Ihr Projekt.
  5. Stellen Sie sicher, dass Ihr Projekt wie dargestellt über die internetClient-Fähigkeit in der package.appxmanifest-Datei verfügt:
    <Capabilities>
    ...
    <Capability Name="internetClient" />
    ...
    </Capabilities>
  6. Importieren Sie den VungleSDK-Namespace.
    using VungleSDK;
    

Beziehen einer VungleAd-Instanz

Die VungleAd-Instanz nimmt zwei Parameter an: einen String für Ihre Vungle App-ID und ein Array von Strings für Platzierungs-IDs. Sie können nur solche Platzierungs-IDs verwenden, die Sie beim Beziehen dieser Instanz bereits miteinbezogen haben. Wenn Sie nicht eine automatisch gecachte Platzierung miteinbeziehen, weist das SDK automatisch eine Ihrer nicht automatisch gecachten Platzierungen als automatisch gecacht zu.

VungleAd sdkInstance;

string appID = “app_id”;
string[] placementArray = new string[]
{
  “placement_id_1”,
  “placement_id_2”,
  “placement_id_3”
};
sdkInstance = AdFactory.GetInstance(appID, placementArray);

Ersetzen Sie im obenstehenden Beispiel app_id mit Ihrer Vungle-App-ID und placement_id_# mit der Platzierungs-ID, die in Ihrem Projekt verwendet werden sollen. Wir empfehlen Ihnen die Durchführung dieser Initialisierungsschritte sofort nach Abschluss des Ladens wichtiger Komponenten durch Ihre App, sodass früher mit dem automatischen Cachen begonnen werden kann.

Erstellen und Registrieren eines Event-Handlers

Erstellen Sie einen Event-Handler für das Event OnAdPlayableChanged. Dieser Event-Handler wird gerufen, wenn der Status der Werbungsverfügbarkeit sich ändert. Sie können durch Prüfen von e.Placement die Platzierung identifizieren, die das Event ausgelöst hat.

//Event-Handler für das OnAdPlayableChanged-Event
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
  // e.Placement  – Platzierungs-ID als String
  // Im UI-Thread asynchron ausführen
  await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
    new DispatchedHandler(() => methodToRun(e.Placement)));
}

Registrieren Sie einen Event-Handler für das Event OnAdPlayableChanged.

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;

Laden einer Werbung für eine Platzierung

Bei Platzierungen außer der automatisch gecachten Platzierung müssen Sie zuerst LoadAd rufen, ausreichend Zeit zum Herunterladen der Assets gewähren und dann auf das Rufen von OnAdPlayableChanged warten:

sdkInstance.LoadAd(“placement_id”);

Hinweis: Die automatisch gecachte Platzierung versucht sofort nach dem Rufen von PlayAdAsync ein neues Werbe-Asset herunterzuladen, weshalb LoadAd nicht gerufen werden muss.

Beispielcode:

private void OnLevelStart(Object sender, RoutedEventArgs e)
{
  sdkInstance.LoadAd(“placement_id”);
}

Abspielen einer Werbung

Abspielen einer Werbung mit der Standardkonfiguration:

sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”);

Beispielcode:

private async void OnLevelComplete(Object sender, RoutedEventArgs e)
{
  await sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”);
}

Optional können Sie die abzuspielenden Werbungen anpassen, indem Sie dem AdConfig-Objekt Optionen zur Verfügung stellen.

Beispielcode:

private async void PlayCustomizedAd(Object sender, RoutedEventArgs e)
{
  AdConfig adConfig = new AdConfig();

  adConfig.Orientation = DisplayOrientations.Portrait;
  adConfig.SoundEnabled = false;
  
  await sdkInstance.PlayAdAsync(adConfig, placement2);
}

Anpassungsoptionen

Dies sind die verfügbaren Eigenschaften in der AdConfig-Objektinstanz:

Optionen

Standardwert/
Typ

Beschreibung

Orientation

AutoRotate

DisplayOrientations

Orientation.AutoRotate (Standard) bedeutet, dass die Werbung automatisch entsprechend der Ausrichtung des Geräts rotiert wird.

Orientation.Portrait sorgt dafür, dass die Werbung nur im Hochformat abgespielt wird.

Orientation.Landscape sorgt dafür, dass die Werbung nur im Querformat abgespielt wird.

Hinweis: Diese Option betrifft nur Mobilanwendungen.

SoundEnabled

true

bool

Legt den anfänglichen Audiozustand für die Werbung fest.

Bei "true" (Standard) erfolgt die Audiowiedergabe mit der Lautstärke und den Audioeinstellungen, die auf dem Gerät eingestellt sind.

Bei "false" ist das Video bei Beginn der Wiedergabe zunächst stummgeschaltet. Dies kann aber vom Nutzer geändert werden.

BackButtonImmediatelyEnabled

false

bool

Bei "true" kann der Nutzer eine Werbung unmittelbar mit der Schaltfläche "Zurück" verlassen.

Bei "false" (Standard) kann der Nutzer die Werbung erst dann mit der Schaltfläche "Zurück" verlassen, wenn die Schaltfläche "Schließen" auf dem Bildschirm angezeigt wird.

Hinweis: Diese Option betrifft nur Mobilanwendungen.

UserId

null

string

Gibt die eindeutige Nutzer-ID an Ihre Anwendung weiter, um zu bestätigen, dass dieser Nutzer für das Ansehen einer Werbung mit Anreiz eine Prämie erhalten soll, wenn zur Bestätigung der Server-zu-Server-Callback verwendet wird.

Hinweis: Diese Einstellung trifft nur bei Werbungen mit Anreiz zu.

IncentivizedDialogTitle

"Diese Werbung schließen?"

string

Legt den Titel des Bestätigungsdialogfelds fest, das beim Überspringen einer Werbung mit Anreiz angezeigt wird.

Hinweis: Diese Einstellung trifft nur bei Werbungen mit Anreiz zu.

IncentivizedDialogBody

"Möchten Sie diese Werbung wirklich überspringen? Sie müssen sie zu Ende ansehen, um Ihre Belohnung zu erhalten."

string

Legt den Text des Bestätigungsdialogfelds fest, das beim Überspringen einer Werbung mit Anreiz angezeigt wird.

Hinweis: Diese Einstellung trifft nur bei Werbungen mit Anreiz zu.

IncentivizedDialogCloseButton

"Schließen"

 

string

Legt den Text der 'cancel'-Schaltfläche in dem Bestätigungsdialogfeld fest, das beim Überspringen einer Werbung mit Anreiz angezeigt wird.

Hinweis: Diese Einstellung trifft nur bei Werbungen mit Anreiz zu.

IncentivizedDialogContinueButton

"Fortfahren"

string

Legt den Text der 'keep watching'-Schaltfläche in dem Bestätigungsdialogfeld fest, das beim Überspringen einer Werbung mit Anreiz angezeigt wird.

Hinweis: Diese Einstellung steht nicht zur Verfügung, wenn die Werbung nicht mit Anreiz ausgestattet ist.

Incentivized

-

VERALTET

Sie können die Anreiz-Einstellung auf der Platzierungsebene im Dashboard anpassen. Unter Einrichtung von und Berichte über Platzierungen erhalten Sie weitere Informationen.


Hinweis:
Die Optionen für SoundEnabled und Dialoge mit Anreiz für die Werbungen "Dynamic Template" und "Flex View" können über das Dashboard eingestellt werden. Die programmgesteuerte Konfiguration trifft nur auf ältere Werbungen zu.

Anzeigen des Buttons "Schließen"

Um zu steuern, ob ein Nutzer die Möglichkeit hat, eine Werbung zu schließen, verwenden Sie die Optionen zum Erzwingen der Wiedergabe in den erweiterten Einstellungen Ihrer App im Vungle Dashboard.

Das Abonnieren von Event-Handlern

Das Windows SDK löst mehrere Events aus, die Sie programmgesteuert verarbeiten können. Sie können diese Event-Handler zur Steuerung von Funktionen Ihrer App wie dem Pausieren oder Fortfahren von Hintergrundmusik verwenden.

Hinweise zum UI-Thread

Die Event-Listener werden in einem Hintergrund-Thread ausgeführt. Jede Interaktion oder Aktualisierung der Benutzeroberfläche, die sich aus einem Event-Listener ergibt, muss vor der Ausführung an den Haupt-Thread der UI übergeben werden. Hier folgt eine Methode um dies umzusetzen:

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ // Dieser Block wird im UI-Thread ausgeführt
} );

VungleAd Event-Handler

Event-Handler

Beschreibung

OnInitCompleted

Wird sofort nach abgeschlossener Initialisierung des SDKs gerufen. Sie können überprüfen, ob eine in einer vorherigen Sitzung heruntergeladene Werbung vorhanden ist oder eine Werbung für Platzierungen herunterladen.

OnAdPlayableChanged

Benachrichtigt über die Änderung der Verfügbarkeit von Werbung für die Platzierung. Warten Sie auf die Durchführung einer Aktion durch den Event-Handler, wenn eine Werbung verfügbar wird, nachdem eine zur Platzierung geladen wurde.

OnAdStart

Wird vor der Wiedergabe einer Werbung gerufen. Sie können Aktionen wie das Pausieren von Hintergrundmusik durchführen.

OnAdEnd

Wird aufgerufen, wenn der Nutzer die End-Karte schließt und die Steuerung zurück an Ihre Anwendung übergeben wird. Wenn entweder IsCompletedView oder CallToActionClicked "true" ist, hat der Nutzer sich die Werbung angesehen oder die Download-Schaltfläche in der Werbung angeklickt. In diesem Fall und wenn es sich um eine Werbung mit Anreiz handelt, sollte der Nutzer belohnt werden. Sie können Aktionen wie das Wiederaufnehmen von App-Funktionen durchführen.

Diagnostic

Wird gerufen, wenn das SDK Diagnose-Logs ausgeben möchte.

Beispielcode:

//Event-Handler registrieren
sdkInstance.OnInitCompleted     += SdkInstance_OnInitCompleted;
sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;
sdkInstance.OnAdStart           += SdkInstance_OnAdStart;
sdkInstance.OnAdEnd             += SdkInstance_OnAdEnd;
sdkInstance.Diagnostic          += SdkInstance_Diagnostic;

...

// OnInitCompleted
//   e.Initialized  – "true", wenn die Initialisierung stattgefunden hat, "false" wenn sie fehlgeschlagen ist
//   e.ErrorMessage  – Grund für den Fehlschlag, wenn e.Initialized  "false" ist.
private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e)
{
  var placementsInfo = "OnInitCompleted: " + e.Initialized;
  // Initialisierung war erfolgreich
  if (e.Initialized == true)
  {
    // Liste der Platzierungen ausgeben
    for (var i = 0; i < e.Placements.Length; i++)
    {
      placementsInfo += "\n\tPlacement" + (i + 1) + ": " + e.Placements[i].ReferenceId;
      if (e.Placements[i].IsAutoCached == true)
        placementsInfo += " (Auto-Cached)";
    }
  }
  // Initialisierung fehlgeschlagen
  else
  {
    placementsInfo += "\n\t" + e.ErrorMessage;
  }
  System.Diagnostics.Debug.WriteLine(placementsInfo);
  await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() =>
    NotifyInitialization(e.Initialized)));
}

// OnAdPlayableAdPlayable
//   e.AdPlayable  – "true" falls eine Werbung zur Wiedergabe verfügbar ist; anderenfalls "false"
// e.Placement  – Platzierungs-ID als String
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnAdPlayable(" + e.Placement + ") - " + e.AdPlayable);
  await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() =>
    NotifyWatcher(e.AdPlayable, e.Placement)));
}

// OnAdStart
// e.Id  – Vungle App-ID als String
// e.Placement  – Platzierungs-ID als String
private void SdkInstance_OnAdStart(object sender, AdEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement);
}

// OnAdEnd
// e.Id  – Vungle App-ID als String
// e.Placement  – Platzierungs-ID als String
// e.IsCompletedView-  "true", wenn mindestens 80 % des Videos angesehen wurden
//   e.CallToActionClicked  – "true", wenn der Nutzer die Download-Schaltfläche auf der End-Karte angeklickt hat
//   e.WatchedDuration  – Veraltet
private void SdkInstance_OnAdEnd(object sender, AdEndEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnVideoEnd(" + e.Id + "): "
    + "\n\tPlacement: " + e.Placement
    + "\n\tIsCompletedView: " + e.IsCompletedView
    + "\n\tCallToActionClicked: " + e.CallToActionClicked
    + "\n\tWatchedDuration: " + e.WatchedDuration);
}

// Event-Handler wird gerufen, wenn das SDK Diagnose-Logs ausgeben möchte
private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e)
{
  System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } // Veraltet – Verwenden Sie stattdessen SdkInstance_OnAdEnd() private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }

Abspielen von native Flex Werbungen

Vungle Windows SDK 5.1.0+ unterstützt unsere neue Funktion für native Flex Werbungen. VungleAdControl bietet Video-Ads in nativen Formaten durch Weiterleitung eines benutzerdefinierten Containers zum Vungle SDK über die Eigenschaft AdConfig.AdContainer und Verwaltung des Container.Content-Contents der Host-App.

Anforderungen für native Flex Werbungen

  • Windows SDK 5.1.0+
  • Windows 10 UWP

Bitte wenden Sie sich an Ihren Kontomanager oder senden Sie eine E-Mail an tech-support@vungle.com, um Platzierungen nativer Flex Werbungen zu konfigurieren.

UI-Setup für native Flex Werbungen - XAML

Die Deklarierung von VungleAdControl muss mit der Vungle App-ID, allen in der App verwendeten Platzierungs-IDs und der Platzierungs-ID für die besondere native Flex-Ansicht oder die Feed-Platzierung erfolgen. Möglich ist auch die Einstellung von UserId, hier verwendet für Werbungen mit Anreiz.

Beispielcode:

<Grid
<UI:VungleAdControl x:Name="vungleEmbedded"
Height="200"
                     Width="300"
                      AppID="vungle_app_id"
                      Placements="placement_id_1,placement_id_2,native_flex_id"
                      Placement = "native_flex_id"
                      UserId="vungle_test_user">
    <TextBlock x:Name="Vungle Native Flex Ad"/>
  </UI:VungleAdControl>
</Grid>

Native Flex Werbung laden

Das Laden einer Werbung mit einer nativen Flex Platzierung ist identisch mit dem Laden einer Vollbildwerbung.

Beispielcode:

sdkInstance.LoadAd(“native_flex_id”); 

Native Flex Werbung abspielen

Das Abspielen einer Werbung mit nativer Flex Platzierung ist ähnlich wie das Abspielen einer Vollbildwerbung, aber jede Konfiguration muss in .xaml oder auf dem Dashboard konfiguriert werden, auch der Start der Werbung mit deaktiviertem Ton.

Beispielcode:

await vungleEmbedded.PlayAdAsync();

Event-Handler für native Flex Werbungen

Ziehen Sie die Registrierung separater Event-Handler in Erwägung, um die verschiedenen Verhaltensweisen von Vollbildwerbungen und native Werbungen zu verwalten und so die Benutzererfahrung zu verbessern.

Beispielcode:

vungleEmbedded.OnAdStart += (sender, arg) => {
    ...
}
vungleEmbedded.OnAdEnd += (sender, arg) => {
    ...
}
await vungleEmbedded.PlayAdAsync();
Haben Sie Fragen? Anfrage einreichen

Kommentare