Android SDK

GG SDK là bộ thư viện để các ứng dụng có thể tương tác với GG Platform. GG SDK bao gồm các chức năng chính như sau:

• Đăng nhập bằng tài khoản GG, Apple, Zing, Facebook, PlayNow.
  
• Hỗ trợ ứng dụng lấy thông tin profile của người dùng.
  
• Hiện tại GG SDK hỗ trợ tất cả các thiệt bị sử dụng hệ điều hành Android 4.3 (API 18) trở lên.

Tham khảo: Code Demo

App demo:

• 2048
• Hexagonal

Tích hợp

1. Thêm GG SDK vào dự án

Trong file settings.gradle thêm Maven url:

dependencyResolutionManagement {
    ...
    repositories {
        ...
        maven {
            url 'https://nexus-repo.vnggames.app/repository/maven-public/'
        }
    }

}

Trong file build.gradle của app module thêm GG SDK dependency:

implementation('vnggames.app:ggsdk:0.6.0') {
    // Có thể bỏ qua dependency này nếu bạn không dùng tính năng lưu accessToken vào storage,
    // hoặc không muốn mã hoá thông tin trước khi lưu
    exclude group: 'androidx.security', module: 'security-crypto'

    // Có thể bỏ qua dependency này nếu bạn không dùng tính năng SDK giúp xử lý
    // đăng nhập bằng facebook, mà muốn tự lấy Facebook accessToken
    exclude group: 'com.facebook.android', module: 'facebook-login'
}

Thông tin các dependencies mà GG SDK đang sử dụng:

implementation 'androidx.browser:browser:1.0.0'
implementation 'com.squareup.retrofit2:converter-gson:2.4.0'
implementation 'androidx.security:security-crypto:1.0.0'
implementation "com.facebook.android:facebook-login:15.2.0"

2. Cấu hình dự án

Để đăng ký ứng dụng, bạn vui lòng liên hệ qua email BaoNQ3 để lấy thông tin clientId và clientToken.
Sau đó làm theo các buớc dưới đây để tích hợp GG SDK vào dự án của bạn:

a. Thêm đoạn mã sau vào file string.xml và AndroidManifest.xml của ứng dụng:

Trong file strings.xml

<string name="appId">clientId</string>
<string name="clientToken">clientToken</string>
<string name="gg_login_protocol_scheme">gg-clientId</string>

Trong file AndroidManifest.xml

<manifest
    ...
    <uses-permission android:name="android.permission.INTERNET" />

    // Từ API 30 (Android 11) cần thêm khai báo cần thiết cho package visibility
    <queries>
        <intent>
            <action android:name="vn.com.vng.gg.intent.action.OAUTH_LOGIN" />
        </intent>
    </queries>

    <application
        android:name=".SampleApplication"...>
        ...

        <meta-data
            android:name="vn.com.vng.gg.ggsigninsdk.appId"
            android:value="@string/appId" />

        <meta-data
            android:name="vn.com.vng.gg.ggsigninsdk.clientToken"
            android:value="@string/clientToken" />

        <activity
            android:name="vn.com.vng.gg.ggsigninsdk.login.GgCustomTabActivity"
            android:configChanges="screenSize|orientation"
            android:exported="true"
            android:launchMode="singleTask">

            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="@string/gg_login_protocol_scheme" />
            </intent-filter>
        </activity>
        ...
    </application>
</manifest>

b. Thay thế client_id bằng giá trị Client Id của ứng dụng của bạn.

c. Thay thế client_token bằng giá trị Client Token của ứng dụng của bạn.

d. Để đăng nhập GG SDK bằng Facebook, vui lòng đăng ký và cấu hình ứng dụng của bạn theo hướng dẫn tại Facebook Login for Android - Quickstart

3. Khởi tạo GG SDK

Khởi tạo GG SDK trong method onCreate của Application

 class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // init the sdk
        GgSignInSDK.initialize(this)
    }
}

Đăng nhập

1. Đăng nhập bằng GG

