Description
This is a detailed overview of the Tiltify Integration Extension for Streamer.Bot. The purpose of this extension is to serve as a foundation for streamers to connect their Streamer.Bot client to Tiltify and to have their own custom actions be triggered by donations to their Tiltify charity campaign.
Video
Requirements
-
Tiltify Account - User will need a Tiltify account in order to gain the necessary access to Tiltify.
-
Tiltify Campaign - User must have an active Tiltify campaign in order for the extension to work properly.
Import Code
Tiltify-StreamerBot Integration v2.1.sb (9.0 KB)
Installation
In the Streamer.Bot client, click on the Import option in the top menu. Drag the downloaded Import Code file into the Import String field. If done correctly, the Import Actions window should match the following image (Figure 1).
After importing the extension, the following items should appear in the Streamer.Bot client under the corresponding tabs:
Actions Tab
- Tiltify - Generic Alert Action
- Tiltify - Recent Donation
- Tiltify - Recent Donation Alert
- Tiltify - Total Raised
Queues Tab
- Tiltify - Access Code
- Tiltify
Timed Actions Tab
- Tiltify - List Donations
Access Token and List Donations are the main actions for the extension. Generic Alert is an example alert action that can be used as a simple alert or an alert action template. Total Raised is an optional action if the user wants to display the current amount raised and the current goal for the Tiltify campaign. Under the Timed Actions Tab (Settings > Timed Actions), the Tiltify - List Donations timer is disabled. Once configuration is complete and all alert actions are linked to the extension, the timer needs to be enabled to begin polling Tiltify.
Configuration
Get Access Token
In order to acquire a Client ID and Client Secret for the Get Access Token action, a Tiltify account is required. From the Tiltify dashboard, access the Developer Hub and create an application. The Redirect URI field needs to be populated in order to create an application, but it is not required for the extension function. For this, http://localhost is used as shown in Figure 2.
After creating an app, a notification will appear indicating that the app was made successfully. Further down the page, there is a blurred section called “Application keys” that will provide the Client ID and Client Secret that are required for the extension to generate an Access Token (accessToken_Tiltify) for Tiltify access. The corresponding sub-actions under the Get Access Token action are then populated with the acquired information (Figure 3).
The extension also requires the user to have an active or published Tiltify charity campaign. From the Tiltify campaign dashboard, the public ID can be found under Information tab of Setup (Figure 4).
List Donations
The List Donations action serves as the trigger for all donation-based alerts. There is a repeating timer called Tiltify - List Donations that serves as the trigger for the List Donations action. With each trigger, the List Donations action polls Tiltify for the latest donation data from the current connected Tiltify campaign. This timer can be adjusted in the Streamer.Bot client under Settings > Timed Actions and is defaulted at 2 second intervals.
Under the List Donations action, the Execute Code (Tiltify Donor Data) sub-action polls data from Tiltify and generates arguments using data from the most recent donation in the Tiltify charity campaign (see table below). These arguments are used in later sub-actions and can be used in alert actions. With each polling, donationIdList_Tiltify, which lists the donationId of the last five donations, is checked to see if it contains the donationId of the most recent Tiltify donation data. If the list does not contain it, donationIdList_Tiltify is updated to add the new donationId and remove the oldest donationId from the list. The other arguments are then generated, and the set alert actions are triggered.
| Argument | Description |
|---|---|
donationId |
Unique identifier assigned to each donation to the Tiltify campaign. This argument is used by the extension to determine whether or not there is a new donation to the Tiltify campaign. The last five donationId are saved and used as reference for new donations. |
donationDate |
Date and time (UTC) of when donation occurs. |
donorName |
Name provided with the donation to the Tiltify campaign. |
donorAmount |
Donation amount (USD) made to the Tiltify campaign. |
donorComment |
Message that donor included with the donation to the Tiltify campaign. |
donorRewards |
List of reward IDs of the rewards claimed with each donation to the Tiltify campaign. Each reward created for the Tiltify campaign is assigned a unique ID and appears in the data when claimed with each donation. |
There are two methods to trigger alert actions built into the List Donations action: Sub-Action Method and C# Method. Both methods are dependent on user preference and the complexity of the alert action triggers. The List Donations action has two different configurations based on the selected trigger alert method used. The Sub-Action Method and C# Method both are functionally similar, but depending on the complexity of the conditions to trigger alerts, the C# Method may be the recommended configuration. If based solely on conditions surrounding the donorAmount argument, the Sub-Action Method will provide a simpler setup. Once alert actions are linked to the List Donations action, the Tiltify - List Donations timer located under Settings > Timed Actions needs to be enabled in order to begin polling Tiltify (Figure 5).
List Donation Methods
| Sub-Action Method | C# Method | |
|---|---|---|
| Pros | Ease of use Relies only on native sub-actions |
Fully Customizable Access to more conditions to trigger alert actions Access to more functions through the Streamer.Bot C# Methods |
| Cons | Limited only to conditions with Limited to native sub-actions |
Requires knowledge of C# programming |
Option A: Subaction Method
The Sub-Action Method uses native Streamer.Bot sub-actions to trigger alert actions and uses a configuration similar to the example shown in Figure 6. This configuration is provided upon installation of the extension, and if no other alerts will be used, it will be ready to be used as-is. Following the Execute Code (Tiltify Donor Data) sub-action, the Run Action sub-action triggers the alert actions. If the user only has one action for all donation alerts, the configuration shown in Figure 6 will be sufficient.
For different triggered alert actions under the Sub-Action Method, the If/Else sub-action is used to set different conditions for alerts as shown in the example in Figure 7. For each If/Else sub-action used, a “Break” must be set if the condition is met, otherwise “Continue” to check the next condition. If donorAmount is used for the conditions of the If/Else sub-actions, it is recommended that sub-actions be organized in descending order especially if comparatives (greater than, less than, etc.) are used. The last sub-action can be a Run Action sub-action for all donations that do not meet any of the established conditions.
Option B: C# Method
The C# Method uses the Execute Code (Donation Alerts) sub-action to trigger all alert actions and uses the configuration as shown in Figure 8. If this method is selected, all sub-actions for the Sub-Action Method must be disabled or removed from the List Donations action. All of the sub-actions used in the Sub-Action Method are already built into the C# code for the Execute Code (Donation Alerts) sub-action. In order to trigger different alert actions, C# conditions and If statements are used as seen in the example below (Figure 9).
//If donorAmount is greater than or equal to $100, trigger Action 3.
if (donorAmount >= 100m)
{
CPH.RunAction("Tiltify - Alerts - Action 3", true);
}
//If donorAmount is greater than or equal to $25, trigger Action 2.
else if (donorAmount >= 25m)
{
CPH.RunAction("Tiltify - Alerts - Action 2", true);
}
//If donorAmount is less than $25, trigger Action 1.
else
{
CPH.RunAction("Tiltify - Alerts - Action 1", true);
}
Once the conditions are satisfied, the native C# method CPH.RunAction() is used to trigger the alert action. For more information on native C# methods in Streamer.Bot, refer to the wiki. Similar to the Sub-Action Method, it is recommended that the conditions be set in descending order if donorAmount is used.
Alerts
Alert actions are triggered based on the conditions set in the List Donations action. When triggered, alert actions will have access to all the arguments generated by the Execute Code (Tiltify Donor Data) sub-action in the List Donations action (see table in List Donations section). The Generic Alert action is a simple example of how these arguments may be used (Figure 10). For the Send Message to Twitch Channel sub-action, the arguments donorName and donorAmount are used in a message to be sent to the Twitch chat (Figure 11).
Total Raised
Total Raised action is an optional feature that generates the following arguments listed in the following table. These arguments can be used to display the current progress of the Tiltify charity campaign. This action can be run by setting it as the last sub-action for each alert action (see example in Figure 10) or by setting a command or timer as the trigger.
| Argument | Description |
|---|---|
currentTotal |
The current amount raised for the Tiltify charity campaign. |
currentGoal |
The current goal set for the Tiltify charity campaign. |
Changelog
Version 2.1
- List Donations action updated.
donorAmountargument updated to function constistently across all cultures. Added CultureInfo.InvariantCulture to the Convert.ToDecimal() fordonorAmount. - Total Raised action updated.
currentTotalandcurrentGoalarguments updated to function consistently across all cultures. Added CultureInfo.InvariantCulture to the Convert.ToDecimal() forcurrentTotalandcurrentGoal.
Version 2.0
- Access Token action renamed to Get Access Token.
- Recent Donation action renamed to List Donations.
- Recent Donation Alert action renamed to Generic Alert.
- Recent Donation timer renamed to List Donations.
- List Donations action updated. Execute Code (Tiltify Donor Data) sub-action updated to perform
donationIdcheck. The past fivedonationIdwill now be saved under the global argumentdonationIdList_Tiltify. All sub-actions related todonationIdhave been removed. - List Donations action updated. Execute Code (Tiltify Donor Data) sub-action updated to include
donorRewardsoutput argument. This new argument will list the IDs of all the rewards claimed with each donation. - List Donations action updated. Sub-actions have been updated to account for the two configurations: Sub-Action Method and C# Method (see List Donation Methods section for more details)
- List Donations updated. The Get Global (
accessToken), If/Else, and Get Global (publicId) sub-actions have been consolidated into the Execute Code (Tiltify Donor Data) sub-action. - List Donations action updated. New Run Action sub-action added to trigger the Generic Alert action.
- List Donations action updated. Execute Code (Tiltify Donor Data) updated to include
donorRewardsargument. - List Donations action updated. Execute Code (Tiltify Donor Data) updated to include condition to trigger Get Access Token action if current Access Token expires.
- List Donations action updated. Execute Code (Tiltify Total Raised) updated to include
currentGoaloutput argument. This argument provides the current charity campaign goal set in Tiltify.
Not an issue tho!