Native Android

From POKKT DOCUMENTATION
Revision as of 06:41, 4 June 2020 by Madhu (talk | contribs) (Integration Guide v 8.0.0)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

POKKT Native Android SDK v8.0.0 (GDPR Compliance)

Last Update: 2nd June, 2020

Download Latest Version Here


Getting Started with Pokkt SDK v 8.0.0

1. Add "PokktSDK.aar" to your project.

2. Set Application Id and Security Key in Pokkt SDK. You can get it from Pokkt dashboard from your account. These are unique per app registered.
PokktAds.setPokktConfig("<Pokkt Application ID>", "<Pokkt Security Key>", “<Activity Context>”);
3. Set the following to enable or disable omission of Pokkt logs and other informatory messages. Make sure to set it to false before release.
PokktAds.Debugging.shouldDebug(“<Context Context>”,<true>);

4. Set GDPR consent in Pokkt SDK. This must be called before calling any ad related API. Developers/Publishers must get the consent from user. For more information on GDPR please refer https://www.eugdpr.org/ and https://www.eugdpr.org/gdpr-faqs.html . This API can again be used by publishers to revoke the consent. If this API is not called or invalid data provided then SDK will access the users personal data for ad targeting.

PokktAds.ConsentInfo consentInfo = new PokktAds.ConsentInfo();
consentInfo.setGDPRApplicable(true);
//true if GDPR is applicable.
consentInfo.setGDPRConsentAvailable(true);
//true if user has given consent to use personal details for ad targeting.
PokktAds.setDataAccessConsent(consentInfo);

5. You can check if Ad is cached or not using

PokktAds.isAdCached("<ScreenId>"); 
6. Show FullScreen Ad with one of the following:
 PokktAds.showAd("<ScreenId>",<PokktAdDelegate>,null); 

7. Show Native Ad

  • Add ​PokktNativeAdLayout​ to your Layout XML
  ...
<com.pokkt.sdk.pokktnativead.PokktNativeAdLayout
    android:id="@+id/pokkt_native_ad"
    android:layout_width="match_parent"
    android:layout_height="300dp"
    android:background="@android:color/white"
    android:visibility="visible" />
...
  • Request for native Ad.
PokktAds.requestNativeAd(“<ScreenId>”, <NativeAdsDelegate>);
  • Once ​PokktNativeAd​ is received in the AdReady callback of ​NativeAdsDelegate​ implementation, pokktNativeAdLayout view should be set to pokktNativeAd.
pokktNativeAd.setMediaView(findViewById(R.id.pokkt_native_ad),context);

8. For Banner Ad

  • Define a container (PokktBannerView) for banner something like following:
<com.pokkt.sdk.banners.PokktBannerView
     android:id="@+id/pokkt_banner_view_top"
     android:layout_width="320dp"
     android:layout_height="50dp"
     android:layout_centerHorizontal="true"/>
  • To load banner, use:
  PokktAds.showAd("<ScreenId>",<PokktAdDelegate>,<PokktBannerView>); 
  • Use the following to destroy banner:
  PokktAds.destroyBanner(<pokktBannerView>); 

9. Implement PokktAds.PokktAdDelegate to listen to fullscreen-ad related messages.
10. Implement PokktAds.BannerAdDelegate to listen to banner-ad related messages.
11. We recommend caching of video-ads for better user experience, you can cache an ad using the following:

 PokktAds.cacheAd("<ScreenId>",<PokktAdDelegate>); 

Integration Guide v 8.0.0

Overview

Thank you for choosing Pokkt SDK for Android. This document contains all the information required to set up the SDK with your project. We also support mediation for various third party networks. To know the supported third party networks and their integration process go to mediation section .

Before implementing plugins it is mandatory to go through project configuration and implementation steps, as these sections contain mandatory steps for basic SDK integration and are followed by every plugin.

You can download our SDK from pokkt.com.

