Pleebie Jeebies Company Logo

Pleebie Jeebies

Timed Rewards

About

The Pleebie Jeebies Timed Rewards asset offers developers a simple-to-use and feature-rich approach to a user reward system. Simply drag and drop in to a scene, set up the desired rewards for users, and the asset takes care of the rest.

The main functions of this asset are:

All code is well-documented and variables have been given detailed tooltip information to aid in any configuration process.

NOTE: This asset uses PlayerPrefs to record and store the data required to remember what users have or haven’t done. Because of this, it should be noted that clearing PlayerPrefs will effectively reset the data which will cause the Timed Reward system to restart. This is by design and is used for app updates or reward rollovers.

Asset Files Hierarchy

All files are located under Assets/PleebieJeebies/TimedRewards/. This asset also uses the TextMeshPro asset with files existing under Assets/TextMeshPro/ after importing. See Installation for more detail.

File hierarchy

Prefabs Folder

Inside the Prefabs/ folder, you will find the three prefabs used in the Main Demo Scene, the PJ_CurrencyController, PJ_TimedRewards, and PJ_UserInterface, some variants of the Timed Rewards prefab, as well as some TextMeshPro files. Any Timed Rewards prefab can be placed in a scene and function after having set up the desired rewards for users. Read here for more information on how to set up rewards. The Currency Controller prefab is an optional addition to a scene which must be placed on a Canvas and will display currency gained set up in the Timed Rewards list. The User Interface prefab contains a fully prepared and functional canvas for the Currency Controller and the Timed Rewards prefabs. The TextMeshPro files are used for the fonts throughout the asset.

Scenes Folder

Inside the Scenes/ folder, you will find three functional sample scenes showcasing the Timed Rewards asset. These scenes have been prepared with prefabs to sample from and to quickly grasp an understanding of this asset.
Main Demo Scene displays the Timed Rewards prefab with no limits for the collection process at a 24 hour interval.
20 Minute Rewards – Demo Scene displays the timed rewards prefab with some limits, which include a reward stop date where collection is no longer allowed past the set date, rewards from missed intervals cannot be collected, rewards are collected at 20 minute intervals, but the rewards are reset upon completion.
10 Second Rewards – Demo Scene displays the Timed Rewards prefab with the same limits in the 20 Minute Rewards sample, except the rewards can be collected at 10 second intervals.

Scripts Folder

Inside the Scripts/ folder, you will find the scripts which contain the functionality of this asset. Each script is commented documenting the purpose of each method and all code is open source and can be changed at your own risk. PJ_CurrencyController contains the functionality for the Currency Controller prefab and any additional desired currencies will need to be added here. PJ_CustomRewardCall is the script to place your own method calls for custom rewards beyond a standard currency. PJ_TimedRewards contains the main functionality for this asset including most text changes. If a certain text is undesired, this is where it would be changed, if not in the inspector. PJ_UserInterface contains the functionality for the buttons on the User Interface prefab. Within the Types/ folder are the scripts RewardType, where new currencies can be added, and TimedReward, which is used to represent a Timed Reward object. Finally, within the Helpers/ folder are custom scripts used to animate multiple graphics on a single button component, PJ_MultiImageButton and PJ_MultiImageTargetGraphics.

Sprites Folder

Inside the Sprites/ folder, you will find images used for the interface of the asset, all of which are conveniently white to allow any desired color changes in the inspector. The Icons/ folder contains royalty free icons used to make the interface more understandable for the end user.

TextMesh Pro Folder

The TextMesh Pro/ folder contains all the files required for another asset called TextMeshPro which is an advanced text solution for Unity and is used for several text objects in the Timed Rewards Asset. If TextMeshPro is not imported alongside the rest of the Timed Rewards asset, then several text objects will not appear properly.

Installation

Configuration

Any Timed Rewards prefab will function by being dragged in to any scene after having set up the desired rewards for users. This section will cover the variables used on the PJ_Timed Rewards script and prefab to better understand how to configure the script or prefab. The optional prefabs, PJ_CurrencyController and PJ_UserInterface, will also be covered.

Main Script in inspector

Timed Rewards - This is the only variable that requires setup for functionality. Any number of desired rewards are set here for users and will be displayed in the Timed Rewards popup

