Integrate and Use Provider Entitlements #

To use Pragma Engine’s Provider Entitlement feature, there are several steps that need to be taken:

1. Set up a third-party provider of your choice.
2. Link accounts between the third-party provider and Pragma Engine.
3. Map offerings in Pragma Engine’s Content Data system.
4. Configure the Entitlement Provider Plugin in Pragma Engine.
5. Sync entitlements.
6. (optional) Access provider entitlement history.

Set up a third-party provider #

Before integrating with Pragma Engine, an account with a third-party provider of your choice is needed. We’ll be using the third-party provider to manage store catalogs. This includes setting up item descriptions, regional pricing, and creating and completing purchases. In most cases, this will also involve the use of a third-party provider’s SDK to render an in-game store.

Once a purchase has been completed, the player receives an entitlement on their account in the third-party provider’s system. Pragma Engine then handles the process of granting the entitlement to the player.

For more information on each third-party provider’s system, refer to their respective documentation:

The Provider Entitlement feature allows for integration with multiple third party providers.

Link accounts #

To allow Pragma Engine to fetch entitlements, set up account linking between the chosen third-party provider and Pragma Engine. See Identity Providers for details on how to configure each provider with Pragma Engine.

Set up configuration for fetching linked accounts #

During the SyncEntitlements stage, the service makes a request to the Accounts service to fetch all linked provider identities for players. To allow the Game node to make this request to the Social node, a social bearer token needs to be configured.

To set up this configuration, add a SocialBackendPartnerClientConfig with a bearerToken that has the encrypted Social Partner token.

game:
  serviceConfigs:
    SocialBackendPartnerClientConfig:
      bearerToken: <encrypted social partner token>

Check out the Generate Partner tokens guide if you need help generating Partner tokens.

Map offerings in Pragma Engine #

In this section, we’ll go over defining entitlement content in Pragma Engine’s Content Data system.

Collect the IDs #

To grant players the items from their entitlements, first collect the third-party provider’s generated IDs. These IDs are used by Pragma Engine to know what corresponding content to grant a player when an entitlement is consumed.

In some cases, third-party providers may have different locations for their generated IDs. As shown in the tabs below, Steam has different locations for their Steam Inventory and Steam App IDs.

Author Player Data Operation #

Player Data operations can modify a player’s live data (entities and components) as a result of an entitlement purchase. These Operations must be allowed on the SERVICE SessionType in order to be called from an Entitlement, and are assigned to entitlements under the playerDataOperation property.

See the Player Data Operations docs for more information.

package playerdata.demo.playerdata

import pragma.playerdata.Component
import pragma.playerdata.Context
import pragma.playerdata.PlayerDataContentLibrary
import pragma.playerdata.PlayerDataOperation
import pragma.playerdata.PlayerDataRequest
import pragma.playerdata.PlayerDataResponse
import pragma.playerdata.PlayerDataSubService
import pragma.rpcs.SessionType


data class GrantSkin(
    val id: String,
): PlayerDataRequest
class GrantSkinResponse: PlayerDataResponse

data class Skin(val id: String): Component

class EntitlementModule(
    contentLibrary: PlayerDataContentLibrary
): PlayerDataSubService(contentLibrary) {

    @PlayerDataOperation(sessionTypes = [SessionType.SERVICE])
    fun grantSkin(grantSkin: GrantSkin, context: Context): GrantSkinResponse {
        // can validate skin id against custom content for skins

        // all skins are stored in one unique entity
        val entity = context.snapshot.getOrCreateUniqueEntity("skins")

        // check if player already has this skin
        if (entity.getComponentsByType<Skin>().any { it.id == grantSkin.id }) {
            /* can throw an ApplicationErrorException and the entitlement record status will stay pending - customer support can help resolve */
        }

        // add the new skin and return success response
        entity.addComponent(Skin(grantSkin.id))
        return GrantSkinResponse()
    }
}

 {
    "id": "player-data-demo",
    "playerDataOperation": {
     // `PlayerDataRequestProto`for the `grantSkin` PlayerDataOperation
      "grantSkin": {
        "id": "example_skin"
      }
    },
    "providerDetails": [
      {
        "steamEntitlement": {
          "inventoryItem": {
            "itemDefId": 510
          }
        }
      },
      {
        "epicEntitlement": {
          "audienceItemId": "272f58c3e1a44fb7b486e1832ed6b3d6",
          "offerType": "CONSUMABLE"
        }
      }
    ]
  }

