Integrating with Epic #

Epics Offers and Game Store #

You can map a Pragma offer to any type of Epic Offer.

Start by checking out the Epic Offers docs.

Plugin configuration #

All Epic configuration values can be found under Product Settings in the Epic developer portal.

You will need to reach out to Epic to get your client access to the ECOM web APIs.

• Open a private support ticket.
• Provide your client id and ask that its policy allow the V1 ECOM web APIs.

YAML

social:
  shared:
    configs:
      Epic:
        class: "pragma.shared.EpicCredentialsConfig"
        config:
          clientId: "[client-id]"
          clientSecret: "[encrypted-client-secret]" # encrypted value
          deploymentId: "[deployment-id]"
          sandboxId: "[sandbox-id]"
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Epic:
          class: "pragma.account.EpicIdentityProviderPlugin"
          config:
            sharedConfigKey: "Epic"
            playerLoginEnabled: true
            showPortalLoginButton: true
            accountLinkingEnabled: true
            accountLinkingCooldownInDays: 30
    ThirdPartyNodeService.orderProviderPlugins:
      plugins:
        Epic:
          class: "pragma.order.EpicOrderProviderPlugin"
          config:
            sharedConfigKey: "Epic"                   

Encrypting config values

All secrets must be encrypted and decrypted per shard. Shards use different encryption keys.

1. Connect to the VPN using the *.ovpn file provided to you during onboarding.
2. Navigate to your Homebase API URL: https://api.homebase.<studioname>.pragmaengine.com/
3. Choose /secrets/encryptV1
4. Enter the following values in the request body:
   1. shardId - The name of the shard you are encrypting a value for.
   2. titleId - The working title of your game that uses the secret.
   3. value - The secret you’re encrypting.

Your encrypted secret will appear below in the Responses section.

Portal

Any configuration set through the portal will override any values assigned in a config yml file.

• Do not manually encrypt any secrets. The API automatically encrypts all sensitive values during submission.
• You only need to enter credential values in one form. Portal will store credentials under shared config.

Order provider configuration #

1. Navigate to the Order Providers page: select the Commerce Tab → Order Providers in side menu.
2. Select platform to configure and fill out the form.
3. Click Confirm to see changes.
4. Click Deploy to apply changes.

Id provider configuration #

1. Navigate to the ID Provider page: select the Accounts Tab → ID Provider in the side menu.
2. Select a provider and fill out the form.
3. Click Confirm to see changes.
4. Click Deploy to apply changes.

Order mapping example #

The content format depends on the Offer type assigned in Epic.

Ownership source

If the offer is of type: Game, Edition, Demo, Add-on, Season pass, or Digital extra, use the ownership source schema.

[project]/content/src/OrderMappingsSpecs.json

{
    "skuId": "SmallGoldBundle",
    "sources": [
        {
            "provider" : "EPIC",
            "epicSource" : {
                "ownership" : {
                    "audienceItemId" : "[offer-audience-item-id]"
                }
            }
        }
    ]
}

Entitlement source

If the offer type is: Consumable, use the entitlement source schema.

[project]/content/src/OrderMappingsSpecs.json

{
    "skuId": "SmallGoldBundle",
    "sources": [
        {
            "provider" : "EPIC",
            "epicSource" : {
                "entitlement" : {
                    "audienceItemId" : "[consumable-offer-audience-item-id]"
                }
            }
        }
    ]
}

Run the content apply command to validate and generate content catalogs.

./pragma content apply

Testing #

Link an Epic account to a Unsafe account using the player portal #

• This lets you authenticate and call the fulfill orders API through a unsafe account vs having to login with an Epic account.
• You can use the Postman collection for this flow.

Grant offers using Epics Access Keys #

• Epic does not provide a sandbox or dev flow for testing offer purchases.
  • Instead you can generate Access Keys use those to grant an account various offers.
• Access token are scoped to a specific sandbox. The sandbox assigned must match the sandbox configured.
• Don’t generate a large amount, Epic will flag the request for manual review before tokens are available.
• Epic Access Key docs.

Refunds and charge backs #

You can turn on clawbacks through the pragma.order.EpicOrderProviderPlugin.

This will turn on a background poll that will call Epic to get any offers that should be revoked.

Example config with clawbacks enabled

social:
  shared:
    configs:
      Epic:
        class: "pragma.shared.EpicCredentialsConfig"
        config:
          clientId: "[client-id]"
          clientSecret: "[client-secret]"
          deploymentId: "[deployment-id]"
          sandboxId: "[sandbox-id]"
  pluginConfigs:
    ThirdPartyNodeService.orderProviderPlugins:
      plugins:
        Epic:
          class: "pragma.order.EpicOrderProviderPlugin"
          config:
            sharedConfigKey: "Epic"
            clawbackPollIntervalHours: 12 
            clawbackPollingEnabled: true
            maxDaysWorthOfClawbacksToProcess: 10 # required - minimum is 1