Timed Rewards > Reward Type - Represents the type of reward given and based on the types quantified in the RewardType script. This correlates to the currencies in the Demo scenes provided. Selecting ‘Custom’ will allow calling of any method desired upon reward collection (see script PleebieJeebies/PJ_CustomRewardCall.cs for entering methods)

Timed Rewards > Title If Desired - Shown above the reward item as its title; if left empty, an integer index starting from 1 will be shown as the title instead

Timed Rewards > Sprite Icon - Sprite shown to represent the collectable reward

Timed Rewards > Subtitle Or Amount - Shown below the reward Sprite Icon and used to calculate the amount of reward gained; if non-number, a currency amount can't be gained

Timed Reward Interval Duration Hours - Amount of time (in hours) before allowing claim to the next reward; can be decimal or fraction; read ‘Missed Interval’ and Making Changes for formulas to get accurate, down to the second intervals

Task After A Reward Unlocks - Decide what should happen when Timed Rewards are unlocked or missed; The ‘Continue’ option will simply allow the user to claim the reward for the completed interval and the next reward will continue to be unlocked while in the app or not, this is the default option; The ‘Wait For Claim’ option will stop the timer after a reward is unlocked whether the user is in the app or not. This means the user must claim the unlocked reward before the timer for the next reward will begin. The ‘Miss Reward If Missed Interval’ option will count how many intervals were missed by the user upon returning to the app and set that number of rewards as missed and unable to be claimed. The ‘Reset Rewards If Missed Interval’ will check if the user has missed a Timed Reward Interval and reset all rewards if that is the case. See ‘Missed Interval’ and Making Changes for more information on ‘Missed Intervals’

Popup At Program Start - Decide if the Timed Rewards UI should pop open at program start based on available rewards or not

Start Date UTC - Enter in UTC a string formatted to DateTime; format is MM/DD/YYYY HH:MM:SS AM/PM; reward period will start after this time has arrived, otherwise leave this field empty

Stop Date UTC - Enter in UTC a string formatted to DateTime; format is MM/DD/YYYY HH:MM:SS AM/PM; after this time has passed, unlocked rewards can still be claimed, but future ones will NOT be unlockable, otherwise leave this field empty

Reset Rewards On Updated App Version - While true, after entering a new Application Version and starting the app, the rewards will be reset; Edit > Project Settings > Player > Version (NOT Bundle Version Code); For resetting after an update

Reset Rewards After All Done - Setting this true will allow unlocking and claiming of all rewards again after all are claimed (or missed)

Is First Reward Free - Decide if the first reward is given at app start or has to be unlocked

Open To First Claimable Reward - If true, the Timed Rewards UI will open to the first claimable reward in the TimedRewards array, even if other rewards are available. Otherwise, it will open to the most recently claimable reward; this also affects when rewards are claimed

Claim Button Claims All Rewards - When true, pressing the claim reward button will claim every available reward; also changes the Claim button text to ‘Claim All’

Notify User Of Reward After Claim - Setting this true will activate a separate popup upon reward claim to notify the user of the reward

Close Reward Popup After Claim - Setting this true will close the Timed Rewards UI after the claim button is pressed

Show Text Popups - Setting this false will override all other text notifications and never show text popups from this asset

Show Reward Availability Panel - When true, will display a panel in the top right of the scene to show if a reward is ready or not and will open the Timed Rewards UI when pressed; the color used for availability can be changed in the Personalization section below

Use Icons To Represent Reward State - When true, icons will be overlaid each reward to represent different states: Locked, Unlocked, Claimed, and Missed; These icons can be changed in the Personalization section below

Reward Availability Color - Color set to the Reward Availability panel when a reward is available

Reward Availability Border Color - Color set to the Reward Availability panel border when a reward is available

Reward State Locked/Unlocked/Claimed/Missed - Sprite used to represent a reward state when 'Use Icons To Represent Reward State' is true (if true, this must be set otherwise a white sprite will cover the reward)

Prefab/Object Setup Section Variables - The variables in this section shouldn’t be changed from the initial prefab as each one is set up to connect to part of the UI; Changing these variables to anything else will cause the asset to not work properly. These variables are serialized to allow easy and efficient setups. In a case where you’d like to build your own, it is advised to copy from an existing prefab.

Currency Controller in inspector

Currency Text - The text objects here correlate to the currencies in RewardType.cs and are used to represent and display the amount of currency owned by the user