Create provider entitlement content #

Provider entitlement content is defined within content/src/ProviderEntitlements.json. The structure of provider details is specific to each provider. To genereate the Provider Entitlement content files, run make init-provider-entitlement-content.

While mapping entitlements in Pragma Engine, keep in mind that a third-party provider’s generated ID can only be mapped to a single data type in Pragma Engine.

Creating provider entitlement content for each supported third-party provider:

// example ProviderEntitlement.json content object for Epic
{
  "id": "60-elemental-orbs",
  "playerDataOperation": {
    "grantOrbs": {
      "amount": 60
    }
  },
  "providerDetails": [
    {
      "epicEntitlement": {
        "audienceItemId": "<audienceItemId>",
        "offerType": "<offer type>"
      }
    }
  ]  
}

// example ProviderEntitlement content object for Steam
{
  "id": "60-elemental-orbs",
  "playerDataOperation": {
    "grantOrbs": {
      "amount": 60
    }
  },
  "providerDetails": [
    {
      "steamEntitlement": {
        "inventoryItem": {
          "itemDefId": "<itemDefId>"
        }
      }
    },
    {
      "steamEntitlement": {
        "app": {
          "appId": "<appId>" 
        }
      }
    }
  ]
}

 // example ProviderEntitlement content object for Twitch
{
  "id": "60-elemental-orbs",
  "playerDataOperation": {
    "grantOrbs": {
      "amount": 60
    }
  },
  "providerDetails": [
    { 
      "twitchDrop": { 
        "rewardId": "<rewardId>" 
      } 
    }
  ]  
}

// ProviderEntitlements.json with multiple providers
[
  {
    "id": "60-elemental-orbs",
    "playerDataOperation": {
      "grantOrbs": {
        "amount": 60
      }
    },
    "providerDetails": [
      {
        "steamEntitlement": {
          "inventoryItem": {
            "itemDefId": 10010
          }
        }
      },
      {
        "epicEntitlement": {
          "audienceItemId": "294f58c3e1a44fb7b456j1832er7h3d8",
          "offerType": "CONSUMABLE"
        }
      },
      { 
        "twitchDrop": { 
           "rewardId": "df1e2846-be27-4188-8da9-665aa0a2204d" } 
      }
    ]
  },
  {
    "id": "founders-edition-bundle",
    "playerDataOperation": {
      "specialEditionGrants": {
        "id": "founders-edition"
      }
    },
    "providerDetails": [
      {
        "steamEntitlement": {
          "app": {
            "appId": 2215760
          }
        }
      },
      {
        "epicEntitlement": {
          "audienceItemId": "7fa45ecd47e243e6b55dd0dec34f12cb",
          "offerType": "EDITION"
        }
      }
    ]
  }
]

Apply content data #

In order to register the content you just defined with Pragma Engine, you must apply your content data changes. You may apply content data either using the command line with make or via an IntelliJ run configuration.

make ext-contentdata-apply

If the JSON is not valid, Pragma Engine returns an error message and the content will not be applied.

Configure the Entitlement Provider Plugin #

The following are supported preimplemented plugins for third-party providers:

For third-party providers not listed, studios can implement a custom Entitlement Provider Plugin. See the Create a Custom Entitlement Provider Plugin section for more information.

To enable integration with your chosen third-party providers, configure the appropriate plugin in your Pragma Engine config:

Pragma Engine allows for simultaneous integration with multiple third-party providers.

Create a custom Entitlement Provider Plugin #

Pragma Engine offers the flexibility to create custom Entitlement Provider Plugins to integrate with any third-party provider.