val permissions = arrayOf(
    "profile.userid",
    "profile.displayname",
    "profile.avatar",
)
// Có thể tuỳ chỉnh cấu hình login nếu muốn thay đổi giá trị mặc định
val authConfiguration = GGAuthConfiguration().apply {
    storeAccessToken = true
    // true: sdk sẽ lưu accessToken vào storage
    // false: sdk chỉ giữ accessToken trên session của ứng dụng
}
GgSignInSDK.authenticate(
    permissions,
    configuration = authConfiguration,
    listener = object : OAuthCompleteListener {
        override fun onSuccess(result: AuthenticationResult) {
           // Đăng nhập thành công, có thể lấy kết quả đăng nhập từ SDK
           val accessToken = result.accessToken
           val tokenType = result.tokenType
           val refreshToken = result.refreshToken
           val userId = result.userId
           val socialId = result.socialId
           val socialAccessToken = result.socialAccessToken

        }

        override fun onError(errorCode: String, message: String) {
            // Đăng nhập có lỗi xảy ra
        }
    })

2. Đăng nhập bằng Facebook

val facebookAuthProvider = FacebookAuthProvider().apply {
   // Có thể dùng access token sẵn có của ứng dụng trong trường hợp không dùng Facebook login của GG SDK
   credential = FacebookCredential(accessToken = "Facebook access token",)
   // Có thể tuỳ chỉnh Facebook permissions theo mong muốn
   permissions = listOf("email", "public_profile")
}

GgSignInSDK.authenticate(
   facebookAuthProvider,
   permissions,
   listener = object : OAuthCompleteListener {
      override fun onSuccess(result: AuthenticationResult) {

      }

      override fun onError(errorCode: String, message: String) {
         // Đăng nhập có lỗi xảy ra
      }
   })

3. Đăng nhập bằng Google

val googleAuthProvider = GoogleAuthProvider()
// Có thể dùng access token sẵn có của ứng dụng trong trường hợp không dùng Google login của GG SDK
googleAuthProvider.credential = GoogleCredential(accessToken = "google access token")
GgSignInSDK.authenticate(
   googleAuthProvider,
   arrayOf(),
   listener = object : OAuthCompleteListener {
      override fun onSuccess(result: AuthenticationResult) {

      }

      override fun onError(errorCode: String, message: String) {
         // Đăng nhập có lỗi xảy ra
      }
   })

4. Đăng nhập bằng Apple

val authConfiguration = GGAuthConfiguration().apply {
   ...
   authMethod = AuthMethod.APPLE
   // Tuỳ chỉnh cách hiển thị màn hình đăng nhập nếu cần thiết
   // Tham khảo mục [AuthMode] bên dưới 
   authMode = AuthMode.SELECT_ACCOUNT
}
GgSignInSDK.authenticate(
   permissions,
   configuration = authConfiguration,
   listener = object : OAuthCompleteListener {
      override fun onSuccess(result: AuthenticationResult) {

      }
      override fun onError(errorCode: String, message: String) {
         val error = "errorCode= ${errorCode}, message= $message"
         Toast.makeText(requireContext(), error, Toast.LENGTH_SHORT).show()
      }
   })

AuthMode

Tham khảo AuthMode chi tiết ở AuthMode

5. Đăng nhập bằng Zing

val zingAuthProvider = ZingAuthProvider()
zingAuthProvider.credential = ZingCredential("accountName", "md5(password)")
GgSignInSDK.authenticate(
   zingAuthProvider,
   permissions,
   listener = object : OAuthCompleteListener {
      override fun onSuccess(result: AuthenticationResult) {

      }
      override fun onError(errorCode: String, message: String) {
         val error = "errorCode= ${errorCode}, message= $message"
         Toast.makeText(requireContext(), error, Toast.LENGTH_SHORT).show()
      }
   })

6. Chơi ngay

val authConfiguration = GuestAuthConfiguration().apply {
    storeAccessToken = false
}
GgSignInSDK.authenticateGuestAccount(
    configuration = authConfiguration,
    readPermissions = permissions,
    listener = object : OAuthCompleteListener {
       override fun onSuccess(result: AuthenticationResult) {
          // Đăng nhập thành công, có thể lấy accessToken,tokenType và refreshToken từ SDK
          val accessToken = result.accessToken
          val tokenType = result.tokenType
          val refreshToken = result.refreshToken
       }

        override fun onError(errorCode: String, message: String) {
            // Đăng nhập có lỗi xảy ra
        }
    })

7. Trường thông tin người dùng

Tham khảo tài liệu Trường thông tin người dùng (scopes)

8. Quick Login / Create Guest

fun createGuest(
   readPermissions: Array<String>,
      configuration: GuestAuthConfiguration = GuestAuthConfiguration(), 
      listener: OAuthCompleteListener
      ) 

