Titanium

From POKKT DOCUMENTATION
Jump to: navigation, search

POKKT SDK v5.0 Integration Guide for Appcelerator (Android)

Last Update: 18th November, 2016

Download Latest Version Here with PDF Documentation v5.0.


1. Overview:

Thank you for choosing Pokkt SDK Plugin v5.0 for Appcelerator. Pokkt SDK supports Offerwall as well as Video/Interstitial-Ad campaigns feature. This document contains all the information that is needed by you to setup the SDK with your project. Please follow these steps as per your integration requirement (Ad/Interstitial/Both). The current plugin supports mediation for various third party ad-networks. These are:

  • AdColony
  • AppLovon
  • Chartboost
  • Fyber
  • InMobi
  • SuperSonic
  • UnityAds
  • TapJoy
  • Vungle
  • AdMob
  • Facebook
  • MoPub

A separate set of documents is provided for each of these, explaining the implementation process.

Kindly note that these instructions are for Appcelerator with Titanium SDK Version 5.x and above, older versions of are not supported.

There is a sample app provided with the SDK. We will be referencing this app during the course of explanation in this document. It is suggested that you should check that app to understand the following process in detail.

Note:Please do not copy the code points from this Doc/PDF file as it may introduce unwanted characters and space in your code. Instead please refer to sample app source code provided with the sample app.


2. Configuration Steps

There are three files that are provided and will be needed by you to use the plugin:

  1. com.pokkt.titaniumandroid-android-5.0.zip
  2. pokkt_native_extension.js

In order to add this to you project, go to Help -> Install Mobile Module,browse to com.pokkt.titaniumandroid-android-5.0.zipand press “Ok”.This should install the plugin in your project. Next, copy pokkt_native_extension.jsinside your Resource folder. Now the plugin should be ready for you to use with your project.

Minimum android SDK version is 14.


Android-Manifest Changes

(You can edit these inside timodule.xmlafter you install the Pokkt module.)

Permissions:

<!--REQUIRED PERMISSIONS FOR POKKT-->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!--RECOMMENDED PERMISSIONS FOR POKKT-->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!--OPTIONAL PERMISSIONS FOR POKKT-->
<uses-permission android:name="android.permission.WRITE_CALENDAR" />

Activities:

Needed for Offerwall:

<activity
android:name="com.app.pokktsdk.ShowOfferwallActivity"
android:configChanges="keyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize"
android:windowSoftInputMode="adjustPan" />

Needed for ads:

<activity
android:name="com.app.pokktsdk.PlayVideoCampaignActivity"
android:configChanges="keyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize"
android:screenOrientation="landscape"
android:windowSoftInputMode="stateAlwaysHidden|adjustUnspecified"/>

<activity
android:name="com.app.pokktsdk.InterstitialActivity"
android:configChanges="keyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize|smallestScreenSize" />

<activity
android:name="com.app.pokktsdk.VPAIDActivity"
android:configChanges="keyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize|smallestScreenSize" />

Broadcast Receivers:

Needed for Offerwall:

<receiver android:name="com.app.pokktsdk.AppInstallBroadcastReceiver">
   <intent-filter android:priority="1000" >
      <action android:name="android.intent.action.PACKAGE_INSTALL" />
      <action android:name="android.intent.action.PACKAGE_ADDED" />
      <data android:scheme="package" />
   </intent-filter>
</receiver>

Optional for Google Analytics:

<receiver
android:name="com.google.android.gms.analytics.AnalyticsReceiver"
android:enabled="true">
   <intent-filter>
      <action android:name="com.google.android.gms.analytics.ANALYTICS_DISPATCH" />
   </intent-filter>
</receiver>

Meta-Data tags:

Needed for Offerwall:

<meta-data
android:name="offerwallDelegate"
android:value="com.pokkt.plugin.common.PokktOfferwallDelegate" />
Required for Google Play Services: Add Following meta tag for google play services (Goole play
services is required and should be part of your project, if not, please refer
http://developer.android.com/google/play-services/setup.html)
<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />

Services:

Optional for In-App Notifications:

<service
   android:name="com.google.android.gms.analytics.AnalyticsService"
   android:enabled="true"
   android:exported="false" />

3. Implementation Steps

Common

  1. For all invocation of Pokkt SDK developer will make use of methods available in pokktNativeExtension.jsfile using PokktExtensionobject.
  2. Create a PokktConfigobject using creatPokktConfig()method, then provide applicationIdand securityKey, these are must for initializing Pokkt.
  3. Once you have your pokktConfig ready, invoke initPokktmethod before you invoke any other methods from the PokktExtension. This does not apply to session related methods namely startSession and endSessionand few utility methods.
  4. In order to know whether Pokkt is initialized or not, listen to ‘PokktInitialised’ event, if the provided Boolean parameter is true only then move ahead with other operations.
  5. If you are doing server to server integration with Pokkt you can also set thirdPartyUserIdin pokktConfigobject.
  6. Apart from above mentioned parameters you can assign additional ones based on your integration type. Refer to Offerwall and Video sections below.
  7. While in development please call PokktExtension.setDebug(true) to see Pokkt debug logs and toast messages. Make sure to change this to falsefor production build.
  8. Call PokktExtension.notifyAppInstall()to log your application installation information with Pokkt.
  9. Call PokktExtension.trackIAP(details)to log any in-app purchase details with Pokkt. Accepted values are (all caps): “NONE”, “GOOGLE”, “IOS”, “AMAZON”.
  10. To use google analytics, please set selectedAnalyticsType to “GOOGLE_ANALYTICS” and googleAnalyticsIDin pokktConfig.
  11. To use flurry analytics please set selectedAnalyticsTypeto “FLURRY” and flurryApplicationKeyin pokktConfig.
  12. To use mix panel analytics please set selectedAnalyticsTypeto “MIXPANEL” and mixPanelProjectTokenin pokktConfig.
  13. To use mix panel analytics please set selectedAnalyticsTypeto “FABRIC”.

Session

  1. Invoke PokktExtension.startSession()at the start of his application and once only.
  2. You should callPokktExtension.endSession()at the end of his application and once only.

Offerwall

  1. In pokketConfigfor Offerwall you can set two additional parameters which are setOfferWallAssetValueand setCloseOnSuccessFlag.Setting of setOfferWallAssetValueis only required if you only want to show campaign of certain value on the Offerwall. setCloseOnSuccessFlagis required if you wish to auto-close the Offerwall after user has completed one offer. It’s default value is false.
  2. Make sure to call initPokktbefore calling another method for Offerwall in PokktExtension.
  3. To show Offerwall you can call PokktExtension.getCoins(pokktConfig).
  4. In the screen or activity where you have button to show Offerwall, in that activity onResumeyou should call PokktExtension.getPendingCoins(pokktConfig) so that you get a callback to award points to the user after he has come back to your game after finishing with Offerwall. You will get a callback for this call in your IOfferwallDelegate implementation class in method EarnedCoinsor CoinResponseFailed.
  5. You can call PokktExtension.checkCampaignAvailable(pokktConfig)to check whether the campaigns are available before showing Offerwall button to user.
  6. Following are offerwall-related events, you can refer to the provided sample-code to understand the ideal implementation on how to consume these:
    • CoinResponse
    • CoinResponseWithTransId
    • CoinResponseFailed
    • CampaignAvailability
    • OfferwallClosed

Rewarded/Non-Rewarded Ads

  1. You will have to configure an adConfigobject to request for any ad to be displayed. Get one using createAdConfig()method. It also provides options for customizing your ad-screen. It is recommended to have different adConfigobjects for each screens. Followings are the values that you can set with adConfig:
    • screenName (Required): This controls the placement of ads and can be created on Pokkt Dashboard.
    • adFormat (Required): Requested ad format. SDK supports Video, Interstitial and banner adFormats. Default is Video ad format.
    • isRewarded (Required): Requested ad type. Ad gratification will happen only for rewarded ads.
    • backButtonDisabled:Disable ‘back’ button press while on ad-screen.
    • defaultSkipTime:If ad-skipping is allowed, this provides the seconds it will wait before the skip button appears.
    • shouldAllowSkip:Whether skipping-ad is allowed or not. If set to ‘false’, user will be forced to watch the ad till it finishes.
    • shouldAllowMute:Whether to allow sound-mute while on ad-screen, it controls the ‘mute’ button. Cannot contains whitespaces and only special characters allowed are hyphens (-) and underscores (_).
    • shouldConfirmSkip:Controls whether to show the skip-confirmation dialog box. If set to ‘false’, the ad will be silently closed without prompting for confirmation
    • skipConfirmMessage: The message that will appear on skip-confirmation dialog box.
    • skipConfirmYesLabel:‘Yes’ Label of skip-confirmation dialog box.
    • skipConfirmNoLabel: ‘No’ Label of skip-confirmation dialog box.
    • skipTimerMessage: The message on countdown-timer before the skip button appears. The message must contain a ‘##’-placeholder to show timer value.
    • incentiveMessage:If set, the message will be displayed while prompting user to watch the ad for certain time before it can be rewarded.
  2. Invoke PokktExtension.cacheAd(adConfig)to cache the ad on device. Cached-ads provide better user experience than streaming-ads
  3. You can call PokktExtension.checkAdAvailability(adConfig) to check if the adcampaigns are available or not. The result will be notified via 'AdAvailability'.
  4. Invoke PokktExtension.showAd(adConfig) to show ad.
  5. Following are ad-related events, you can refer to the provided sample-code to understand the ideal implementation on how to consume these:
    • AdCachingCompleted
    • AdCachingFailed
    • AdClosed
    • AdCompleted
    • AdDisplayed
    • AdSkipped
    • AdGratified
    • AdAvailability
  6. Reward user ONLY from the 'AdGratified' event.

Export Logs

  1. Developer should call PokktExtension.exportLog() to export the Pokkt SDK logs to folder of your choice.
  2. This API shows a folder chooser dialog where user can choose a particular folder.
  3. User can also create a new folder where user wants to export the logs.

Optional Parameters

PokktConfig also has provision for developers to provide extra user data available with them to Pokkt. We currently support following data points: Name, Age, Sex, MobileNo, EmailAddress, Location, Birthday, MaritalStatus, FacebookId, TwitterHandle, Education, Nationality, EmploymentandMaturityRating.