Bulk Importer and Exporter Tool

A tool to assist with stat and achievement management

You can use the Bulk Importer/Exporter Tool to manage your product's stats and achievements outside of the Developer Portal interface. The tool uses .zip archives containing CSV-formatted data, so you can view and edit your stats and achievements in a wide variety of existing programs or your own tools.

The bulk import tool only affects the definitions of your stats and achievements. It does not add, delete, or change your users' progress in any way. If you delete and recreate your stats or achievements definitions, your users' stat and achievement progression remains intact.

You can find this tool on the Developer Portal, under Games Services > Achievements. The Bulk Import/Export button exists between the Player Lookup and Create New buttons near the top.

Exporting (Step 1)

The export process creates a zip archive for download. This archive contains .csv and .png image files of all existing stats and achievements for your product.

These files adhere to the standard .csv format for easy import and export with most spreadsheet software applications. Your image files should be in standard .png format before exporting.

To start the export, simply select Export Current Achievements. The download automatically begins and creates a .zip folder wherever your downloaded content is typically stored.

If you only want to export your data, you can select Export Current Achievements and cancel or X out of the modal at this step.

You can also skip exporting by selecting Next. If you do not have a backup of your current achievements, it is not recommended to skip this step.

Importing (Step 2 and 3)

Importing achievements and stats erase and override the current achievements and stats. Be sure you have a backup of your achievements and stats in case you need to revert your changes.

The import process follows the same file format as the export process. Your import .zip file should contain the following files:

File Name

Contents

stats.csv

A list of "name and type" pairs that define each stat

achievementDefinitions.csv

A list of achievement names, along with the stats they reference

achievementLocalizations.csv

Achievement Localization locale keys and the files names of their icons

One or more .png files

The icons referenced in achievementDefinitions.csv

To help prepare your .zip file for import, you can download our .zip template from the Developer Portal where you would upload your .zip for import (select the Download EOS Achievements Zip Template) or click here. Either option sets off an automatic download of our sample BulkTemplate.zip folder with properly organized content.

Sample of the EOS Achievements Bulk Import template

Before beginning the import process, review the requirements for both your CSV and image files.

Once you are ready to import your files, select Choose File to Upload on Step 2 of the Bulk Import process. Confirm that you have read the notice about the import removing all existing achievements and clears all the stats for your product.

Select Next to begin a validation check for your imported content. Once complete, the backend service deletes all your existing stats and achievements, then replaces them with the ones found in the .zip file. This includes caching any icons that the new achievements use on the backend service.

The final step of the import modal displays the success of your achievements and stats import.

When importing on a live deployment, stat and achievement definitions may be in an incomplete state. As a result, users may not be able to record stats or unlock achievements. To minimize disruption and unexpected behavior for your users, we recommend importing data during your maintenance windows for live deployments.

CSV Format Requirements

To ensure that the .csv files you upload pass the validation check, use to the data format listed below for each file type and avoid leaving any blank lines. All CSV files must be UTF-8 encoded.

stats.csv Format

The stats.csv file has two columns for each stat: the name of the stat and its aggregation type. Supported values for aggregation type are SUM, MIN, MAX, or LATEST. A sample stats.csv file follows:

name,aggregationType
numTreesChopped,SUM
lastTreesChopped,LATEST
maxTreesChopped,MAX
minTreesChopped,MIN
numAxesUsed,SUM

Stat names are in camel case, aggregation types are in all caps, and there are no spaces in each entire line.

See the Stats Interface for more information.

achievementDefinitions.csv Format

The achievementsDefinitions.csv uses three columns to define each achievement and the requirements for unlocking it. The first two columns hold the achievement's internal name and a Boolean value indicating whether the achievement is hidden or not.

The third column is optional; if it is empty, the achievement can only be unlocked by an explicit command from the EOS SDK. When present, the third column is a list of stat names and thresholds, taking the form Stat1:Threshold1;Stat2:Threshold2;StatN:ThresholdN, as shown in the following sample Achievements.csv file:

name,hidden,statThresholds
achvTutorial,FALSE,
achvLumberjack,FALSE,numTreesChopped:3
achvWoodsman,TRUE,numTreesChopped:100;numAxesUsed:5

Internal names are in camel case, the second column is either TRUE or FALSE, and your optional third column uses a stat in camel case with a colon (:) and threshold criteria. There are no spaces in each entire line.

See the Achievements Interface for more information.

achievementLocalizations.csv Format

All user-visible information about achievements is subject to localization.

The achievementLocalizations.csv sets up all the data that the system needs to describe each achievement to users in different locales. This includes the internal name of the achievement and the locale, followed by its title and description when locked, its title and description when unlocked, its flavor text, and its locked and unlocked icons. The following sample achievementLocalizations.csv file shows the default (with the second column empty) and German (with "de" in the second column) versions of the same set of achievements:

name,locale,lockedTitle,lockedDescription,unlockedTitle,unlockedDescription,flavorText,lockedIcon,unlockedIcon
achvTutorial,,Intro,Complete the Tutorial,Intro,Completed the Tutorial,Onwards!,locked.png,tutorial.png
achvTutorial,de,Einführung,Schließe die Einführung ab,Einführung,Die Einführung abgeschlossen,Weiter!,locked.png,tutorial.png
achvLumberjack,,Lumberjack,Chop 3 trees,Lumberjack,Chopped 3 trees,Timber!,locked.png,lumberjack.png
achvLumberjack,de,Holzfäller,Fälle drei Bäume,Holzfäller,Drei Bäume gefällt,Holz!,locked.png,lumberjack_de.png
achvWoodsman,,Woodsman,Roam the woods,Woodsman,Travelled the woods and chopped some trees,,lockedSecret.png,woodsman.png
achvWoodsman,de,Waldmensch,Durschtreife die Wälder,Waldmensch,Die Wälder bereist und Bäume gefällt,,lockedSecret.png,woodsman.png

Be sure there are no spaces at the beginning or end of your values. Some values can contain spaces within the value, such as your locked and unlocked descriptions.

The text entered into the locale (second) column of the .csv file must match the tag formats below:

Locale

Tag

Arabic

ar

Danish

da

Dutch

nl

English (America)

en-US

English (United Kingdom)

en-GB

Finnish

fi

French

fr

German

de

Italian

it

Japanese

ja

Korean

ko

Norwegian

no

Polish

pl

Portuguese (Brazil)

pt-BR

Russian

ru

Simplified Chinese

zh-Hans

Spanish (Mexico)

es-MX

Spanish (Spain)

es-ES

Swedish

sv

Thai

th

Traditional Chinese

zh-Hant

Turkish

tr

On February 23, 2021, the locale codes for English (United Kingdom), Swedish, Traditional Chinese, and Simplified Chinese were updated. Do not import any of your .zips from before this date. Either update those files to match the new locale codes or perform a new export your data.

Icon Requirements

Icons you reference in achievementDefinitions.csv must exist in the current zip archive you import, because all previous content is erased at the time of the new import. All icons must be in .png format and exist at the root level of the archive. Do not have any subfolders in your .zip file.

Icon filenames cannot include the following characters or it produces Developer Portal errors: \ { \^ } % ` ] > [ \~ < # | & $ \@ = ; : + , \? or spaces ' '

To eliminate redundant downloads for your users, achievements can share icons if they refer to the same icon file. Use this capability whenever multiple achievements use the same image, like the "locked" icon for hidden achievements.