Setup Guide

For products published to the Epic Games Store, you can enhance your product’s user experience with Epic Games Store achievements. These achievements extend the functionality of Epic Online Services achievements and can be used to reward users with experience points (XP) for interacting with your product.

The process for implementing Epic Games Store achievements for your product is outlined below. For general information about Epic Games Store achievements, review Achievements Overview.

To begin, follow the steps below to prepare your product for Epic Games Store achievements:

1. Sign the Epic Online Services Developer Agreement.
   • Note: This step is only required once for your organization.
2. Generate Dev and Stage sandboxes and deployments.
3. Choose a deployment in each sandbox to use with Epic Games Store achievements.

The owner of your organization must read and sign the updated Developer Agreement. You cannot use Epic Games Store achievements until this agreement has been accepted.

To read and sign the agreement, the owner of your organization follows the steps below. Only the organization owner can complete this process. :

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements. Then, select Epic Games Store Achievements.
2. In the Developer Agreement section, click See Agreement.
3. Review the Epic Online Services Developer Agreement and click Accept.

Once the agreement has been signed, continue to Steps 2 and 3 below.

The next step in setting up Epic Games Store achievements includes generating Dev and Stage sandboxes and deployments in your product. Once generated, you then select one deployment in each sandbox as the primary deployment for use with Epic Games Store achievements. Epic Online Services associates all user data for a product, including achievement data, with a specific deployment.

Note: To learn more about sandboxes and deployments, review Product Management.

To generate and select your sandboxes and deployments, follow the steps below:

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements. Then, select Epic Games Store Achievements.
2. In the Generate Sandboxes and Deployments section, click Generate to create new Dev and Stage sandboxes and associated deployments.
   • Note: If Dev and Stage sandboxes containing one or more deployments already exist for your product, skip this step and proceed to step 3.
3. In the Select a Primary Deployment per Sandbox section, choose a primary deployment for each sandbox to contain your Epic Games Store achievements.
   • Tip: For Dev and Stage, select the deployments you are using for pre-production QA. For Live, select the deployment associated with your live product.
4. Review your primary deployment selections. Then, click Submit to complete this process.

Once the setup process is complete, you are ready to create your Epic Games Store achievements!

There are two ways to create Epic Games Store achievements for your product, as follows:

• Define multiple Epic Games Store achievements at once using bulk import.
  • Tip:This method is recommended if you have already added Epic Online Services achievements to your product.
• Define Epic Games Store achievements one at a time using the Dev Portal interface.

The sections below further describe each of these methods.

To add multiple Epic Games Store achievements to your product at once, use the bulk import process. This process involves defining your achievements in a downloaded file, then uploading that information to the Dev Portal.

Note: The bulk import process must be completed in the deployment linked to Epic Games Store achievements in your Dev sandbox.

To begin this process, select one of the following methods to retrieve your starting file:

• Method 1: Export your current Epic Online Services achievements from your Live deployment to a zip file. This option is recommended if you already have achievements defined for your product.
• Method 2: Download the Epic Games Store achievements template to create new achievements.

Once you have your file, you can define and upload and upload your achievements.

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements. Then, select Epic Online Services Achievements.
2. In the Deployment drop-down, select your Live sandbox.
3. To the top right, click Bulk Import / Export.
4. On the Bulk Export form, select Export Current EOS Achievements to download your file. Then, close the form.

Once you have your zip file, review the Define and Upload your Achievements section below for next steps.

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements. Then, select Epic Online Services Achievements.
2. In the Deployment drop-down, select your Dev sandbox.
3. To the top right, click Bulk Import / Export to open the form. Then, click Next.
4. Select Download Epic Games Store Achievements Zip Template to download your file. Then, close the form.
   • Note: If the Epic Games Store Achievements option is not available, ensure you have fully completed the setup process.

Once you have your zip file, review the Define and Upload your Achievements section below for next steps.

Regardless of which starting method you chose, the next step consists of defining your Epic Games Store achievements in the downloaded file. The updated file is then uploaded to the Dev Portal to create your Epic Games Store achievements.

To define and upload your Epic Games Store achievements, follow the process below:

1. On your computer, extract the zip file you downloaded.
2. Open the file labeled achievementDefinitions.csv.
3. In the CSV file, ensure the last column is labeled user_epic_achievements_xp. If this column is not available, add it to the file.
4. Populate the CSV file with the appropriate values for your achievements.
   • Ensure that you include any live Epic Online Services achievements in the file. If you exported your achievements from the Live sandbox, these achievements should already be included.
   • Learn more about usage limitations for achievements.
5. In the user_epic_achievements_xp column, add the desired experience point (XP) value for each achievement.
   • Note: When defining XP values, ensure the appropriate XP requirements are followed.

An example achievement definition in the CSV file.