Downloaded SDK package will contain:

  1. Docs:
    • Contains documentations for step wise step integration for SDK.
  2. PokktSDK_v 8.0.0.jar
    • Pokkt SDK in jar format.
  3. PokktSDK_v 8.0.0.aar
    • Pokkt SDK in aar format.
  4. Pokktsdk360ext.jar / Pokktsdk360ext.aar
    • Add these if you want to support 360 video ads.
  5. PokktAds Demo
    • Source code for PokktAds Demo(Sample app) which showcase implementation of Pokkt SDK through code for better understanding.
  6. Dependency jars:
    • Please add google play services and support-v4 jar.

minSdkVersion supported is 11 .

ScreenId: This one parameter is accepted by almost all API’s of Pokkt SDK. This controls the placement of ads and can be created on Pokkt Dashboard.

We will be referencing PokktAds Demo app provided with SDK during the course of explanation in this document. We suggest you go through the sample app for better understanding.

Project Configuration

Dependencies

  • Add PokktSDK_v 8.0.0.jar or PokktSDK_v 8.0.0.aar to your project.
  • We expect Google play services integrated in project, although it is optional but we recommend you to integrate it, as it is required to fetch AdvertisingID for device,which is useful to deliver targeted advertising to Android users.
  • Add Pokktsdk360ext.jar/Pokktsdk360ext.aar if you want to support 360 video ads.

Manifest

Android 9.0 (API 28) blocks cleartext (non-HTTPS) traffic by default , which can prevent ads from serving correctly.To mitigate that, publishers whose apps run on Android 9.0 or above should ensure to add a network security config file or you should set the usesCleartextTraffic attribute in your application tag to true. Doing so whitelists cleartext traffic and allows non-HTTPS ads to serve.

<application
    ...
    android:usesCleartextTraffic="true">
    ...
</application>
Permissions Declarations

Add the following permissions to your project manifest

1. Mandatory permissions.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  • android.permission.INTERNET = Required for SDK communication with server.
  • android.permission.ACCESS_NETWORK_STATE = Required to detect changes in network, like if WIFI is available or not.
Activity Declaration

Add the following activity in your AndroidManifest for Pokkt SDK integration.

<activity
     android:name="com.pokkt.sdk.PokktAdActivity"
     android:configChanges="keyboard|keyboardHidden|navigation|orientation|screenLayout
     |uiMode|screenSize|smallestScreenSize"
     android:hardwareAccelerated="true"
     android:label="Pokkt"
     android:screenOrientation="landscape"
     android:windowSoftInputMode="stateAlwaysHidden|adjustUnspecified" />

You can change the android:screenOrientation="landscape" to of your choice, the way you want to display the ads.

Implementation Steps

SDK Configuration

1. Set Application Id and Security key in Pokkt SDK. You can get it from Pokkt dashboard from your account. These are unique per app registered.

PokktAds.setPokktConfig("<Pokkt Application ID>", "<Pokkt Security Key>","<Activity Context>");

2. If you are using server to server integration with Pokkt, you can also set Third Party UserId in PokktAds.

PokktAds.setThirdPartyUserId("<Third party user Id>");

3. When your application is under development and if you want to see Pokkt logs and other informatory messages, you can enable it by setting shouldDebug to true . Make sure to disable debugging before release.

PokktAds.Debugging.shouldDebug(<true>);

4. Set GDPR consent in Pokkt SDK. This must be called before calling any ad related API. Developers/Publishers must get the consent from user. For more information on GDPR please refer https://www.eugdpr.org/ and https://www.eugdpr.org/gdpr-faqs.html . This API can again be used by publishers to revoke the consent. If this API is not called or invalid data provided then SDK will access the users personal data for ad targeting.

PokktAds.ConsentInfo consentInfo = new PokktAds.ConsentInfo();
consentInfo.setGDPRApplicable(true);
//true if GDPR is applicable.
consentInfo.setGDPRConsentAvailable(false);
//false if user has given consent to use personal details for ad targeting.
PokktAds.setDataAccessConsent(consentInfo);

Ad Types

FullScreen Ads
  • FullScreen Ads are of two types : Video and Interstitial.
  • FullScreen ads can be rewarded or non-rewarded.
  • FullScreen properties can be configured from the Pokkt dashboard.
  • You can either cache the ad in advance or directly call show for it.
  • We suggest you cache the ad in advance so as to give seamless play behaviour, In other case it will stream the video which may lead to unnecessary buffering delays depending on the network connection.

