Migration guide from Go Non-modular SDK to Go Modular Extend SDK

Last updated on January 14, 2025

Overview

The AccelByte Go Modular SDK is the latest development SDK which separates each service provided by AccelByte Gaming Services (AGS) into its own module so you can select which services you want to use.

Goals

This guide will describe how to migrate existing Go projects that already use Go Extend SDK to the latest Go Modular Extend SDK.

Migrate existing projects to Go Modular Extend SDK

1. Rename Go imports.

   Rename the imports package name prefix of all the .go files in your project as follows. You can utilize the find and replace feature on your IDE.

   From

   github.com/AccelByte/accelbyte-go-sdk

   To

   github.com/AccelByte/accelbyte-go-modular-sdk
   info

   This step is required because the Go Modular SDK and Non-modular SDK are hosted in a separate repository.

2. Use compatibility modules.

   Compatibility modules have a backward compatibility layer to allow smooth migration from previous non-modular SDKs to modular SDKs so you don't have to do anything after applying these modules.

   Run this command to automatically resolve the required Go Module dependencies.

   go mod tidy

   After running the command, you're already opted in to the Go Modular SDK but are still using the backward compatibility layer modules so you're required to use Go build tags. Go build tags are used to include which Go compatibility modules to include in the build.

   In the following example, we're using AccelByte achievement and iam modules, so we include the compat_achievement and compat_iam tags:

   go build -tags compat_achievement,compat_iam .

   Here's a list of available tags.

   Tag	Description
   compat	Include all AccelByte services modules (similar to non-modular)
   compat_achievement	Include achievement service compatibility modules
   compat_ams	Include ams service compatibility modules
   compat_basic	Include basic service compatibility modules
   compat_cloudsave	Include cloudsave service compatibility modules
   compat_dslogmanager	Include dslogmanager service compatibility modules
   compat_dsmc	Include dsmc service compatibility modules
   compat_eventlog	Include eventlog service compatibility modules
   compat_gametelemetry	Include gametelemetry service compatibility modules
   compat_gdpr	Include gdpr service compatibility modules
   compat_group	Include group service compatibility modules
   compat_iam	Include iam service compatibility modules
   compat_leaderboard	Include leaderboard service compatibility modules
   compat_legal	Include legal service compatibility modules
   compat_lobby	Include lobby service compatibility modules
   compat_match2	Include match2 service compatibility modules
   compat_matchmaking	Include matchmaking service compatibility modules
   compat_platform	Include platform service compatibility modules
   compat_qosm	Include qosm service compatibility modules
   compat_reporting	Include reporting service compatibility modules
   compat_seasonpass	Include seasonpass service compatibility modules
   compat_session	Include session service compatibility modules
   compat_sessionbrowser	Include sessionbrowser service compatibility modules
   compat_social	Include social service compatibility modules
   compat_ugc	Include ugc service compatibility modules

   For convenience, you can include all modules to the build using only the compat tags.

   go build -tags compat .

3. Migrate breaking changes.

   If you're ready for a proper migration to Go Modular SDK, you can start migrating breaking changes.

   • Service wrapper

   Move all service client wrappers from github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/service/* to each service package.

   In the following example, achievement and iam service are moved. The patterns apply to the other services.

   // 1. before (achievement package)
   import "github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/service/achievement"
   var achievementSvc = achievement.AchievementsService{}
   
   // 1. after (achievement package)
   import "github.com/AccelByte/accelbyte-go-modular-sdk/achievement-sdk/pkg"
   var achievementSvc = achievement.AchievementsService{}
   
   //  2. before (iam package)
   import "github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/service/iam"
   var iamSvc = iam.OAuth20Service{}
   
   // 2. after (iam package)
   import "github.com/AccelByte/accelbyte-go-modular-sdk/iam-sdk/pkg"
   var iamSvc = iam.OAuth20Service{}
   • Service factory

   Move all client factory inside packages from github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/factory/* to each service SDK package accordingly.

   In the following example, achievement and iam service are moved. The patterns apply to the other services.

   // Before: factory package containing all client factory
   import "github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/factory"
   var achievementCli = factory.NewAchievementClient(config)
   var iamCli = factory.NewIamClient(config)
   
   // After: client factory reside in each service module
   import "github.com/AccelByte/accelbyte-go-modular-sdk/iam-sdk/pkg"
   import "github.com/AccelByte/accelbyte-go-modular-sdk/achievement-sdk/pkg"
   var achievementCli = achievement.NewAchievementClient(config)
   var iamCli = iam.NewIamClient(config)
   • Local token validator

   If you're using an auth local token validator, it is already moved from github.com/AccelByte/accelbyte-go-sdkservices-api/pkg/utils/auth/validator to github.com/AccelByte/accelbyte-go-sdk/iam-sdk/pkg.

   Example code:

   // Before
   import "github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/utils/auth/validator"
   var tokenValidator = validator.NewTokenValidator(...)
   
   // After
   import "github.com/AccelByte/accelbyte-go-modular-sdk/iam-sdk/pkg"
   var tokenValidator = iam.NewTokenValidator(...)
   • Refresh token scheduler

   Move the files from github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/utils/auth to github.com/AccelByte/accelbyte-go-sdk/iam-sdk/pkg. Note that it may only used be internally inside iam.OAuth20Service.

   Example code:

   // Before
   import "github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/utils/auth"
   auth.RefreshTokenScheduler(session, loginType)
   
   // After
   import "github.com/AccelByte/accelbyte-go-modular-sdk/iam-sdk/pkg"
   iam.NewRefreshTokenSchedulerImpl().Start(session, loginType)

   Finally, tidy up and resolve the required dependencies by running this command.

   go mod tidy