6. (Optional) Add localized text and associate images with your achievements by editing the achievementLocalizations.csv file.
   • Learn more about achievementLocalizations.csv.
7. Compile your files, including your modified achievementDefinitions.csv file, into a new zip archive. Place all the files at the root level of the zip archive.
8. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements. Then, select Epic Online Services Achievements.
9. In the Deployment drop-down, select your Dev sandbox.
10. To the top right, click Bulk Import / Export to open the form. Then, click Next to advance to the Bulk Import page.
11. Locate the Upload Achievement section at the bottom of the page. Then, review and accept the warning message.
12. Click Choose File to Upload and select your zip archive. Then, click Next to upload the file.

After you import your achievements, ensure they satisfy the criteria specified in the XP (Experience Points) requirements for achievements.

To review your achievements import, follow the steps below:

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements. Then, select Epic Games Store Achievements.
2. Locate the Push to Stage button at the top of the page.
   • If the button is enabled, your achievements passed validation and satisfy the XP requirements.
   • If the button is disabled, your achievements do not meet the XP requirements. Expand the message to review the details of the failed validation. Common errors include missing or incorrect XP values, an XP total that does not equal 1000, incorrect icon file sizes, or exceeded character limits.
3. If one or more errors are present in your achievements, resolve those issues in your CSV file. Then, update your zip archive and reupload the archive following the bulk import process.

You can validate your Epic Games Store achievements in your product before you push them to Stage. To do so, create a build of your product using the Dev sandbox and deployment associated with your achievements during SDK initialization.

If you push your achievements to Live, you can preview them on the Product Detail Page and Achievement Details Page. To do so, first push your achievements to Stage for review and approval.

When you create an Epic Games Store achievement, you link it to an Epic Online Services achievement and assign it an experience point (XP) value. If you do not have a corresponding Epic Online Service achievement available, you can create one through the Dev Portal.

Note: This section explains how to create and link a single Epic Games Store achievement. If you already have Epic Online Services achievements in your product or wish to create multiple achievements, following the process for bulk uploading Epic Games Store achievements is strongly recommended.

Before you can create an Epic Games Store achievement, you must have a corresponding Epic Online Services achievement to associate it with. There are two ways to define Epic Online Services achievements:

• Write some corresponding code in your product before you launch. To learn more, review Epic Online Services achievements.
• Base each Epic Online Services achievement on a stat. For example, to create an achievement that rewards users for traveling a certain distance in a game, first create a stat to track player travel distance. Then, associate the achievement with that stat.

To create an Epic Online Services achievement, follow the steps below:

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements. Then, select Epic Online Services Achievements.
2. In the Deployment drop-down, select the deployment associated with your Dev sandbox.
3. From the options in the top right, click Create New.
4. To base this achievement on a stat, select the desired option from the drop-down. Then, enter the stat value that unlocks the achievement.
5. Click Next.
6. Complete the Create New Achievement form as appropriate:
   • Achievement ID: A unique value that identifies the achievement.
   • Select Locale: The locale for the provided achievement name and description. Unique sets of Epic Games Store achievements can be created for each language the Epic Games Store supports, as needed.
   • Visibility: Determines whether the achievement is displayed to product users before they unlock it.
   • Unlocked Icon: The image the Epic Games social overlay or your product displays to users after they unlock the achievement.
   • Locked Icon: The image displayed to users before they unlock the achievement. Note that this icon is not used by Epic Games Store achievements; instead, Epic Games Store users see a semi-transparent version of the unlocked icon.
   • Locked Display Name: The name displayed to users before they unlock the achievement.
   • Locked Description: The description displayed to users before they unlock the achievement.
   • Unlocked Display Name: The name displayed to users after they unlock the achievement.
   • Unlocked Description: The description displayed to users after they unlock the achievement.
   • Flavor Text Optional: Optional text that you can freely use in your product.
7. After completing the form, click Create to save your new achievement.

Once you have an Epic Online Services achievement available, you can create your Epic Games Store achievement and link the two achievements together. To do so, follow the steps below:

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements. Then, select Epic Online Services Achievements.
2. In the Deployment drop-down, select the deployment associated with your Dev sandbox.
3. In the list of achievements, locate the Epic Online Services achievement you wish to link to your new Epic Games Store achievement.
4. Click the menu icon (...) to the right of the achievement’s row, then select Link Achievements.
5. Enter an XP value for the achievement.
   • Tip: For guidelines, review XP (Experience Points) requirements for achievements.
6. Select Create Link to finalize and save your new Epic Games Store achievement.

Before an Epic Games Store achievement is pushed to Live, you can edit its XP value. Once the achievement is live, this value cannot be modified.

To edit the XP awarded by an Epic Games Store achievement:

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements.
2. In the drop-down above your Epic Online Services achievements, select the deployment associated with your Dev sandbox.
3. Click Epic Games Store achievements. Then, locate the achievement you wish to update.
4. To the right of the achievement’s row, click the menu icon (...) and choose Edit XP.
5. Enter the desired XP value for the achievement.
6. Click Save to finalize your changes.

