Twitch Drops Integration

Twitch Setup

This guide is written assuming you've never set up anything related to Twitch. If you have, feel free to skip ahead to relevant sections.

As you go through these steps, record the following 4 important pieces of information, as you'll need them to configure Catena:
The Client Id of your Twitch Application (Step 2)
The Client Secret of your Twitch Application (Step 2)
Your Organization Id (Step 1)
Your Game's Id (Step 1)

Create an Organization
- To create an organization, you are expected to have a game that's already known to Twitch. If you haven't done that, see Adding a Game or Game Cover Art to Twitch.
- Twitch notes that "Processing typically takes one business week," so you'll want to get this step done a short bit before you want to begin testing, otherwise you may find yourself waiting around.
Create a Twitch Application
- For the OAuth Redirect URL, fill it in with the root URL that Catena is running on, plus the following: /api/v1/authentication/PROVIDER_TWITCH_WEB/callback
- The result should look similar to https://catena.reallycoolgame.example.com:5000/api/v1/authentication/PROVIDER_TWITCH_WEB/callback
Create a Reward
1. If you have not yet created an item in Catena that you want to assign as the Twitch Drop, you should do so now.

Once that item has been created, mark down its Catena Catalog Item Id.
Back in the Twitch reward creation, there is an optional "Reward ID" field. Fill that field in with the Catena Catalog Item Id.
Create a Drops Campaign
1. Be sure to check the Test the Drop section of the documentation. You'll need at least two accounts:
  1. One of which will be the Creator that will stream the game.
  2. The other of which will be the viewer that will receive the Twitch Drop(s).

Catena Setup

In the catena-tools-core project, open appsettings.json (or any of its variations).
In the Entitlements section, if it does not exist, add an ExternalItemProviders field. An empty block will look like this:

"ExternalItemProviders": {
  "TwitchDropsProvider": {
    "Database": {
      "ConnectionString": "Data Source=Build/SqliteDatabase/twitch.db;Foreign Keys=True"
    },
    "ClientID": "",
    "Secret": "",
    "GameID": "",
    "OrganizationID":  "",
    "WebHookSecret": "",
    "SkipSignatureVerification": false
  }
}

Fill in the Client ID, Secret, GameID, and OrganizationID fields with the information recorded from the Twitch Setup section.
Fill in the WebHookSecret with a 10-100 character string of your choosing.
Leave the SkipSignatureVerification field as false.
Ensure that the Twitch viewer account that will receive Twitch Drops is connected to a Catena Account.

Verifying Drops w/ Catena

We'll assume here that your Twitch Drops campaign is live and you've already had your two accounts (Creator/Streamer and Test Viewer) successfully earn the Drops through Twitch. What you'll need to do next is ensure that the Drops were successfully obtained by Catena.

Check the Admin Dashboard

Under the Account Data tab, input the Catena Account ID that should have received the drop.
If the item you set up previously is within the Owned Items section, that's a bingo.

If the above fails...

Check the Catena logs.
Check the Catena database files, specifically:
1. Check the accounts_platforms table within the accounts.db file, and ensure that the Test Viewer account has a Twitch platform_type registered.
2. Check the twitch_account_mappings table within the twitch.db file, and ensure that the Test Viewer account is linked there.
3. Check the twitch_drops table within the twitch.db file, and ensure that the drop (labeled as "entitlement") has been delivered.
  - To confirm, you'll want to find the entry that has the appropriate twitch_account_id and benefit_id, where the benefit_id is the Catena Item Id for the item to be delivered.
  - If the entitlement_status is not marked as FULFILLED, that confirms a failure somewhere in the pipeline, after having received the drop.

Testing Internally with Catena

Heads Up!
If you follow this section of the guide, you will not be connecting to Twitch directly. This section of the guide utilizes an emulated layer meant to confirm that Catena alone is working as intended.

Testing and Verifying the Catena Pipeline

If you want to ensure that Catena is working as expected, in Step 5 of Catena Setup, you can flip the SkipSignatureVerification flag to true. Additionally, you will need to include the following field in the PreferredImplementations section:

"PreferredImplementations": {
   ...
   "ITwitchDropsWrapper": "EmulTwitchDropsWrapper"
   ...
}

After doing the above, and assuming that you have already created a Catena Item as per Step 3.1 of Twitch Setup, you'll need to trigger the fake Twitch Drop from an outside source. For now, we'll use Postman.

Postman

Using the address localhost:5000/twitch/drop/callback (or your specified url:port if appropriate), send a POST request with the following body:

{
    "subscription": {
        "id": "test-id",
        "type": "drop.entitlement.grant",
        "version": "1",
        "status": "enabled",
        "condition": {
            "organization_id": "TestOrganization"
        },
        "transport": {
            "method": "webhook",
            "callback": "localhost:5000/twitch/drop/callback"
        },
        "created_at": "2019-11-16T10:11:12.634234626Z"
    },
    "events": [
        {
            "id": "test-event-id-1",
            "data": {
                "organization_id": "TestCatenaOrg",
                "category_id": "TestGameID",
                "category_name": "Very Cool Catena Game",
                "campaign_id": "TestCampaignID",
                "user_id": "<your fake twitch account id here>", // Fill this in
                "user_name": "DisplayName",
                "user_login": "LoginName",
                "entitlement_id": "test-entitlement-id-1",
                "benefit_id": "<your catena item id here>", // Fill this in
                "created_at": "2024-12-01T00:00:00.000Z"
            }
        }
    ]
}

After sending the request, head back to the Verifying Drops section to confirm that you've correctly received the drop.