Currency Controller in inspector

Timed Rewards Popup Panel - Used to open the Timed Rewards UI panel when the 'Reward Popup' button is pressed; must be set to the Reward Panel to work properly

Exit Button - Used to turn the exit button off while in the Unity Editor since it has no effect

NOTE: This may seem like a lot of variables, but most have presets or are for small tweaks to get the exact functionality desired. See Getting Started and Asset Setup for how to start using this asset in your project.

Getting Started and Asset Setup

The only required setup for this asset is to fill in the Timed Rewards list with as many objects as desired for users and set up any custom rewards. This section will cover how to do so along with specific sample scenarios to aid in any setup.

First Steps

Either open a demo scene provided or drag and drop the PJ_UserInterface prefab or one of the PJ_TimedRewards prefabs in to one of your own scenes. Ensure the scene has an Event System object, without this, the asset will not function properly. NOTE: PJ_CurrencyController and PJ_TimedRewards are children of the PJ_UserInterface prefab which is used to display any currencies claimed. Using only the Timed Rewards prefab will keep track of rewards claimed/missed, but not record or display any currencies collected.

NOTE: If the TextMesh Pro asset is not already installed and imported, upon running a scene with the Timed Rewards prefab, Unity will prompt to import TMP Essentials; this must be imported for text objects to appear properly. Importing the Extras is not required.

Using the PJ_UserInterface Prefab

If using the PJ_UserInterface prefab, currencies are recorded and displayed by the PJ_CurrencyController within PJ_UserInterface prefab. Feel free to unpack the prefab and adapt the prefab’s interface to be part of your own scene.

Using ONLY the PJ_TimedRewards Prefab

If using only a Timed Rewards prefab, the main reward types won’t exist in the current context since the Currency Controller is part of the User Interface prefab. You will need to have your own custom methods to be called upon reward collection which will need to record and display any rewards given. There is a ‘Custom’ reward type to handle this scenario.

Setting Up a Timed Reward

Click on the PJ_TimedRewards prefab in your scene and navigate to the Inspector and open the Timed Rewards array. Set the array to have as many elements as you would like as this will represent the number of rewards to be claimed. Open the array and open the first element. If using the PJ_UserInterface prefab, any Reward Type can be selected and used, otherwise if only using the Timed Rewards prefab or a custom reward is desired, a ‘Custom’ Reward Type should be selected. A title can be entered to show above the reward, otherwise all elements will be automatically assigned an index value as its title. Then, set a sprite to be displayed which will represent the reward being given. Finally, enter the ‘Subtitle or Amount’ which is used to calculate the amount of reward gained; if non-numbers are entered, a currency amount can’t be gained and will be for display only. This also makes it possible to set ‘blank’ rewards which could either give no reward or set the Reward Type to ‘Custom’ and give specific rewards depending on the scenario.

How to Use or Code for a Custom Timed Reward

If a Reward Type is set to Custom, custom methods must be entered and called from a specific script to work properly with this asset. Navigate to the project panel and open the script at Assets/PleebieJeebies/TimedRewards/Scripts/PJ_CustomRewardCall.cs. When a Timed Reward is claimed with the Custom Reward Type, the CustomRewardCall() method is called. Within this method is where any custom rewards should be given, recorded, and displayed for the user. Code examples have been provided to show how you can differentiate between collected rewards by exposed properties such as the title chosen or the element number in the array. You can even code for blank or null rewards if desired.

Again, these properties have been exposed so any custom reward can be given, but you must also use these properties to properly record and display these rewards to the user, the Timed Rewards prefab only keeps track of reward collection state. See PlayerPrefs Information and Final Thoughts for suggestions on recording data.

Specifications and Personalization

Once you’ve set up your Timed Rewards and adapted your scene to display any rewards given, you’re ready for any final tweaks to the Timed Rewards system. Each variable is documented with tooltips, so hovering over each one will give more information on its purpose. Note that these variables won’t function properly if changed during runtime. You can also see Configuration for information on each variable in this script.

How to Rollover Users to a New Set of Timed Rewards

Once your Timed Rewards system is set up, this section will cover how to continue to update your Timed Rewards while rolling out updates to your users. Under the Specifications section of the Timed Rewards prefab, there is a Boolean named ‘Reset Rewards On Updated App Version’, this is set true by default, but must be true to accomplish reward updates.