Parameter	Type	Description
readPermissions	Array<String>	Required. The list of permission
configuration	GuestAuthConfiguration	Required. The auth configuration
listener	Interface	Required. The lisenter callback with data

val permissions = arrayOf(
    "profile.userid",
    "profile.displayname",
    "profile.avatar",
)
val authConfiguration = GuestAuthConfiguration().apply {
    storeAccessToken = false
}
GgSignInSDK.createGuest(
    configuration = authConfiguration,
    readPermissions = permissions,
    listener = object : OAuthCompleteListener {
       override fun onSuccess(result: AuthenticationResult) {
          // Đăng nhập thành công, có thể lấy accessToken,tokenType và refreshToken từ SDK
          val accessToken = result.accessToken
          val tokenType = result.tokenType
          val refreshToken = result.refreshToken
       }

        override fun onError(errorCode: String, message: String) {
            // Đăng nhập có lỗi xảy ra
        }
    })

9. Quick Login / Bind Guest

fun bindGuest(
        authProvider: AuthProvider?,
        readPermissions: Array<String>,
        configuration: GGAuthConfiguration = GGAuthConfiguration(),
        listener: OAuthCompleteListener
    )

Parameter	Type	Description
authProvider	AuthProvider	Optional. The social auth providing when use: Facebook,Google,ZingId
readPermissions	Array<String>	Required. The list of permission
configuration	GGAuthConfiguration	Required. The auth configuration
listener	Interface	Required. The lisenter callback with data

Example Khi tích hợp với Email, Phone

GgSignInSDK.bindGuest(
      authProvider = null,
      readPermissions = permissions,
      configuration = GGAuthConfiguration(),
      listener = object : OAuthCompleteListener {
         override fun onSuccess(result: AuthenticationResult) {
            loginResult = result
            loading.dismiss()
            showProfile(true)
            loadProfile()
         }

         override fun onError(errorCode: String, message: String) {
            handler.removeCallbacksAndMessages(null)
            loading.dismiss()
            val error = "errorCode= ${errorCode}, message= $message"
            showMessage(error)
         }

      }
);

Example Khi tích hợp với Socials

val googleAuthProvider = GoogleAuthProvider().apply {
   credential = GoogleCredential(jsonObject.optString("access_token")).apply {
      refreshToken = jsonObject.optString("refresh_token")
      expiresIn = jsonObject.optLong("expires_in")
   }
}
val handler = Handler(Looper.getMainLooper())

val authConfiguration = GGAuthConfiguration().apply {
   authMethod = AuthMethod.GOOGLE
}

handler.postDelayed({
   loading.show()
}, 500)
GgSignInSDK.bindGuest(
   authProvider = googleAuthProvider,
   readPermissions = permissions,
   configuration = authConfiguration,
   listener = object : OAuthCompleteListener {
      override fun onSuccess(result: AuthenticationResult) {
            loginResult = result
            loading.dismiss()
            showProfile(true)
            loadProfile()

      }

      override fun onError(errorCode: String, message: String) {
            handler.removeCallbacksAndMessages(null)
            loading.dismiss()
            val error = "errorCode= ${errorCode}, message= $message"
            showMessage(error)
      }

   }
);

10. Đăng ký Zing

val authConfiguration = GGAuthConfiguration().apply {
   authMethod = AuthMethod.ZING_SIGN_UP
}
GgSignInSDK.authenticate(
      permissions,
      configuration = authConfiguration,
      listener = object : OAuthCompleteListener {
         override fun onSuccess(result: AuthenticationResult) {
            // success callback
         }

         override fun onError(errorCode: String, message: String) {
            // error callback
         }
      })

Đăng xuất

Khi người dùng đăng xuất khỏi ứng dụng, bạn có thể gọi hàm sau để xoá thông tin người dùng được lưu trong cache của GGSDK.

GgSignInSDK.logout()

Cài đặt cho GGSDK

1. Cài đặt ngôn ngữ

GgSignInSDK.setLanguage("vi")

Tham khảo ngôn ngữ hỗ trợ

2. Cài đặt những kênh đăng nhập social được hỗ trợ

Để cấu hình các kênh đăng nhập được hỗ trợ trong ứng dụng Android, hãy gọi GgSignInSDK.setSupportedSignInMethods(...) và truyền vào một mảng các AuthMethod tương ứng:

GgSignInSDK.setSupportedSignInMethods(
   arrayOf(
      AuthMethod.FACEBOOK,
      AuthMethod.GOOGLE
   )
)

Các phương thức hỗ trợ (AuthMethod enum):

AuthMethod.FACEBOOK        // "facebook"
AuthMethod.GOOGLE          // "google"
AuthMethod.APPLE           // "apple"
AuthMethod.ZING            // "zing"
AuthMethod.GG              // "gg"
AuthMethod.EMAIL           // "email"
AuthMethod.PHONE_NUMBER    // "phone_number"

⚠️ Lưu ý:
Nếu bạn bật AuthMethod.ZING_SIGN_UP, thì bắt buộc cấu hình AuthMethod.ZING trong setSupportedSignInMethods.

Ví dụ cấu hình đầy đủ:

GgSignInSDK.setSupportedSignInMethods(
   arrayOf(
      AuthMethod.FACEBOOK,
      AuthMethod.GOOGLE,
      AuthMethod.APPLE,
      AuthMethod.ZING,
      AuthMethod.EMAIL,
      AuthMethod.PHONE_NUMBER
   )
)

Open API

Lấy thông tin người dùng

GgSignInSDK.getProfile(tokenType, accessToken, object : GetProfileListener {
   override fun onSuccess(response: GetProfileResponse) {
      // Lấy thông tin người dùng thành công
      tvName.text = response.displayName
      ivAvatar.image = response.avatar
   }

   override fun onError(errorCode: String, message: String) {
      // Có lỗi xảy ra
   }
}
)

Kiểm tra access token

 GgSDKOpenApi.validateAccessToken(accessToken,
   object : CheckAccessTokenListener {
      override fun onSuccess(result: AccessTokenValidationResult) {
         if (result.active) {
            // Access token là hợp lệ
            // Có thể lấy được thời điểm access token hết hạn
            result.expiresAt
         } else {
            // Access token là không hợp lệ
            // Nguyên nhân được đính kèm theo link dưới
            result.inactiveReason
         }
      }
      override fun onError(errorCode: String, message: String) {

      }
   })

Chi tiết nguyên nhân access token không hợp lệ và thông tin về kết quả tại đây

Refresh token

GgSDKOpenApi.refreshToken(refreshToken,
   object : OAuthCompleteListener {
      override fun onSuccess(result: AuthenticationResult) {

      }

      override fun onError(errorCode: String, message: String) {

      }
   })

Revoke access token

GgSDKOpenApi.revokeAccessToken(accessToken,
   object : RevokeAccessTokenListener {
      override fun onSuccess() {

      }
      override fun onError(errorCode: String, message: String) {

      }
   })

Xoá tài khoản

 GgSDKOpenApi.deleteAccount(accessToken,
   object : DeleteAccountListener {
      override fun onSuccess() {

      }

      override fun onError(errorCode: String, message: String) {

      }
   })

Mở trang giới thiệu về GG

GgSignInSDK.openAboutGG(context)

Môi trường Sandbox

Bạn có thể chuyển sang môi trường sandbox bằng câu lệnh sau:

GgSignInSDK.initialize(application)
   ...
 val configuration = GgConfiguration().apply {
    sandbox = true
}
GgSignInSDK.setConfiguration(configuration)

Mã lỗi

Tham khảo mã lỗi chi tiết ở Mã lỗi đăng nhập

Mã lỗi từ GG SDK trên Android

Mã lỗi	Mô tả
cancel	Người dùng huỷ quá trình xác thực
login_failed	SDK gặp phải lỗi không xác định

Ví dụ:

GgSignInSDK.authenticate(
    permissions,
    configuration = authConfiguration,
    listener = object : OAuthCompleteListener {
        override fun onSuccess(result: AuthenticationResult) {

        }

        override fun onError(errorCode: String, message: String) {
            if (errorCode == "cancel") {
                Toast.makeText(requireContext(), "Bạn đã bỏ qua đăng nhập", Toast.LENGTH_SHORT).show()
                return
            }
            if (errorCode == "login_failed") {
                Toast.makeText(requireContext(), "Login bị lỗi", Toast.LENGTH_SHORT).show()
                return
            }
        }
    })

Nhật ký thay đổi phiên bản

Theo dõi thay đổi của từng phiên bản tại đây.

Hỗ trợ

Nếu có thắc mắc trong quá trình tích hợp, bạn có thể liên hệ trực tiếp qua email BaoNQ3 để được trợ giúp.