Below is a plugin interface to implement a custom Entitlement Provider Plugin. Refer to the inline comments for detailed instruction:

data class Entitlement(val id: String, val thirdPartyItemId: String)

/**
* Plugin interface used to manage entitlement fulfillment with a third party provider.
*/
interface EntitlementProviderPlugin: PragmaServicePlugin {
  /**
  * A unique ID for the provider this plugin is implemented for.
  * Used when mapping entitlements returned from [fetchPlayerEntitlements] to
  * content configured in `ThirdPartyEntitlementMappings.json`
  *
  * @returns a string representing an ID of the provider, ex: "EPIC", "TWITCH", etc.
  */
  fun entitlementProviderId(): String


  /**
  * Used by the Inventory Service to obtain a full view of the player's entitlements in
  * the third party provider. These results will be used to determine if any
  * Pragma content should be granted to the player's inventory.
  *
  * Note: Unconsumed entitlements that are returned from this method will be passed back
  * to [markEntitlementsConsumed] once they have been marked for fulfillment internally  
  * in Pragma.
  *
  * @returns all active basic entitlements and all unconsumed entitlements.
  */
  suspend fun fetchPlayerEntitlements(
    playerId: PlayerId,
    idProviderAccounts: List<IdProviderAccount>
  ): List<Entitlement>
                    

  /**
  * This method will be invoked with a list of entitlements previously returned by
  * [fetchPlayerEntitlements] that had been successfully marked for fulfillment  
  * internally in Pragma.
  */
  suspend fun markEntitlementsConsumed(
    playerId: PlayerId,
    idProviderAccounts: List<IdProviderAccount>, entitlements: List<Entitlement>
  )

  /**
  * if the [ProviderEntitlement] has [ProviderDetails] for this plugin's provider, 
  * return the thirdPartyItemIds from those details
  */
  fun getThirdPartyItemIdsForProvider(providerEntitlement: ProviderEntitlement):       
    List<String> = listOf()
  }

Sync entitlements #

Use Pragma Engine’s InventoryRpc.SyncEntitlementsV1 endpoint to give players the corresponding content listed in their entitlements. This call can be made any time we want to check when a player’s account has been given an entitlement, such as on login or purchase completion.

The following is the information returned on entitlements:

• FulfilledEntitlements are entitlements that have been granted to a player and are now marked as fulfilled by Pragma Engine.
• UnfulfilledEntitlements are entitlements that failed to be granted to a player. This can be due to a number of issues; there are available server logs for more details.

// On InventoryService
void SyncEntitlements(FOnCompleteSyncEntitlementsDelegate Delegate);
DECLARE_DELEGATE_OneParam(
  FOnCompleteSyncEntitlementsDelegate,
  TPragmaResult<FPragmaSyncEntitlementsResults>
);

struct FPragmaSyncEntitlementsResults
{
  TArray<FPragma_Inventory_ProviderEntitlementV1> FulfilledEntitlements;
  TArray<FPragma_Inventory_ProviderEntitlementV1> UnfulfilledEntitlements;
};

// On InventoryService
public Future<SyncEntitlementsResults> SyncEntitlements()
public void SyncEntitlements(SyncEntitlementsDelegate completeDelegate)

public delegate void SyncEntitlementsDelegate(Result<SyncEntitlementsResults> result);

public class SyncEntitlementsResults
{
   public IReadOnlyList<ProviderEntitlementV1> FulfilledEntitlements { get; }
   public IReadOnlyList<ProviderEntitlementV1> UnfulfilledEntitlements { get; }
}

message SyncEntitlementsV1Request {
  option (pragma_session_type) = PLAYER;
  option (pragma_message_type) = REQUEST;
}

/*
* Returns lists of fulfilled and unfulfilled entitlements by their provider and provider
* item ID. Details of the items granted can be looked up in the  
* ProviderEntitlementMappings content file. Subsequent calls will attempt to fulfill
* any unfulfilled entitlements.
*/
message SyncEntitlementsV1Response {
 option (pragma_session_type) = PLAYER;
 option (pragma_message_type) = RESPONSE;

 // List of Provider and Item ID for all entitlements that were fulfilled by this request.
 repeated ProviderEntitlementV1 fulfilled = 1;

 // List of Provider and Item ID for all entitlements that were available
 // but unable to be fulfilled
 repeated ProviderEntitlementV1 unfulfilled = 2;
}