1. To cache FullScreen ad call:

 PokktAds.cacheAd("<ScreenId>",<PokktAdDelegate>); 

2. To show FullScreen ad call:

 PokktAds.showAd("<ScreenId>",<PokktAdDelegate>,null); 

3. You can check if FullScreen ad is cached or not using

 PokktAds.isAdCached("<ScreenId>"); 
  • Sample Screen Id for Video : 684ab1e66abeb060faa500136c4c6a74
  • Sample Screen Id for Interstitial : 5e59028c8332c9583e742c183abbaafb
  • Add ​PokktBannerView ​to your layout, we use it as a placeholder to populate banner ads into it.
 <com.pokkt.sdk.banners.PokktBannerView
    android:id="@+id/pokkt_banner_view_top"
    android:layout_width="320dp"
    android:layout_height="50dp"
    android:layout_centerHorizontal="true"/> 
  • Load banner
 PokktAds.showAd("<ScreenId>",<PokktAdDelegate>,<PokktBannerView>); 
  • You can remove Banner using:
 PokktAds.destroyBanner(<pokktBannerView>); 
  • Sample Screen Id for Banner : 129cc53b4666f5ae1ebad6a9bc942764
Native Ads

A native ad may be served in feed or in between the developer content inside the app. Normally, FullScreen ads are delivered on call to action by the user. Native ads eliminate this limitation and show ads without any user request.Native ads are also non intrusive as they will be automatically paused when the ad is out of the view by scrolling. The PokktNativeAdLayout will be part of developer application parent components which may be ListView, Layout in ScrollView or WebView.

  • Add ​PokktNativeAdLayout​ to your Layout XML
  ...
<com.pokkt.sdk.pokktnativead.PokktNativeAdLayout
    android:id="@+id/pokkt_native_ad"
    android:layout_width="match_parent"
    android:layout_height="300dp"
    android:background="@android:color/white"
    android:visibility="visible" />
...
  • Request for native Ad.
PokktAds.requestNativeAd(“<ScreenId>”, <NativeAdsDelegate>);
  • Once ​PokktNativeAd​ is received in the AdReady callback of ​NativeAdsDelegate​ implementation, pokktNativeAdLayout view should be set to pokktNativeAd.
pokktNativeAd.setMediaView(findViewById(R.id.pokkt_native_ad),context);
  • Developers must implement ​NativeAdsDelegate​ and supply POKKT SDK in requestNativeAd().
PokktAds.NativeAdsDelegate delegate = new PokktAds.NativeAdsDelegate()
    { @Override
    public void adReady(screenId,pokktNativeAd) {
    }
    @Override
    public void adFailed(screenId, String errorMessage) {
    }
    @Override
    public void adClosed(String screenId, boolean isComplete) {
    }
};
  • Developers will have to do cleanup of Native Ad in onDestroy of activity life cycle.
pokktNativeAd.destroy();

Please refer to our Pokkt Ads Demo Source code for sample implementation of Native Ads in List, Scroll and WebView

  • Sample Screen Id for Video : 684ab1e66abeb060faa500136c4c6a74
  • Sample Screen Id for Interstitial : 5e59028c8332c9583e742c183abbaafb

Ad Delegates

FullScreen Ads

Ad delegates are optional, but we suggest to implement them as it will help you to keep track of the status of your ad request.

 PokktAdDelegate pokktAdDelegate = new PokktAds.PokktAdDelegate() {
    @Override
    public void adCachingResult(screenId,isSuccess,reward,errorMessage) {
    }
    @Override
    public void adDisplayedResult(screenId,isSuccess,errorMessage) {
    }
    @Override
    public void adClosed(screenId,isComplete) {\
    }
    @Override
    public void adGratified(screenId,reward) {
    }
   @Override
    public void adClicked(screenId) {
    }
};
Native Ads

Developers should implement SDK Native Ad delegates and supply POKKT SDK in requestNativeAd().

PokktAds.NativeAdsDelegate delegate = new PokktAds.NativeAdsDelegate() {
    @Override
    public void adReady(screenId,pokktNativeAd) {
    }
    @Override
    public void adFailed(screenId,errorMessage) {
    }
    @Override
    public void adClosed(screenId,isComplete) {
    }
};

