npm package: @gartorware/cordova-plugin-appodeal-framework
Description: Appodeal's supply-side platform is designed and built by veteran publishers, for publishers. Appodeal is not an ad network, it is a new approach to monetizing for publishers.
Author: Gartorware
Latest version: 3.0.2-trimmed

# Appodeal Cordova Plugin

This is an unofficial Appodeal Cordova plugin, created to integrate Appodeal SDK with Apache Cordova.

# How to Update Plugin Manually

### Android Part:

+ Update [appodeal.gradle](/src/android/appodeal.gradle) with desired changes/version.
+ Check [AppodealPlugin.java](/src/android/AppodealPlugin.java) for any API changes.
+ Done, you can use updated plugin for Android Platform.

### iOS Part:

//TODO

+ Download new Appodeal iOS SDK [here](https://www.appodeal.com/sdk/documentation?framework=20&full=1&platform=4) and unzip it somewhere.
+ Remove [Adapters](/libs/iOS/Adapters/) folder and [Appodeal.bundle](/libs/iOS/Appodeal/). Replace old `Appodeal.framework` with new one and put `Resources` folder if exists into [libs/iOS/Appodeal](/libs/iOS/Appodeal).
+ Open [plugin.xml](/plugin.xml), scroll down to `<platform name="ios">` and check system frameworks for any changes due to changes in 3 Step of 5.3 Manual Integration in [Appodeal iOS Doc page](https://www.appodeal.com/sdk/documentation?framework=20&full=1&platform=4).
+ Remove all the content after `<framework custom="true" src="libs/iOS/Appodeal/Appodeal.framework"/>` in [plugin.xml](/plugin.xml) up to `</platform>` close tag. 
+ Skip this step if unzipped iOS SDK does not contain `Resources` folder. Add all resources from `Resources` folder of unzipped iOS SDK manually after `<framework custom="true" src="libs/iOS/Appodeal/Appodeal.framework"/>`, for example: 

```xml
<resource-file src="libs/iOS/Appodeal/Resources/MPCloseBtn.png"/>
```

+ Check [AppodealPlugin.m](/scr/ios/AppodealPlugin.m) for any API changes.
+ Done, you can use updated plugin for iOS Platform.

## Install

Simply go to the project folder over console/terminal and run there following command:

    cordova plugin add https://github.com/GartorwareCorp/appodeal-cordova-plugin-framework.git --variable ADMOB_APP_ID="<YOUR_ANDROID_ADMOB_APP_ID_AS_FOUND_IN_ADMOB>"

Also, *if targeting Android >= 28*, create a `resources/android/xml/network_security_config.xml` file with this content:
```
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
            <certificates src="user" />
        </trust-anchors>
    </base-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">127.0.0.1</domain>
    </domain-config>
</network-security-config>
```
And edit your config.xml to include this file in your build:

```
<edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest/application" xmlns:android="http://schemas.android.com/apk/res/android">
     <application android:networkSecurityConfig="@xml/network_security_config" />
</edit-config>
<resource-file src="resources/android/xml/network_security_config.xml" target="app/src/main/res/xml/network_security_config.xml" />
        
```

If you have issues while installing plugin, follow the Command-line Interface Guide.

Minimum OS requirements: 

+ iOS 8.1
+ Android API level 14 (Android OS 4.0)

### Multidex
 
If receiving errors while compiling about method number limites (>65K), please, enable Multidex:

**For Android X**
```
cordova plugin add https://github.com/GartorwareCorp/cordova-plugin-androidx-multidex.git
```

### Proguard

Proguard rules should be auto included, so no changes needed.


## Cordova Integration

### Ad Types

+ Appodeal.INTERSTITIAL
+ Appodeal.BANNER_TOP
+ Appodeal.BANNER_BOTTOM
+ Appodeal.REWARDED_VIDEO

Ad types can be combined using "|" operator. For example Appodeal.INTERSTITIAL | Appodeal.REWARDED_VIDEO.

### SDK Initialization

To initialize SDK for INTERSTITIAL ad type, call the following code:

```javascript
var appKey = "e7e04e54ae0a8d28cff2f7e7e7d094e78b2a09743be2cc4a";
Appodeal.disableLocationPermissionCheck();
Appodeal.initialize(appKey, Appodeal.INTERSTITIAL, consent);
```

+ To initialize only interstitials use `Appodeal.initialize(appKey, Appodeal.INTERSTITIAL)`
+ To initialize only rewarded video use `Appodeal.initialize(appKey, Appodeal.REWARDED_VIDEO)`
+ To initialize only non-skippable video use `Appodeal.initialize(appKey, Appodeal.NON_SKIPPABLE_VIDEO)`
+ To initialize interstitials and non-skippable videos use `Appodeal.initialize(appKey, Appodeal.INTERSTITIAL | Appodeal.NON_SKIPPABLE_VIDEO)`
+ To initialize only banners use `Appodeal.initialize(appKey, Appodeal.BANNER)`

### Display Ad

To display ad you need to call the following code:

```javascript
Appodeal.show(adTypes);
```

+ To display interstitial use `Appodeal.show(Appodeal.INTERSTITIAL)`
+ To display rewarded video use `Appodeal.show(Appodeal.REWARDED_VIDEO)`
+ To display non-skippable video use `Appodeal.show(Appodeal.NON_SKIPPABLE_VIDEO)`
+ To display interstitial or non-skippable video use `Appodeal.show(Appodeal.INTERSTITIAL | Appodeal.NON_SKIPPABLE_VIDEO)`
+ To display banner at the bottom of the screen use `Appodeal.show(Appodeal.BANNER_BOTTOM)`
+ To display banner at the top of the screen use `Appodeal.show(Appodeal.BANNER_TOP)`

Also it can be used in this way, to get boolean value if ad was successfully shown:

```javascript
Appodeal.show(adTypes, function(result) {
   // result is a boolean value, that is indicates whether show call was passed to appropriate SDK 
});
```

### Checking if interstitial is loaded

To check if ad type was loaded, use following code:

```javascript
Appodeal.isLoaded(adTypes, function(result){
    // result returns bool value
});
```

### Hide Banner Ad

To hide banner you need to call the following code:

```javascript
Appodeal.hide(Appodeal.BANNER);
```

### Callbacks integration

Callbacks can be setted with following code:

```javascript
Appodeal.setInterstitialCallbacks( function(result) {
       console.log(result);
});
Appodeal.setBannerCallbacks( function(result) {
       console.log(result);
});
Appodeal.setRewardedVideoCallbacks( function(result) {
       console.log(result);
});
Appodeal.setNonSkippableVideoCallbacks( function(result) {
       console.log(result);
});
```

result.event can be one of the following:
```
onInit
onLoaded
onFailedToLoad
onClick
onShown
onClosed
onFinished
onExpired
onShowFailed
```

To set Interstitial callbacks, use following code:

```javascript
Appodeal.setInterstitialCallbacks( function(container) {
       if (container.event == 'onLoaded') {
            console.log("Appodeal. Interstitial. " + container.event + ", isPrecache: " + container.isPrecache  );
            // your code
       } else if (container.event == 'onFailedToLoad') {
            // your code
       } else if (container.event == 'onShown') {
            // your code
       } else if (container.event == 'onClick') {
            // your code
       } else if (container.event == 'onClosed') {
            // your code
       }
});
```

To set Banner callbacks, use following code:

```javascript
Appodeal.setBannerCallbacks( function(container) {
       if (container.event == 'onLoaded') {
            console.log("Appodeal. Banner. " + container.event + ", height: " + container.height + ", isPrecache: " + container.isPrecache);
            // your code
       } else if (container.event == 'onFailedToLoad') {
            // your code
       } else if (container.event == 'onShown') {
            // your code
       } else if (container.event == 'onClick') {
            // your code
       }
});
```

To set Rewarded Video callbacks, use following code:

```javascript
Appodeal.setRewardedVideoCallbacks( function(container) {
       if (container.event == 'onLoaded') {
            // your code
       } else if (container.event == 'onFailedToLoad') {
            // your code
       } else if (container.event == 'onShown') {
            // your code
       } else if (container.event == 'onFinished') {
            // container also returns "name" and "amount" variables with reward amount and currency name you have set for your application
            console.log( "Appodeal. Rewarded. " + container.event + ", amount: " + container.amount + ", name: " + container.name);
            // your code
       } else if (container.event == 'onClosed') {
            // container also returns "finished" variable with boolean value for indicating if video was finished
            console.log("Appodeal. Rewarded. " + container.event + ", finished: " + container.finished);
            // your code
       }
});
```

To set Non Skippable Video callbacks, use following code:

```javascript
Appodeal.setNonSkippableVideoCallbacks( function(container) {
       if (container.event == 'onLoaded') {
            // your code
       } else if (container.event == 'onFailedToLoad') {
            // your code
       } else if (container.event == 'onShown') {
            // your code
       } else if (container.event == 'onFinished') {
            // your code
       } else if (container.event == 'onClosed') {
            // container also returns "finished" variable with boolean value for indicating if video was finished
            console.log("Appodeal. Non Skippable Video. " + container.event + ", finished: " + container.finished);
            // your code
       }
});
```

### Advanced Features

#### Getting reward data for placement

To get placement reward data before video is shown use:

```javascript
Appodeal.getRewardParameters( function(result) {
   console.log("Appodeal Reward Amount:" + result.amount);
   console.log("Appodeal Reward Currency:" + result.currency);
});
```

#### Enabling 728*90 banners

To enable 728*90 banner use the following method:

```javascript
Appodeal.set728x90Banners(true);
```

#### Disabling banner refresh animation

To disable banner refresh animation use:

```javascript
Appodeal.setBannerAnimation(false);
```

#### Disabling smart banners

```javascript
Appodeal.setSmartBanners(false);
```

#### Enabling test mode

```javascript
Appodeal.setTesting(true);
```

In test mode test ads will be shown and debug data will be written to log.

#### Enabling logging

```javascript
Appodeal.setLogLevel(Appodeal.LogLevel.debug);
```

Available parameters: Appodeal.LogLevel.none, Appodeal.LogLevel.debug, Appodeal.LogLevel.verbose.

#### Checking if loaded ad is precache

```javascript
Appodeal.isPrecache(adTypes, function(result){
  // result is a boolean value, that equals true if ad is precache
})
```

Currently supported only for interstitials and banners

To check if loaded interstitial is precache: use `Appodeal.isPrecache(Appodeal.INTERSTITIAL);`

To check if loaded banner is precache: use `Appodeal.isPrecache(Appodeal.BANNER);`

#### Manual ad caching

```javascript
Appodeal.cache(adTypes);
```

+ You should disable automatic caching before SDK initialization using `setAutoCache(adTypes, false)`.
+ To cache interstitial use `Appodeal.cache(Appodeal.INTERSTITIAL)`
+ To cache rewarded video use `Appodeal.cache(Appodeal.REWARDED_VIDEO)`
+ To cache interstitial and non-skippable video use `Appodeal.cache(Appodeal.INTERSTITIAL | Appodeal.NON_SKIPPABLE_VIDEO)`
+ To cache banner use `Appodeal.cache(Appodeal.BANNER)`

#### Enabling or disabling automatic caching

```javascript
Appodeal.setAutoCache(adTypes, false);
```

+ Should be used before SDK initialization
+ To disable automatic caching for interstitials use `Appodeal.setAutoCache(Appodeal.INTERSTITIAL, false)`
+ To disable automatic caching for rewarded videos use `Appodeal.setAutoCache(Appodeal.REWARDED_VIDEO, false)`
+ To disable automatic caching for banners use `Appodeal.setAutoCache(Appodeal.BANNER, false)`

#### Triggering onLoaded callback on precache

```javascript
Appodeal.setTriggerOnLoadedOnPrecache(adTypes, true);
```

+ Currently supported only for interstitials
+ `setOnLoadedTriggerBoth(Appodeal.INTERSTITIAL, false)` - onInterstitialLoaded will trigger only when normal ad was loaded (default)..
+ `setOnLoadedTriggerBoth(Appodeal.INTERSTITIAL, true)` - onInterstitialLoaded will trigger twice, both when precache and normal ad were loaded..
+ Should be used before SDK initialization

#### Disabling data collection for kids apps

```javascript
Appodeal.setChildDirectedTreatment(true);
```

#### Disabling networks

```javascript
Appodeal.disableNetwork(network);
```

Available parameters: "adcolony", "admob", "amazon_ads", "applovin", "appnext", "avocarrot", "chartboost", "facebook", "flurry", "inmobi", "inner-active", "ironsource", "mailru", "mmedia", "mopub", "ogury", "openx", "pubnative", "smaato", "startapp", "tapjoy", "unity_ads", "vungle", "yandex"

Should be used before SDK initialization

#### Disabling location permission check

To disable toast messages ACCESS_COARSE_LOCATION permission is missing, use the following method:

```javascript
Appodeal.disableLocationPermissionCheck();
```

Should be used before SDK initialization.

#### Disabling write external storage permission check

To disable toast messages WRITE_EXTERNAL_STORAGE permission is missing use the following method:

```javascript
Appodeal.disableWriteExternalStoragePermissionCheck();
```

Disables all ad networks that need this permission may lead to low video fillrates.

Should be used before SDK initialization.

#### Tracking in-app purchase

```javascript
Appodeal.trackInAppPurchase(this, 5, "USD");
```

#### Testing third-party networks adapters integration

To show test screen for testing adapters integration call:

```javascript
Appodeal.showTestScreen();
```

#### Muting videos if call volume is muted

```javascript
Appodeal.muteVideosIfCallsMuted(true);
```

### Setting User Data

#### Set the age of the user

```javascript
Appodeal.setAge(25);
```

#### Specify gender of the user

```javascript
Appodeal.setGender(UserSettings.Gender.FEMALE);
```

Possible values: Appodeal.Gender.FEMALE, Appodeal.Gender.MALE, Appodeal.Gender.OTHER.