To delete an Epic Games Store achievement, you unlink the achievement from the associated Epic Online Services achievement. This action removes the Epic Games Store achievement from your product. It does not delete the Epic Online Services achievement.

To unlink and delete an Epic Games Store achievement, follow the steps below:

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements.
2. In the drop-down above your Epic Online Services achievements, select the deployment associated with your Dev sandbox.
3. Click Epic Games Store achievements. Then, locate the achievement you wish to remove.
4. To the right of the achievement’s row, click the menu icon (...) and choose Unlink.
5. Select Remove Link to unlink and delete your Epic Games Store achievement.

In the Epic Games Store, information about your achievements displays on both your Product Details Page and on the dedicated Achievements page available for your product. To preview this information, first ensure the following:

• Your product has been pushed to Live.
• Your product has a catalog item.
• Your product has an offer.

Then, use the following URL to preview your product’s achievements before pushing them live. Replace <product-name> with the name of your product: /store/en-US/achievements/<product-name>

An example achievement details page.

To make your Epic Games Store achievements available to users, the following workflow should be followed:

1. In your Dev sandbox, create your achievements.
2. Push your achievements to your Stage sandbox and submit them for review by the Epic Games Store team.
3. Once approved, push your achievements to the Live sandbox.

Notes:

• When you push Epic Games Store achievements from one sandbox to another, they replace any achievements in the deployment linked to the destination sandbox.
• After an Epic Games Store achievement is live, you cannot adjust its XP value or remove the achievement through the Dev Portal. To delete a published achievement, contact support by creating a private discussion on our Developer Support site.
• To update any text or images associated with your achievements, follow the normal publishing flow as described in this section.

To push your achievements to Stage, follow the steps below:

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements and select Epic Games Store Achievements.
2. From the options to the top right, click Push to Stage.

If the Push to Stage button is disabled and cannot be clicked, it indicates that your achievements contain one or more errors. An alert box on the page lists any available errors; these issues must be resolved before you can proceed.

When your achievements are pushed to Stage, the Epic Games Store team reviews your achievements for any inappropriate content such as mature content, profanity, and asset flips. Note that Epic Games does not moderate unlinked achievements (i.e., Epic Online Services achievements); only Epic Games Store achievements are reviewed. Epic Games Store achievements must abide by the Epic Games Store content guidelines.

If the Epic Games Store team approves your achievements, a message displays at the top of the screen along with a button to push your achievements live.

If the Epic Games Store team rejects any of your Epic Games Store achievements during the review process, a rejection message displays in the Stage sandbox, as shown in the example below:

To view more information about the rejection, click See Details.

To fix the identified issues, switch to your Dev sandbox and complete any necessary updates. Then, resubmit your achievements to Stage for approval.

Note:

• After pushing updates to Stage, you can still make changes at any time before product approval occurs. To do so, cancel the push to Stage and complete the desired updates in your Dev sandbox. When ready, push your updated product to Stage again.
• If you make any changes to an achievement set, you must resubmit the full set of achievements to Stage for review.

Once your Epic Games Store achievements have been reviewed and approved, you can push them live to make them available to users. To do so, follow the steps below:

1. In the Dev Portal, navigate to Your Product > Game Services > Progression > Achievements and select Epic Games Store Achievements.
2. In the Deployment drop-down, select the Stage sandbox.
3. From the options to the top right, click Push to Live.

Note: After an Epic Games Store achievement is live, you cannot adjust its XP value or remove the achievement through the Dev Portal.

• To delete a published achievement, contact support by creating a private discussion on our Developer Support site.
• To update any text or images associated with your achievements, follow the normal publishing flow.

When setting XP (experience point) values for Epic Games Store achievements, you must adhere to the following guidelines:

• Each product must have exactly 1,000 XP* in total, regardless of how many achievements are defined. The total XP currently used for a product displays in the Dev Portal under Your Product > Games Services > Progression > Achievements > Epic Games Store Achievements.
  • An error message displays if you try to add more or less than 1,000 XP for a specific product.
  • Achievements cannot be pushed from Dev to Stage if the product’s total XP does not exactly equal 1,000 (i.e., the total XP cannot be more or less than 1,000).
• The XP value for individual achievements must be a multiple of 5 (e.g., 5, 10, 15, 100, 110, 200, etc.).
• The minimum XP for a single achievement is 5, and the maximum is 200.
• Epic Games Store achievements are classified in bronze, silver, and gold tiers, as follows:
  • Bronze: 5-45 XP
  • Silver: 50-95 XP
  • Gold: 100-200 XP
  • An additional platinum tier achievement is available for users who earn a total of 1,000 XP from a single product.