Once this is true, navigate to Edit > Project Settings > Player > Version (NOTE: Version not Bundle Version Code).

Change the version value to something new, fill in a new set of Timed Rewards if desired, and push this update out to your users. Now when a user updates and starts the application, this version value has changed; this will trigger a check to reset the rewards to the updated Timed Rewards array and reset any progress gained by users up to this point. Thus allowing the developer to create a full set of new rewards to be collected for users.

Note that any time the Version is changed along with the named Boolean being set true, that it will reset rewards for users. If this is not desired, simply uncheck the Boolean.

‘Missed Interval’ and Making Changes

One of the specifications, ‘Task After A Reward Unlocks’, may be used to punish users for missing a reward interval either by missing the reward for that interval or by resetting reward progress. A ‘Missed Interval’ occurs when a user is not in the application for the entirety of a ‘Timed Reward Interval’. For example, if the reward is set to unlock every 24 hours, a user must be absent for 24 hours to trigger a Missed Interval. This means if a user is absent for less than 24 hours, they will have not missed the interval and thus can receive a reward. When using the reset option, if the user unlocks a reward interval but forgets to claim the reward and then misses a reward interval, those rewards will be reset and lost. As mentioned, this feature is designed to punish users for taking too much time away from your app, so it should be used with caution. There is another option named ‘Wait for Claim’ which will stop the timer after a reward is unlocked whether the user is in the app or not. This means the user must claim the unlocked reward before the timer for the next reward will begin. Using the above example of a 24 hour reward unlock, a user could be absent for two or more days and using the ‘Wait for Claim’ option will mean the user will only unlock a single reward. If punishing users is not desired, then simply set the ‘Task After A Reward Unlocks’ to ‘Continue’.

This asset makes dynamic changes to different texts throughout the cycle of the rewards system. To make changes to any text in this asset, some can be made directly to the text object of choice, but most changes are made within the PJ_TimedRewards script. This script is well documented in attempt to aid any searches for specific text or code changes.

When setting the ‘Timed Reward Interval Duration Hours’, fractions or decimals can be entered to get accurate intervals down to the second. For second intervals, use the formula x/60/60, where x represents how many seconds each interval should have; for minute intervals, use x/60, where x represents how many minutes each interval should have.

The main demo scene provided shows different ways to open the rewards interface: use a button click event to trigger the game object to activate, serialize the object in code and activate it like in the PJ_UserInterface script, or use the provided reward availability panel which is activated though the Boolean ‘Show Reward Availability Panel’.

PlayerPrefs Information and Final Thoughts

This asset uses PlayerPrefs to record and store the data required to remember what users have or haven’t done. Because of this it should be noted that clearing PlayerPrefs will effectively reset the data which will cause the Timed Reward system to restart. This is by design and is used for app updates or reward rollovers. A way to reset all PlayerPrefs in Unity is Edit > Delete Player Prefs, but be careful as this will delete all PlayerPrefs for the active project. There is also a button in the demo scenes provided named ‘Delete Pleebie Jeebies Player Prefs’ which is tied to a reset method. This method will clear only the PlayerPrefs used in this asset and is very helpful for any pre-production testing desired.

In terms of persistence, PlayerPrefs will persist between scenes and through an app update, but not through an app delete and reinstall. For complete persistence and to avoid data manipulation, developers should both encrypt their data and store it in a database server. If this is desired, all PlayerPref calls will need to be replaced with appropriate database calls.

This asset also uses PlayerPrefs to create timestamps which can be manipulated by changing the time on the device running the app. This is an issue for any programmer who uses timestamps in any way. Again to avoid this, a server time could be used to avoid any checking of the local device time, but this would require apps to force an internet connection and if one isn’t present, the check would fall back on to the local device time and thus cause the same problem. This means developers must choose between forcing their users to have internet and losing any ‘offline’ users or to allow users to manipulate time or data. Most users are not inclined to change their device time as this can intrude with many other applications and ‘cheaters’ tend to manipulate save files instead of device time. Since forcing internet connection is not ideal for most users and for other reasons mentioned, server time is not an available feature for this asset and only uses local device time.


If you are experiencing any issues, contact our support team at:
support@pleebiejeebies.com

Pleebie Jeebies Company Logo

Back to Top of Page