cordova-plugin-pollfish

Pollfish Cordova Plugin

Pollfish Cordova Plugin allows integration of Pollfish surveys into Android and iOS apps.

Pollfish is a mobile monetization platform delivering surveys instead of ads through mobile apps. Developers get paid per completed surveys through their apps.

Pollfish Cordova Plugin can be found on npm Registry.

Prerequisites

• Android SDK 21 or higher using Google Play Services
• iOS 11.0 or higher
• Apache Cordova v3.0.0 or higher
• CocoaPods v1.10.0 or higher

Quick Guide

• Create Pollfish Developer account, create a new app and grap it's API key
• Install Pollfish plugin and call init function
• Set to Release mode and release in AppStore and Google Play
• Update your app's privacy policy
• Request your account to get verified from the Pollfish Dashboard

Note: Apps designed for Children and Families program should not be using Pollfish SDK, since Pollfish does not collect responses from users less than 16 years old

Note: Pollfish surveys can work with or without the IDFA permission on iOS 14+. If no permission is granted in the ATT popup, the SDK will serve non personalized surveys to the user. In that scenario the conversion is expected to be lower. Offerwall integrations perform better compared to single survey integrations when no IDFA permission is given

Installation

To add Pollfish plugin just type:

cordova plugin add cordova-plugin-pollfish

To remove Pollfish plugin type:

cordova plugin remove cordova-plugin-pollfish

In iOS you may need to add manually pollfish.framework to your XCode project. In Xcode, select the target that you want to use and in the Build Phases tab expand the Link Binary With Libraries section. Press the + button, and press Add other… In the dialog box that appears, go to the Pollfish framework’s location (located in /src/ios/framework) and select it. The project will appear at the top of the Link Binary With Libraries section and will also be added to your project files (left-hand pane). The framework is a folder and you should add the whole folder into your project.

Initialization

1. Create pollfish.Builder instance

The Pollfish plugin must be initialized with one or two api keys depending on which platforms are you targeting. You can retrieve an API key from Pollfish Dashboard when you sign up and create a new app.

var builder = new pollfish.Builder('ANDROID_API_KEY', 'IOS_API_KEY')
	.rewardMode(true); // Android & iOS

var builder = new pollfish.Builder('ANDROID_API_KEY', null)
	.rewardMode(true); // Android only

var builder = new pollfish.Builder(null, 'IOS_API_KEY')
	.rewardMode(true); // iOS only

1.1 Configure Pollfish behaviour (Optional)

You can set several params to control the behaviour of Pollfish survey panel within your app with the use of the pollfish.Builder instance. Below you can see all the available options. Apart from the constructor all the other methods are optional.

Param	Description
constructor(String, String)	Sets Your Android and iOS API Keys (from step 2)
.indicatorPosition(pollfish.Position)	Sets the Position where you wish to place the Pollfish indicator. There are six different options RNPollfish.Position.{topLeft, topRight, middleLeft, middleRight, bottomLeft, bottom Right}:
.indicatorPadding(Int)	Sets the padding from top or bottom depending on the position of the indicator specified before (if used in middle position, padding is calculated from the top).
.offerwallMode(Boolean)	Sets Pollfish to offerwall mode
.releaseMode(Boolean)	Choose Debug or Release Mode
.rewardMode(Boolean)	Init in reward mode (skip Pollfish indicator to show a custom prompt)
.requestUUID(String)	Sets a unique id to identify a user and be passed through server-to-server callbacks
.userProperties(Json)	Send attributes that you receive from your app regarding a user, in order to receive a better fill rate and higher priced surveys. You can see a detailed list of the user attributes you can pass with their keys at the following link
.rewardInfo(Json)	An object holding information regarding the survey completion reward. If set, signature must be calculated in order to receive surveys. See here in section Notes for sig query parameter
.clickId	A pass throught param that will be passed back through server-to-server callback
.userId	A unique id to identify a user
.signature	An optional parameter used to secure the rewardConversion and rewardName parameters passed on rewardInfo Json object.

Example of Pollfish configuration using the available options

var builder = builder
	.offerwallMode(false)
	.releaseMode(false)
	.indicatorPadding(50)
	.indicatorPosition(pollfish.Position.BOTTOM_RIGHT)
	.requestUUID('REQUEST_UUID')
	.userProperties({
		gender: '1',
		education: '1',
		...
	})
	.clickId('CLICK_ID')
	.userId('USER_ID')
	.signature('SIGNATURE')
	.rewardInfo({
		rewardName: 'Points',
		rewardConversion: 1.3
	})
	.build();

pollfish.init(params); 

Debug vs Release Mode

You can use Pollfish either in Debug or in Release mode.

• Debug mode is used to show to the developer how Pollfish will be shown through an app (useful during development and testing).
• Release mode is the mode to be used for a released app (start receiving paid surveys).

Note: Be careful to set the releaseMode parameter to true when you release your app in a relevant app store!!

Reward Mode