/*
* Represents an entitlement from a specific provider.
*/
message ProviderEntitlementV1 {
 // The identifier of the provider granting the entitlement.
 string provider_id = 1;


 // The provider's identifier of the entitlement,
 // mapped to Pragma Inventory content in ProviderEntitlementMappings.
 string provider_item_id = 2;
}

Access provider entitlement history #

Pragma Engine tracks the processing of player entitlements for player support. There are Operator and Partner endpoints that can be used to access this data.

The GetProviderEntitlementHistory endpoint returns a ProviderEntitlementRecord for each entitlement Pragma Engine has recieved from a configured Provider Entitlement Plugin.

This record includes the following information:

The GetProviderEntitlementHistory endpoint returns a ProviderEntitlementRecord for each entitlement Pragma Engine has recieved from a configured Provider Entitlement Plugin. This record includes information like the status (pending or completed) and the time in milliseconds it took to fulfill the entitlement.

// in PragmaInventoryPartnerServiceRaw

virtual void GetProviderEntitlementHistoryPartnerV1(
  const FPragma_Inventory_GetProviderEntitlementHistoryPartnerV1Request& Request,
  FGetProviderEntitlementHistoryPartnerV1Delegate Delegate
) const;

virtual void GetProviderEntitlementHistoryPartnerV1(
  const FPragma_Inventory_GetProviderEntitlementHistoryPartnerV1Request& Request,
  TUniqueFunction<
    void(TPragmaResult<FPragma_Inventory_GetProviderEntitlementHistoryPartnerV1Response>,
      const FPragmaMessageMetadata&)> Callback
) const;
};

// In InventoryServiceRaw.cs

public virtual void GetProviderEntitlementHistoryPartnerV1(
    GetProviderEntitlementHistoryPartnerV1Request request,
    Protocol.OnComplete<GetProviderEntitlementHistoryPartnerV1Response> callback)
{
    Connection.Game.SendMessage(request, callback);
}

public RpcFuture<GetProviderEntitlementHistoryPartnerV1Response>
    GetProviderEntitlementHistoryPartnerV1(
        GetProviderEntitlementHistoryPartnerV1Request request)
{
    return Connection.Game
        .SendMessage<GetProviderEntitlementHistoryPartnerV1Request,
            GetProviderEntitlementHistoryPartnerV1Response>(request);
}

message GetProviderEntitlementHistoryPartnerV1Request {
  option (pragma_session_type) = PARTNER;
  option (pragma_message_type) = REQUEST;

  // The playerId to return records for
  Fixed128 player_id = 1;
  // The index of the page to view for pagination.
  int32 page_index = 2;
  // The size of the page to view for pagination, equivalent to the entry count of historical purchases.
  int32 page_size = 3;
}

message GetProviderEntitlementHistoryPartnerV1Response {
  option (pragma_session_type) = PARTNER;
  option (pragma_message_type) = RESPONSE;

  // list of player's entitlement history records
  repeated ProviderEntitlementRecord provider_entitlement_records = 1;
}

message GetProviderEntitlementHistoryOperatorV1Request {
  option (pragma_session_type) = OPERATOR;
  option (pragma_message_type) = REQUEST;

  // The playerId to return records for
  Fixed128 player_id = 1;

  // The index of the page to view for pagination.
  int32 page_index = 2;

  // The size of the page to view for pagination, equivalent to the entry count of historical purchases.
  int32 page_size = 3;
}

message GetProviderEntitlementHistoryOperatorV1Response {
  option (pragma_session_type) = OPERATOR;
  option (pragma_message_type) = RESPONSE;

  // list of player's entitlement history records
  repeated ProviderEntitlementRecord provider_entitlement_records = 1;
}