Ad delegates are optional, but we suggest to implement them as it will help you to keep track of the status of your ad request.

 PokktAds.BannerAdDelegate adDelegate = new PokktAds.BannerAdDelegate() { @Override
   public void bannerExpanded(screenId) {
   }
   @Override
   public void bannerResized(screenId) {
   }
   @Override
   public void bannerCollapsed(screenId) {
   }
   @Override
   public void adCachingResult(screenId,isSuccess,reward,errorMessage) {
   }
   @Override
   public void adDisplayedResult(screenId,isSuccess,errorMessage) { //called when banner is loaded/failed to load
   }
   @Override
   public void adClosed(screenId,isComplete) {
   }
   @Override
   public void adGratified(screenId,reward) {
   }
   @Override
   public void adClicked(screenId) {
   //called when banner is clicked
   }
};

Pokkt ad player configuration

Pokkt Ad player works the way App is configured at Pokkt dashboard, but we provide a way to override those settings using PokktAdViewConfig.

Application should prefer configuration provided through code by developer or what’s configured for the app in dashboard, can be controlled any time through the dashboard itself. If you want to make changes to this configuration after your app distribution, you can contact Pokkt Team to do the same for your app through admin console.

PokktAdViewConfig adViewConfig = new PokktAdViewConfig ();
// set properties values to adViewConfig
PokktAds.setAdPlayerViewConfig(adViewConfig );

Various setters for the properties that can be managed through this are:

1. Back button
Defines if user is allowed to close the Advertisement by clicking on back button or not.
Setter Name: setBackButtonDisabled(boolean backButtonDisabled)
Values:
True = Back button is disabled and user cannot close the Ad.
False = Back button is not disabled and user can close the Ad.

2. Default skip time
Defines the time after which user can skip the Ad.
Setter name: setDefaultSkipTime(int defaultSkipTime)
Values:
Any Integer value.
Default value is 10 seconds.

3. Should allow skip
Defines if user is allowed to skip the Ad or not.
Setter name: setShouldAllowSkip(boolean shouldAllowSkip)
Values:
True = User can skip Ad.
False = User can’t skip Ad.

4. Should allow mute
Defines if user is allowed to mute the Video Ad or not.
Setter name: setShouldAllowMute(boolean shouldAllowMute)
Values:
True = User can mute video Ad.
False = User can’t mute video Ad.

5. Should confirm skip
Defines if confirmation dialog is to be shown before skipping the Ad.
Setter name: ShouldConfirmSkip
Values:
True = Confirmation dialog will be shown before skipping the video.
False = Confirmation dialog will not be shown before skipping the video.

6. Skip confirmation message
Defines what confirmation message to be shown in skip dialog.
Setter name: setShouldSkipConfirm(boolean shouldSkipConfirm)
Values:
Any String message.
Default value is “Skipping this video will earn you NO rewards. Are you sure?”.

7. Affirmative label for skip dialog
Defines what should be the label for affirmative button in skip dialog.
Setter name: setSkipConfirmYesLabel(String skipConfirmYesLabel)
Values:
Any String message.
Default value is “Yes”.

8. Negative label for skip dialog
Defines what should be the label for affirmative button in skip dialog.
Setter name: setSkipConfirmNoLabel(String skipConfirmNoLabel)
Values:
Any String message.
Default value is “No”.

9. Skip timer message
Defines message to be shown before enabling skip button. Don’t forget to add placeholder “ ## ” in your custom message. This placeholder is replaced by property “Default skip time” assigned above.
Setter name: setSkipTimerMessage(String skipTimerMessage)
Values:
Any String message.
Default value is “You can skip video in ## seconds”

10. Incentive message
Defines message to be shown during video progress, that after what time user will be incentivised.
Setter name: setIncentiveMessage(String incentiveMessage)
Values:
Any String message
Default value is “more seconds only for your reward !”

11. Should collect feedback
Defines message to be shown during video progress, that after what time user will be incentivised.
Property name setShouldCollectFeedback
Values:
True = If you want to collect feedback from the user for the Ad.
False = If you don’t want to collect feedback from the user for the Ad.