Setting the rewardMode to false during initialization enables controlling the behavior of Pollfish in an app from the Pollfish panel. Enabling reward mode ignores Pollfish behavior from Pollfish panel. It always skips showing Pollfish indicator (small button) and always force open Pollfish view to app users. This method is usually used when app developers want to somehow incentivize their users before completing surveys to increase completion rates.

User ID

Setting the userId will override the default behaviour and use that instead of the Advertising Id, of the corresponding platform, in order to identify a user

You can pass the id of a user as identified on your system. Pollfish will use this id to identify the user across sessions instead of an ad id/idfa as advised by the stores. You are solely responsible for aligning with store regulations by providing this id and getting relevant consent by the user when necessary. Pollfish takes no responsibility for the usage of this id. In any request from your users on resetting/deleting this id and/or profile created, you should be solely liable for those requests.

3. Initialize Pollfish

Last but not least. Build the Params object by invoking .build() on the pollfish.Builder instance that you've configured earlier and call RNPollfish.init(params) passing the Params object as an argument.

var params = builder.build();
pollfish.init(params);

// OR

pollfish.init(builder.build());

Optional section

In this section we will list several options that can be used to control Pollfish surveys behaviour, how to listen to several notifications or how be eligible to more targeted (high-paid) surveys. All these steps are optional.

Get notified when a Pollfish survey is received

You can get notified when a Pollfish survey is received. With this notification, you can also get informed about the type of survey that was received, money to be earned if survey gets completed, shown in USD cents and other info around the survey such as LOI and IR.

Note: If Pollfish is initialized in offerwall mode then the event parameter will be undefined, otherwise it will include info around the received survey.

pollfish.setEventCallback(pollfish.EventListener.OnPollfishSurveyReceived, (result) => {
    console.log("Survey Received: " + JSON.stringify(result));
});

Get notified when a Pollfish survey is completed

You can get notified when a user completed a survey. With this notification, you can also get informed about the type of survey, money earned from that survey in USD cents and other info around the survey such as LOI and IR.

pollfish.setEventCallback(pollfish.EventListener.OnPollfishSurveyCompleted, (result) => {
    console.log("Survey Completed: " + JSON.stringify(result));
});

Get notified when a user is not eligible for a Pollfish survey

You can get notified when a user is not eligible for a Pollfish survey. In market research monetization, users can get screened out while completing a survey beucase they are not relevant with the audience that the market researcher was looking for. In that case the user not eligible notification will fire and the publisher will make no money from that survey. The user not eligible notification will fire after the surveyReceived event, when the user starts completing the survey.

pollfish.setEventCallback(pollfish.EventListener.OnPollfishUserNotEligible, (_) => {
    console.log("Pollfish User Not Eligible");
});

Get notified when a Pollfish survey is not available

You can get notified when a Pollfish survey is not available

pollfish.setEventCallback(pollfish.EventListener.OnPollfishSurveyNotAvailable, (_) => {
    console.log("Pollfish Survey not available");
});

Get notified when a Pollfish survey panel has opened

You can register and get notified when a Pollfish survey panel has opened. Publishers usually use this notification to pause a game until the pollfish panel is closed again.

pollfish.setEventCallback(pollfish.EventListener.OnPollfishOpened, (_) => {
    console.log("Pollfish Survey panel is open");
});

Get notified when a Pollfish survey panel has closed

You can register and get notified when a Pollfish survey panel has closed. Publishers usually use this notification to resume a game that they have previously paused when the Pollfish panel was opened.

pollfish.setEventCallback(pollfish.EventListener.OnPollfishClosed, (_) => {
    console.log("Pollfish Survey panel is closed");
});

Get notified when a use has rejected a survey

You can be notified when use has rejected a Pollfish survey

pollfish.setEventCallback(pollfish.EventListener.OnPollfishUserRejectedSurvey, (_) => {
    console.log("Pollfish User Rejected Survey");
});

Manually show/hide Pollfish panel

You can manually hide and show Pollfish by calling anywhere after initialization:

For example:

pollfish.show();

or

pollfish.hide();

Check if Pollfish surveys are available on your device

After you initialize Pollfish and a survey is received you can check at any time if the survey is available at the device by calling the following function.

pollfish.isPollfishPresent((result) => {
	console.log(result)
});

Check if Pollfish panel is open

You can check at any time if the survey panel is open by calling the following function.

pollfish.isPollfishPanelOpen((result) => {
	console.log(result)
});

Migrate to v2.x.x

Pollfish Cordova Plugin v2 introduces a new package name and different API with added customization options during initialization. If you have already integrated Pollfish Cordova Plugin < v2 in you app, please

1. Remove the old deprecated package name

cordova plugin remove com.pollfish.cordova_plugin

2. Add the new package name

cordova plugin add cordova-plugin-pollfish

3. Read the migration guide

For a detailed guide on how to migrate from Pollfish Cordova Plugin v1.x.x to v2.x.x please click here

More info

You can read more info on how the Native Pollfish SDKs work on Android and iOS or how to set up properly a Cordova environment at the following links:

Pollfish Corvova Plugin Documentation

Pollfish Android SDK Integration Guide

Pollfish iOS SDK Integration Guide

Cordova Starting Guide