Hosting static files for games

Games are web apps that require different files for work, such as images, HTML pages, or scripts. These files are referred to as static resources, or static files. They are uploaded directly to the user's device without prior server-side processing.

These files must be uploaded to a hosting for users to be able to receive them. VK offers its own hosting for such files. You can also choose any other hosting that supports the HTTPS protocol.

About VK hosting

• •

  The hosting's sole purpose is storing and sharing files, not running server-side code.

• •

  The hosting uses the VK CDN infrastructure to upload files. This boosts upload speed and makes uploading more reliable for users from different regions.

• •

  Adding files to the hosting is free, but with certain limitations on the volume of data sent and the number of updates per day.

• •

  To add files to VK hosting, the vk-miniapps-deploy library is used. This solution is suitable for games that are built using npm or Yarn.

• •

  Switching to VK hosting may require changing the game architecture if the server side and static files currently use the same server. If the static files and server-side logic of the game are separated already, the transition will be easier.

Limitations

• •

  Uploading files to VK hosting is limited to once in 24 hours. This limitation applies to the game itself regardless of the number of admins.

• •

  Previous versions of the files are kept when uploaded again. The hosting stores up to 10 production versions and up to 100 staging versions for every game.

• •

  Maximum size for a ZIP archive for upload is 300 MB.

• •

  Audio and video files cannot uploaded to the hosting.

How to upload game files to hosting

To upload files to the VK hosting, use the vk-miniapps-deploy library.

Step 1. Install library

1. 1.

   Run the command line and go to the folder containing the game files.

   Command line

   cd <path-to-game-folder>
2. 2.

   Install the library:

   Command line

   npm install @vkontakte/vk-miniapps-deploy --include=dev

Step 2. Prepare game files

2.1. Prepare file structure

In the folder containing the game files, create a new folder and transfer all files that must be uploaded to users' devices there. In this example, a folder called build is used. If you use a build system, such as webpack, the respective folder will be created automatically.

2.2. Use VK Bridge events for storing data

When using VK hosting, the app's URL changes after each upload to the hosting. We'll explain this further below. if you use cookies or localStorage for storing data, the stored values will become unavailable after the URL changes.

As a solution, we recommend using the VKWebAppStorageSet, VKWebAppStorageGet and VKWebAppStorageGetKeys events from the VK Bridge library. Values stored this way will be tied to the user’s ID rather than to the browser or device. They're stored indefinitely, so you won’t need to write additional server-side code to store small amounts of data between sessions.

Step 3. Prepare configuration files

1. 1.

   In the game folder, open or create a vk-hosting-config.json file and add JSON code similar to the following:

   JSON

   { "static_path": "build", "app_id": 123456, "endpoints": { "mobile": "index_DG.html", "web": "index.html", "mvk": "index.html" } }

   For a detailed description of the configuration file parameters, see vk-hosting-config.json file.

2. 2.

   Add the deploy and predeploy scripts to the package.json file:

   package.json

   "scripts": { ... "build": "...", "predeploy": "npm run build", "deploy": "vk-miniapps-deploy" }

   The example above assumes that your project has a build script. The predeploy script will run this script before uploading files to the hosting.

3. 3.

   Add the "homepage": "." field to the package.json file:

   package.json

   "scripts": { ... }, "homepage": "."

Step 4. Upload files to hosting

1. 1.

   Execute the following command for uploading files to the hosting:

   Command line

   npm run deploy
2. 2.

   After running the command, the library will request permission to add files to the hosting.

   The request to add files to VK hosting

   Press y or Enter.

3. 3.

   Next, the script will sequentially request your permission to automatically change the URL in the game settings. This will help you avoid changing the settings manually. Accept the following offers:

   • •
     Would you like to update prod urls? — update the game URL.
   • •
     Would you like to update dev urls? — update the game URL in development mode.
   • •
     Would you like to update test group url? — update the game URL for test groups. If you don't have test groups yet, no changes will apply.
   • •
     Enter test group name — if you chose to update the URL for test groups during the previous step, enter the group's name. You may also skip entering the name, which will keep the test group URL unchanged.

   Confirming the URL change is required at each run of the command to upload files to hosting, such as after making changes. This is due to the fact that the hash in the app's URL changes after the files are updated. We recommend allowing the vk-miniapps-deploy library to automatically update the URL.

4. 4.

   If you're uploading files to the hosting for the first time, the library needs to obtain a special access token to do so. In the command line, you'll see a link similar to the following:

   URL to obtain the access token

5. 5.

   Copy the obtained URL and open it in your browser. You'll see a message that VK Mini Apps Hosting now has access to your account.

6. 6.

   Return to the command line and press y or Enter to confirm successful authorization. After that, you'll see a notification that the token has been obtained.

   • •

     The library will save this token on your computer and won't request it during subsequent uploads.

   • •

     The token is required for adding files to the hosting from automatic builds. If you are using or planning to use automation, make sure to copy this token.

Final steps

1. 1.

   The library will package the contents of the build folder into a ZIP archive, upload it to the hosting and extract it there. You can find the archive in the folder where the vk-hosting-config.json file is located.

2. 2.

   After the upload is completed, you'll see the URLs for launching the game in the command line window. These link to the files uploaded to the hosting.

   • •

     If you've allowed the vk-miniapps-deploy library to change the game settings, these URLs will be automatically updated in the game placement settings in the Mobile app, Web and Mobile site version blocks. For details, see the Placement section.

   • •

     If you haven't granted this permission, copy the URLs to the settings manually.

3. 3.

   To check how the game works on VK, open this link: https://vk.com/app<game-id>.

   To check how the game works on OK, connect it to the platform and launch the game via this link: https://ok.ru/game/vk_app<game-id> For details, see Publication on OK.

Possible errors

Error: 5: User authorization failed: invalid session

If you run the npm run deploy command and encounter an authentication error, update the library's access token. To do so, delete the file with the token from your drive:

• •

  On Windows: C:\Users\.config\configstore\@vkontakte\vk-miniapps-deploy.json

• •

  On macOS and Linux: ~/.config/configstore/@vkontakte/vk-miniapps-deploy.json

Then, follow the steps for uploading files to hosting, and the token will be generated again.

Error: 15: Access denied

Verify that the app_id field in the vk-hosting-config.json file contains the correct identifier for your game.

Can't find the access token

1. 1.
   Run the command as described in Error: 5: User authorization failed: invalid session.
2. 2.
   Obtain the access token by completing the sixth step in Step 4. Upload files to hosting.

See more

• •

  Uploading files to hosting from automated builds

• •

  vk-hosting-config.json file