12. Audio Enabled
Provides a medium to disable audio for video ad without user interaction.
Property name setAudioEnabled
Values:
True = If you want to play audio for video ad.
False = If you don’t want to play audio for video ad.

User Details

For better targeting of ads you can also provide user details to our SDK using.

PokktUserDetails pokktUserDetails = new PokktUserDetails();
pokktUserDetails.setName(" ");
pokktUserDetails.setAge(" ");
pokktUserDetails.setSex(" ");
pokktUserDetails.setMobileNumber(" ");
pokktUserDetails.setEmailAddress(" ");
pokktUserDetails.setLocation(" ");
pokktUserDetails.setBirthday(" ");
pokktUserDetails.setMaritalStatus(" ");
pokktUserDetails.setFacebookId(" ");
pokktUserDetails.setTwitterHandle(" ");
pokktUserDetails.setEducation(" ");
pokktUserDetails.setNationality(" ");
pokktUserDetails.setEmployment(" ");
pokktUserDetails.setMaturityRating(" ");
PokktAds.setUserDetails(pokktUserDetails);

Pokkt Server Callback Params

Developer can set some values in POKKT SDK that they need to be sent to their server via POKKT Server callbacks.

Map<String, String> params = new HashMap<>();
params.put("testdata","{\"adnetwork\": \"pokkt\"}");
PokktAds.setCallbackExtraParams(params);

Debugging

Other than enabling debugging for Pokkt SDK, it can also be used to:

1. When your application is under development and if you want to see Pokkt logs and other informatory messages, you can enable it by setting ​shouldDebug ​to ​true​. Make sure to disable debugging before release.

PokktAds.Debugging.shouldDebug(“<Context Context>”,<true>);

2. Export log
Export your log to your desired location, we generally have it in root directory of SD card, if permission for external storage is provided and in cache folder otherwise.

PokktAds.Debugging.exportLog(getActivity());

3. Export log to cloud You can also export log to cloud.

PokktAds.Debugging.exportLogToCloud(getActivity());

Proguard

If you are using proguard in your app, add following rules to your proguard file.

# Pokkt SDK
-keep class com.pokkt.** { public *; }
-dontwarn com.pokkt.**
# moat
-keep class com.moat.** { *; }
-dontwarn com.moat.**
-keep class com.c.c.**{*;}
# OM
-keep class com.iab.omid.library.pokkt.**{*;}
-dontwarn com.iab.omid.**
# 360 if Pokktsdk360ext.jar or Pokktsdk360ext.aar is added
-keep class com.pokkt.sdk360ext.** { *; }
# For communication with Pokkt WebView
-keepclassmembers class * {
@android.webkit.JavascriptInterface <methods>;
}

Migration Note Guide v 8.0.0

  • In case of any query regarding integration, refer “POKKT_SDK_Integration_Guide(_v8.0.0_Native_Android)” for this version provided inside “PokktSDK_v8.0.0”.

Screen ID

ScreenId is accepted by almost all API’s of Pokkt SDK. This controls the placement of ads and can be created on Pokkt Dashboard. This replaced Screen Name used earlier.

AdTypes

Rewarded Video ads and Interstitial Ads are merged into full screen ad type and ad type can be changed in runtime by editing the screen id Ad type.

Simpler APIs for full screen ads and banner ads.

PokktAds.VideoAd.cacheRewarded("<ScreenName>");
PokktAds.VideoAd.cacheNonRewarded("<ScreeName>");
PokktAds.Interstitial.cacheRewarded("<ScreeName>");
PokktAds.Interstitial.cacheNonRewarded("<ScreeName>");

is now

PokktAds.cacheAd("<ScreenId>",<PokktAdDelegate>);
PokktAds.VideoAd.showRewarded("<ScreenName>");
PokktAds.VideoAd.showNonRewarded("<ScreeName>");
PokktAds.Interstitial.showRewarded("<ScreeName>");
PokktAds.Interstitial.cacheNonRewarded("<ScreeName>");

is now

