Required reading if you're interested in writing applications that can help channels fulfill subscriber rewards
Benefit Delivery is Complicated
This is dense material, but is required reading if you're wanting to work with subscriber benefits at all in your application
Benefit Basics
Benefits and their fulfillment are basically the core of GameWisp. As such, benefits are also the most complicated concept to describe.
When a user subscribes to a channel's tier, they're awarded at least one (but usually several) benefits in exchange for their subscription. These benefits are fulfilled in a myriad of different ways:
- Implicitly by the platform -- For example, you have to be a subscriber with the Early Access Video benefit and specifically be on the GameWisp site to watch early access videos. The Exclusive Video and Subscriber Messaging benefits are also fulfilled natively through functionality directly on the GameWisp platform.
- Automatically -- GameWisp fulfills some benefits automatically. If the benefit can be accomplished by e-mailing all the subscribers that have a particular benefit the exact same information, then it is fulfilled automatically without the channel needing to do anything.
- Manually by the channel -- The channel can fulfill benefits manually. This usually occurs when a channel has to send different information to each subscriber for a benefit (e.g., custom thank you messages, etc.)
- Manually after user input -- The channel can fulfill benefits manually, but sometimes need to wait for specific information from the subscriber (e.g., mailing addresses, twitter soutouts that require the subscribers @handle, etc.)
Regardless of the benefit, whenever it is fulfilled, it is done so using a fulfillment object on the back end. This object links a benefit to whatever action the channel performed to fulfill the benefit.
When you receive benefits and their fulfillment information through Singularity or the REST API, it comes in the form of a benefit-fulfillment pair. The benefit-fulfillment pair is used to fully describe the benefit and whatever the channel did to fulfill it.
The Benefit-Fulfillment Pair
An example benefit-fulfillment pair is shown below. Note that the fulfillment object's benefit_id property matches the id property of the benefit object:
{
benefit: {
id: "3",
delivery: "delivery-messaging",
title: "Subscriber Messaging",
description: "Receive Subscriber-only messages from me.",
channel_data: null,
type: "unknown-type",
month_delay: null,
recurring: false,
recurring_input: false,
receieve_immediately: false,
removed_at: null,
subscriber_limit: null,
tier_bonus: false,
quantity: 1,
multiplier: 1
},
fulfillment: {
id: "54350",
benefit_id: "3",
tier_id: "8781",
channel_fulfillment_response: null,
fulfilled_at: "2015-12-30 21:29:07",
previously_fulfilled_at: null,
disabled_at: null,
user_input: null,
user_input_provided_at: null,
recurring: true,
granted_at: {
date: "2015-12-30 21:29:07.000000",
timezone_type: 3,
timezone: "UTC"
},
channel_cancelled_at: null,
status: "active"
}
}
There's a lot to parse here. The following table breaks down the benefit object:
| Parameter | Type | Description |
|---|---|---|
| id | Integer | The identifier for the benefit. Note that the “Premium Videos”, “Early Access Videos”, and “Subscriber Messaging” benefits will have the same identifier (1, 2, and 3 respectively) across GameWisp channels. |
| delivery | String | The delivery type of the benefit. This parameter describes how the benefit is delivered by GameWisp. Options are: delivery-messaging - Unique to the Subscriber Messaging benefit, indicates that the benefit allows the subscriber to access messaging features for the channel. delivery-video - Unique to the Early Access and Exclusive Video benefits. Indicates that the user can view early access and/or premium videos for the channel on GameWisp. delivery-automatic - Indicates that the benefit’s data is automatically sent to the subscriber upon subscription. delivery-personal - Indicates that the channel must do something specific to this subscriber in order to fulfill the benefit. For example, providing channel currency. This is likely the benefit delivery type of most importance for bots and other applications that generally want to automate some action for a specific user. delivery-personal-input - Indicates that the channel must do something specific to this subscriber, but some input is required by the subscriber. This input is collected on GameWisp, typically after this event has been sent. delivery-none - Nothing is required to be sent to a subscriber, but something is required to be performed by the channel. Examples include giveaways and playing games with subscribers. * delivery-unknown - Error condition. The delivery type isn’t recognized by Singularity. |
| title | String | The title of the benefit |
| description | String | The benefit's description. |
| type | String | The type of the benefit. Can be one of several options. They are as follows: currency-more - More channel currency to the subscriber. currency-multiplier - Multiplier for the amount of currency earned. access-server - Server credentials for games, etc. access-teamspeak - Credentials to access a teamspeak server. access-discord - Access information for a Discord server. giveaways - Access to giveaways performed by the channel. play-games - Access to game playing sessions. subscriber-art - Access to art delivered by the channel. subscriber-music - Access to music delivered by the channel. giftcards - Giftcards for Steam, Origin, etc. videos-exclusive - Access to videos hosted only on GameWisp. videos-early - Access to videos hosted on GameWisp in their early access period. custom - A benefit created custom by the channel. unknown-type - Error condition. The benefit type isn’t recognized by Singularity. |
| month_delay | Integer | The number of months that a benefit should be delayed before it is awarded to the subscriber. This number is always an integer between 1 and 12. It is null if no delay has been specified. |
| recurring | Boolean | Specifies whether or not a benefit recurs. If this is true and a month_delay is specified, the benefit should recur every X months as specified by month_delay. |
| recurring_input | Boolean | Specifies whether or not new input is required from the user each time the benefit recurs. This is only true if the delivery_type is also delivery-personal-input, but can also be false in this case. |
| receieve_immediately | Boolean | Indicates that the user should receive the benefit immediately. This value will only ever be true if month_delay is not null, and can still be false in this case. Otherwise, there is no delay on benefit delivery and the benefit will be delivered immediately regardless of the value for receieve_immediately. |
| removed_at | String formatted UTC DateTime | Indicates that this benefit has been removed from a tier. Subscribers may still have this benefit if they subscribed while the benefit was part of a tier. |
| subscriber_limit | Integer | If not null, indicates the maximum number of subscribers that can have this benefit at any one time. |
| tier_bonus | Boolean | Indicates that this benefit is a tier bonus. As such it does not stack with higher tiers. The currency-more and currency-multiplier benefits are typically tier bonuses. |
| quantity | Integer | The amount of the benefit. Default is 1. This field is currently only relevant for benefits of the type currency-more, but may be expanded to other benefit types in the future. |
| multiplier | Integer | A multiplier on the benefit. Default is 1. This field is currently only relevant for benefits of the currency-multiplier type, but may be expanded to other benefit types in the future. |
The fulfillment object represents how the benefit is fulfilled by the channel. It is described as follows:
fulfillment: {
id: "54350",
benefit_id: "3",
tier_id: "8781",
channel_fulfillment_response: null,
fulfilled_at: "2015-12-30 21:29:07",
previously_fulfilled_at: null,
disabled_at: null,
user_input_provided_at: null,
recurring: true,
granted_at: "2015-12-30 21:29:07.000000",
channel_cancelled_at: null,
status: "active",
user_input: null,
}
user_input is only Accessible through the Subscriber Resource
access user_input requires the 'subscriber_read_full' scope, and is only accessible from the Subscriber Resource (e.g., the /subscriber/subscriptions endpoint)
| Parameter | Type | Description |
|---|---|---|
| id | Integer | The unique identifier for the fulfillment object. |
| benefit_id | Integer | The benefit identifier to which the fulfillment object belongs. In other words, a fulfillment object with benefit_id = 5 was used to fulfill the benefit with id = 5 for that particular channel. |
| tier_id | Integer | The unique identifier of the tier to which the fulfilled benefit belongs. |
| channel_fulfillment_response | String | If the channel provided a response when fulfilling the benefit, it is provided here. |
| fulfilled_at | String formatted UTC DateTime | A timestamp indicating when the benefit was fulfilled. Null if the benefit has not yet been fulfilled. |
| previously_fulfilled_at | String formatted UTC DateTime | The date this benefit was last fulfilled by the channel. This is only non-null if the benefit is recurring and has been fulfilled previously. |
| recurring | Boolean | True if the fulfillment object is for a recurring benefit, false otherwise. |
| granted_at | String formatted UTC DateTime | The time that the benefit was awarded to the subscriber. |
| channel_cancelled_at | String formatted UTC DateTime | The time that the channel cancelled this benefit for the subscriber. Only non-null if the benefit has been cancelled. |
| status | String | The status of the fulfillment for the subscriber. Statuses are as follows: active - The benefit fulfillment is currently active for the subscriber. inactive - The benefit fulfillment is inactive and the subscriber should no longer receive it. delayed - The subscriber has the benefit, but its fulfillment is currently delayed. This occurs most often with recurring / delayed benefits. dismissed-channel - The channel has dismissed this benefit for this subscriber. dismissed-channel-email - The channel has dismissed this benefit for this subscriber and notified the subscriber of doing so via email. dismissed-subscriber - The subscriber dismissed the benefit. This usually occurs when the subscriber does not want a benefit being offered by the channel. cancelled-action-required - The benefit has been cancelled and the channel needs to take some action manually as a result. This action usually entails removing subscribers from third party services (e.g., game server whitelists, giveaway lists, etc.). unknown-status - Error condition. |
| user_input | String | If the user has provided any input that is needed to fulfill this benefit, it will be included here. Only visible for access tokens with the subscriber_read_full scope.* |
Fulfilling Benefits
Remember, currently the REST API and Singularity are read only. So if you want to fulfill a benefit on behalf of a channel, you cannot currently signal to GameWisp that your application has fulfilled that benefit.
It's highly anticipated that this functionality will be incorporated into the API and Singularity in the future, so if you need it, please let us know!