Erste Schritte mit Vungle – Windows SDK v. 6

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

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

Inhalt

DSGVO: Empfohlene Implementierung

Seit dem 25. Mai gilt in der EU die Datenschutzgrundsatzverordnung (DSGVO). Zur Einhaltung der DSGVO haben Entwickler zwei Optionen.

  • Option 1 (empfohlen): Der Herausgeber steuert den Prozess zur Konformität mit der DSGVO auf Benutzerebene und leitet die Entscheidung des Benutzers an Vungle weiter. Entwickler können dazu die Zustimmung des Benutzers über eigene Mechanismen einholen und dann mit Vungle APIs den Zustimmungsstatus des Benutzers abfragen oder aktualisieren. Einzelheiten finden Sie im Abschnitt Anweisungen zur empfohlenen Implementierung der DSGVO.

  • Option 2: Erlauben Sie Vungle, die Anforderungen zu verwalten. Vungle zeigt europäischen Benutzern vor dem Abspielen einer Werbung einen Zustimmungsdialog an und merkt sich die Zustimmung bzw. Ablehnung des Benutzers für die nachfolgende Werbung.

Bevor Sie anfangen

  • Dieser Leitfaden gilt für Vungle Windows SDK 5.3.2 und höher. Den Integrationsleitfaden für Vungle Windows SDK Version 1.3.16 und früher finden Sie hier: Erste Schritte 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, falls Sie noch keines besitzen.
  • Falls noch nicht geschehen, gehen Sie zu unserem Dashboard und fügen Sie Ihre App Ihrem Konto hinzu. 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, nicht aber auf PCs (Tastatur) unterstützt. Dies kann bei UWP-Builds zu Unterschieden in Verhalten und Bedienung führen.
  • Bitte versetzen 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 Ihrem Projekt hinzu

Es gibt zwei Möglichkeiten, Vungle in Ihr Xcode-Projekt einzufügen: entweder über NuGet oder durch eine manuelle Integration.

Option 1. NuGet-Integration

  1. Klicken Sie in Visual Studio mit der rechten Maustaste auf Projekt und wählen Sie Manage NuGet Packages (NuGet-Pakete verwalten).
  2. Klicken Sie auf Browse (Durchsuchen), geben Sie „Vungle“ ein, wählen Sie Vungle SDK aus und klicken Sie auf Install (Installieren).

Option 2. Manuelle Integration

  1. Laden Sie das Vungle Windows SDK aus dem Vungle Dashboard herunter.
  2. Extrahieren Sie das Archiv.
  3. Erstellen Sie in Visual Studio ein neues Projekt mit der passenden Vorlage für Ihre Anwendung und Programmiersprache.
  4. Fügen Sie der heruntergeladenen Vungle Windows SDK-Datei eine Referenz auf Ihr Projekt hinzu.

Vungle SDK enthält zwei VungleSDK.windmd-Dateien zur Entwicklung für Windows 10 und 8.1. Verwenden Sie das korrekte SDK aus dem extrahierten Verzeichnis: Win10 oder Win81.

internetClient-Fähigkeit

Stellen Sie die internetClient-Fähigkeit Ihres Projekts in der Datei package.appxmanifest sicher.

Visual Studio

  1. Doppelklicken Sie auf appxmanifest in Solution Explorer.
  2. Wählen Sie die Fähigkeiten aus
  3. Vergewissern Sie sich, dass die Option Internet (Client) markiert ist.

Manuelle Bearbeitung

Öffnen Sie die Datei package.appxmanifeset und fügen Sie internetClient dem Abschnitt Fähigkeiten hinzu.

<Capabilities>
...
<Capability Name="internetClient" />
...
</Capabilities>

VungleSDK Namespace importieren

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 eine automatisch gecachte Platzierung nicht übernehmen, 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 gleich nachdem wichtige Komponenten durch Ihre App geladen wurden, sodass mit dem automatischen Cachen früher begonnen werden kann.

Erstellen und Registrieren eines Event-Handlers

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

// Event handler for OnAdPlayableChanged event private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { // e.Placement - placement ID in string // Run asynchronously on the UI thread await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => methodToRun(e.Placement))); } 

Registrieren Sie diesen Event-Handler für Event OnAdPlayableChanged.

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; 

Laden einer Werbung zur Platzierung

Bei Platzierungen außer der automatisch gecachten Platzierung müssen Sie zuerst LoadAd aufrufen, ausreichend Zeit zum Herunterladen der Assets gewähren und dann warten, dass OnAdPlayableChanged aufgerufen wird:

sdkInstance.LoadAd(“placement_id”); 

Hinweis: Die automatisch gecachte Platzierung versucht sofort nach dem Aufruf von PlayAdAsync ein neues Werbe-Asset herunterzuladen, sodass LoadAd nicht aufgerufen 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:

Hinweis: Belohnte Anzeigen (rewarded ads) werden im Englischen mitunter auch als incentivized bezeichnet; beide Begriffe stehen für dieselbe Art von Werbeanzeige. Im SDK-Code und in unserer Reporting-API verwenden wir den Begriff „incentivized”.