PokktAds.showAd("<ScreenId>",<PokktAdDelegate>,null);
PokktAds.Banner.loadBanner(“<screenName>”, <pokktBannerView>);

is now

PokktAds.showAd("<ScreenId>",<PokktAdDelegate>,<PokktBannerView>);

Ad Delegates are changed. SetDelegate API is removed.

PokktAds.VideoAd.setDelegate(new PokktAds.VideoAd.VideoAdDelegate() {
public void videoAdCachingCompleted(String screenName, boolean isRewarded, double reward) {}
public void videoAdCachingFailed(String screenName, boolean isRewarded, String errorMessage) {}
public void videoAdDisplayed(String screenName, boolean isRewarded) {}
public void videoAdFailedToShow(String screenName, boolean isRewarded, String errorMessage) {}
public void videoAdClosed(String screenName, boolean isRewarded) {}
public void videoAdClicked(String screenName, boolean isRewarded){}
public void videoAdSkipped(String screenName, boolean isRewarded) {}
public void videoAdCompleted(String screenName, boolean isRewarded) {}
public void videoAdGratified(String screenName, boolean isRewarded, double reward)
{}
});

is now

PokktAdDelegate pokktAdDelegate = new PokktAds.PokktAdDelegate() {
public void adCachingResult(screenId,isSuccess,reward,errorMessage) { }
public void adDisplayedResult(screenId,isSuccess,errorMessage) { }
public void adClosed(screenId,isComplete) { }
public void adGratified(screenId,reward) { }
public void adClicked(screenId) {} };
PokktAds.Interstitial.setDelegate(new PokktAds.Interstitial.InterstitialDelegate() {
public void interstitialCachingCompleted(String screenName, boolean isRewarded, double reward) {}
public void interstitialCachingFailed(String screenName, boolean isRewarded, String errorMessage) {}
public void interstitialDisplayed(String screenName, boolean isRewarded) {}
public void interstitialFailedToShow(String screenName, boolean isRewarded, String errorMessage) {}
public void interstitialClosed(String screenName, boolean isRewarded) {}
public void interstitialSkipped(String screenName, boolean isRewarded) {}
public void interstitialClicked(String screenName, boolean isRewarded){}
public void interstitialCompleted(String screenName, boolean isRewarded) {}
public void interstitialGratified(String screenName, boolean isRewarded, double reward) {}
});

is now

PokktAdDelegate pokktAdDelegate = new PokktAds.PokktAdDelegate() {
public void adCachingResult(screenId,isSuccess,reward,errorMessage) { }
public void adDisplayedResult(screenId,isSuccess,errorMessage) { }
public void adClosed(screenId,isComplete) { }
public void adGratified(screenId,reward) { }
public void adClicked(screenId) {} };

isAdCached API is changed.

PokktAds.VideoAd.isAdCached("<ScreenName>", <true/false>);
PokktAds.Interstitial.isAdCached("<ScreenName>", <true / false>);

is now

PokktAds.isAdCached("<ScreenId>");

Destroy Banner API is changed

PokktAds.Banner.destroy(<pokktBannerView>);

is now

PokktAds.destroyBanner(<pokktBannerView>); 

Native Ad

Native Ads are introduced which replaces OutStream ads. Please refer our documentation for details.

Migration Note Guide v 7.6.0

Note

  • In case of any query regarding integration, refer POKKT_SDK_Integration_Guide(_v 7.6.0_Native_Android) for this version provided inside PokktSDK_v 7.6.0.

1. Removed callbacks
videoAdAvailabilityStatus and interstitialAvailabilityStatus are removed from the Video and Interstitial ads respectively and so are the checkAdAvailability API.

2. PokktAdPlayerViewConfig
PokktAdPlayerViewConfig is renamed to PokktAdViewConfig.

3. Activity context required in setPokktConfig.
PokktAds.setPokktConfig("<Pokkt Application ID>", "<Pokkt Security Key>");

is now

PokktAds.setPokktConfig("<Pokkt Application ID>", "<Pokkt Security Key>",
“<Activity Context>”);
4. Context required in shouldDebug.
PokktAds.Debugging.shouldDebug(<true>);

is now

PokktAds.Debugging.shouldDebug(“<Context Context>”,<true>);