Tapjoy Flutter Plugin Documentation
The Tapjoy Flutter plugin allows you to integrate Tapjoy's advertising and monetization features into your Flutter applications. This documentation provides an overview of the plugin's usage and functionalities.
Table of Contents
- Installation
- Getting Started
- Configuration
- User ID
- Placements
- Currency Balance
- iOS App Tracking Transparency
Installation
To use the Tapjoy Flutter plugin in your Flutter project, follow these steps:
-
Open your project's
pubspec.yaml
file. -
Add
flutter_tapjoy
as a dependency:dependencies: flutter_tapjoy: ^x.x.x
-
Run the command
flutter packages get
to fetch the package.
Getting Started
To start using the Tapjoy plugin in your Flutter application, follow these steps:
-
Import the necessary packages in your Dart file:
import 'package:flutter/material.dart'; import 'package:flutter_tapjoy/flutter_tapjoy.dart';
-
Initialize the Tapjoy plugin and connect to Tapjoy in the
initState()
method of your widget:@override void initState() { super.initState(); TapJoyPlugin.shared.connect( androidApiKey: "YOUR_ANDROID_API_KEY", iOSApiKey: "YOUR_IOS_API_KEY", debug: true, ); }
Replace
"YOUR_ANDROID_API_KEY"
and"YOUR_IOS_API_KEY"
with your actual Tapjoy API keys. Set thedebug
parameter totrue
for testing purposes. -
Set up the Tapjoy plugin for handling connection results, currency balance, and placements. This can be done in the
initState()
method as well:@override void initState() { super.initState(); // Set connection result handler TapJoyPlugin.shared.setConnectionResultHandler(_connectionResultHandler); // Set currency handlers TapJoyPlugin.shared.setGetCurrencyBalanceHandler(_currencyHandler); TapJoyPlugin.shared.setAwardCurrencyHandler(_currencyHandler); TapJoyPlugin.shared.setSpendCurrencyHandler(_currencyHandler); TapJoyPlugin.shared.setEarnedCurrencyAlertHandler(_currencyHandler); // Set contentState handler for each placement myPlacement.setHandler(_placementHandler); myPlacement2.setHandler(_placementHandler); // Add placements TapJoyPlugin.shared.addPlacement(myPlacement); TapJoyPlugin.shared.addPlacement(myPlacement2); }
In the code above,
_connectionResultHandler
,_currencyHandler
, and_placementHandler
are placeholder methods that you need to define to handle the corresponding events. -
Implement the necessary UI and button callbacks to interact with Tapjoy functionalities. For example, you can use the
ElevatedButton
widget to request content, show placements, or perform other actions:ElevatedButton( onPressed: myPlacement.requestContent, child: const Text("Request Content for Placement"), ),
Replace
myPlacement
with the actual placement you want to request content for.
Configuration
The Tapjoy Flutter plugin provides configuration options to connect to Tapjoy and enable debugging. Use the TapJoyPlugin.shared.connect()
method to configure the plugin:
TapJoyPlugin.shared.connect({
androidApiKey: String,
iOSApiKey: String,
debug: bool,
});
androidApiKey
(required): Your Tapjoy Android API key.iOSApiKey
(required): Your Tapjoy iOS API key.debug
(optional): Set totrue
to enable debug mode. Default isfalse
.
User ID
You can set a user ID to identify the user associated with Tapjoy interactions. Use the TapJoyPlugin.shared.setUserID()
method to set the user ID:
TapJoyPlugin.shared.setUserID({userID: String});
userID
(required): The unique identifier for the user.
Placements
Tapjoy placements represent locations in your application where you want to show content, such as rewarded ads or offers. The Tapjoy plugin allows you to add placements, request content, and handle placement events.
Adding Placements
Use the TapJoyPlugin.shared.addPlacement()
method to add a placement:
TapJoyPlugin.shared.addPlacement({placement: TJPlacement});
placement
(required): An instance ofTJPlacement
representing the placement to add.
Requesting Content for a Placement
To request content for a placement, call the requestContent()
method on the corresponding TJPlacement
instance:
myPlacement.requestContent();
Replace myPlacement
with the actual placement you want to request content for.
Handling Placement Events
You can handle events related to Tapjoy placements, such as content readiness, appearance, disappearance, and request success/failure. Set the handler for each placement using the setHandler()
method:
placement.setHandler({handler: Function});
-
handler
(required): The function that will be called when placement events occur. It should have the following signature:void handler(TJContentState contentState, String? name, String? error)
contentState
(required): The current content state of the placement.name
(optional): The name of the placement.error
(optional): Any error message associated with the event.
Currency Balance
The Tapjoy plugin provides methods to manage the user's currency balance, such as retrieving the balance, awarding currency, and spending currency. You can set handlers to receive currency-related events.
Retrieving Currency Balance
To retrieve the user's currency balance, call the getCurrencyBalance()
method:
TapJoyPlugin.shared.getCurrencyBalance();
The currency balance will be returned via the currency balance handler.
Handling Currency Balance Events
To handle currency balance events, set the handler using the setGetCurrencyBalanceHandler()
method:
TapJoyPlugin.shared.setGetCurrencyBalanceHandler({handler: Function});
-
handler
(required): The function that will be called when currency balance events occur. It should have the following signature:void handler(String? currencyName, int? amount, String? error)
currencyName
(optional): The name of the currency.amount
(optional): The amount of the currency.error
(optional): Any error message associated with the event.
Awarding Currency
To award currency to the user, call the awardCurrency()
method:
TapJoyPlugin.shared.awardCurrency({amount: int});
amount
(required): The amount of currency to award.
The currency balance will be returned via the currency balance handler.
Spending Currency
To spend currency from the user's balance, call the spendCurrency()
method:
Tap
JoyPlugin.shared.spendCurrency({amount: int});
amount
(required): The amount of currency to spend.
The currency balance will be returned via the currency balance handler.
iOS App Tracking Transparency
If your Flutter application targets iOS and you want to access the App Tracking Transparency (ATT) authorization status, you can use the Tapjoy plugin to retrieve it.
Retrieving iOS App Tracking Transparency Authorization
To retrieve the iOS App Tracking Transparency (ATT) authorization status, call the getIOSATTAuth()
method:
TapJoyPlugin.shared.getIOSATTAuth();
The authorization status will be returned as a value of the IOSATTAuthResult
enum.
Handling iOS ATT Authorization Result
To handle the iOS ATT authorization result, set the handler using the setIOSATTAuthResultHandler()
method:
TapJoyPlugin.shared.setIOSATTAuthResultHandler({handler: Function});
-
handler
(required): The function that will be called when the iOS ATT authorization result is received. It should have the following signature:void handler(IOSATTAuthResult result)
result
(required): The iOS ATT authorization result, represented by theIOSATTAuthResult
enum.