Optionen

Standardwert /
Typ

Beschreibung

Orientation

AutoRotate

DisplayOrientations

Orientation.AutoRotate (Standard) bedeutet, dass die Werbung automatisch entsprechend der Ausrichtung des Geräts gedreht 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 Betrachten einer Werbung mit Belohnungsanreiz eine Prämie erhalten soll, wenn zur Bestätigung der Server-zu-Server-Callback verwendet wird.

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

IncentivizedDialogTitle

„Diese Werbung schließen?“

string

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

Hinweis: Diese Einstellung trifft nur bei Werbungen mit Belohnungsanreiz 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 Belohnungsanreiz angezeigt wird.

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

IncentivizedDialogCloseButton

"Schließen"

 

string

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

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

IncentivizedDialogContinueButton

"Fortfahren"

string

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

Hinweis: Diese Einstellung steht nicht zur Verfügung, wenn die Werbung nicht mit Belohnungsanreiz 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 mit Belohnungsanreizen versehene Dialoge für dynamische Vorlagen und Flex View-Werbung sind auf dem Dashboard konfigurierbar. Eine programmgesteuerte Konfiguration ist nur ältere Werbungsformen verfügbar.

Anzeigen der Schaltfläche „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.

Anweisungen zur empfohlenen DSGVO-Implementierung

// To set the user’s consent status as opted in: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentAccepted); // To set the user’s consent status as opted out: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentDenied); // To find out what the user’s current consent status is: // This will return null if the GDPR Consent status has not been set // Otherwise, it will return VungleConsentStatus.VungleConsentAccepted or // VungleConsentStatus.VungleConsentDenied UpdateConsentStatus? currentStatus = sdkInstance.GetCurrentConsentStatus(); 

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(() =>
{ // This block will be executed in the UI thread
} );

VungleAd Event-Handler

Event-Handler

Beschreibung

OnInitCompleted

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

OnAdPlayableChanged

Informiert über die Änderung der Verfügbarkeit von Werbung zur 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 aufgerufen. Sie können Aktionen wie das Pausieren von Hintergrundmusik ausführen.

OnAdEnd

Wird aufgerufen, wenn der Nutzer die End-Karte schließt und die Kontrolle 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 Belohnungsanreiz handelt, sollte der Nutzer dafür belohnt werden. Sie können Aktionen wie die Wiederaufnahme von App-Funktionen ausführen.

Diagnostic

Wird aufgerufen, wenn das SDK Diagnose-Logs ausgeben will.

Beispielcode:

//Register event handlers sdkInstance.OnInitCompleted += SdkInstance_OnInitCompleted; sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; sdkInstance.OnAdStart += SdkInstance_OnAdStart; sdkInstance.OnAdEnd += SdkInstance_OnAdEnd; sdkInstance.Diagnostic += SdkInstance_Diagnostic; ... // OnInitCompleted // e.Initialized - true if initialization succeeded, false if failed // e.ErrorMessage - reason for failure when e.Initialized is false private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e) { var placementsInfo = "OnInitCompleted: " + e.Initialized; // Initilization was success if (e.Initialized == true) { // Print out list of placements 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)"; } } // Initilization failed 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 if an ad is available to play, false otherwise // e.Placement - placement ID in 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 in string // e.Placement - placement ID in string private void SdkInstance_OnAdStart(object sender, AdEventArgs e) { System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement); } // OnAdEnd // e.Id - Vungle app ID in string // e.Placement - placement ID in string // e.IsCompletedView- true when 80% or more of the video was watched // e.CallToActionClicked - true when the user has clicked download button on end card // e.WatchedDuration - DEPRECATED 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 called when SDK wants to print diagnostic logs private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e) { System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } // DEPRECATED - Use SdkInstance_OnAdEnd() instead private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }

Abspielen von nativer Flex-Werbung

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-Werbung - 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 Belohnungsanreiz.

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 vergleichbar mit dem Abspielen einer Vollbildwerbung, allerdings muss jede Konfiguration in .xaml bzw. auf dem Dashboard konfiguriert werden, auch der Start der Werbung mit deaktiviertem Ton.

Beispielcode:

await vungleEmbedded.PlayAdAsync();

Native Flex-Werbung schließen

Aufgrund der Eigenschaften von Flex Feed-Werbung können Benutzer das Video anhalten, ohne dabei die Anzeige zu schließen. Sie müssen daher dem SDK mitteilen, die Werbung zu entfernen, sobald sie sich nicht mehr im Bildschirmbereich befindet. Wir haben daher zwei Methoden zum Schließen nativer Flex-Werbung eingeführt:

  • Verwenden Sie CloseFlexViewAd(String placementId), um eine Werbung mit der entsprechenden Platzierungs-ID sofort zu schließen.

  • Verwenden Sie SetFlexViewCloseTimeInSec(String placementId, int seconds), um die entsprechende Platzierung nach Ablauf der eingestellten Anzahl an Sekunden zu schließen.

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