دسترسی سمت سرور به خدمات بازی های Google Play را فعال کنید

پس از منسوخ شدن رابط برنامه‌نویسی کاربردی ورود گوگل (Google Sign-In API)، ما در سال ۲۰۲۶ کیت توسعه نرم‌افزاری بازی‌ها نسخه ۱ (games v1 SDK) را حذف خواهیم کرد. پس از فوریه ۲۰۲۵، شما قادر به انتشار عناوینی که به تازگی با کیت توسعه نرم‌افزاری بازی‌ها نسخه ۱ (games v1 SDK) ادغام شده‌اند، در گوگل پلی نخواهید بود. توصیه می‌کنیم به جای آن از کیت توسعه نرم‌افزاری بازی‌ها نسخه ۲ (games v2 SDK) استفاده کنید.
در حالی که عناوین موجود با بازی‌های قبلی نسخه ۱ ادغام‌شده تا چند سال دیگر به کار خود ادامه می‌دهند، توصیه می‌شود از ژوئن ۲۰۲۵ به نسخه ۲ مهاجرت کنید .
این راهنما برای استفاده از SDK نسخه ۱ سرویس بازی‌های Play Games Services است. برای اطلاعات بیشتر در مورد آخرین نسخه SDK، به مستندات نسخه ۲ مراجعه کنید.

اگر بازی شما از یک سرور پشتیبان استفاده می‌کند، توصیه می‌کنیم از Google Sign-In برای تأیید هویت بازیکنان و انتقال ایمن هویت بازیکن به سرور پشتیبان استفاده کنید. این کار همچنین به بازی شما امکان می‌دهد هویت و سایر داده‌های بازیکن را به طور ایمن بازیابی کند، بدون اینکه در حین عبور از دستگاه در معرض دستکاری‌های احتمالی قرار گیرد.

در این سناریو، بازی شما از بازیکن می‌خواهد که طبق معمول به سرویس‌های بازی‌های گوگل پلی وارد شود. وقتی بازیکن با موفقیت وارد سیستم می‌شود، شیء GoogleSignInAccount حاوی یک کد یکبار مصرف ویژه (به نام کد احراز هویت سرور ) است که کلاینت به سرور ارسال می‌کند. سپس، در سرور، کد احراز هویت سرور را با یک توکن OAuth 2.0 که سرور می‌تواند برای برقراری تماس با API سرویس‌های بازی‌های گوگل پلی از آن استفاده کند، تعویض کنید.

برای راهنمایی بیشتر در مورد افزودن ورود به سیستم در بازی‌هایتان، به ورود به سیستم در بازی‌های اندروید مراجعه کنید.

برای مشاهده‌ی نمونه کد دقیقی که نحوه‌ی استفاده از Google Sign-In برای احراز هویت بازیکنان را نشان می‌دهد، به نمونه‌ی clientserverskeleton در گیت‌هاب مراجعه کنید.

برای دسترسی آفلاین، مراحل زیر لازم است:

  1. در کنسول گوگل پلی: یک اعتبارنامه برای سرور بازی خود ایجاد کنید. نوع اعتبارنامه برای کلاینت OAuth، «وب» خواهد بود.
  2. در برنامه اندروید: به عنوان بخشی از ورود به سیستم، یک کد احراز هویت سرور برای اعتبارنامه سرور خود درخواست کنید و آن را به سرور خود ارسال کنید.
  3. روی سرور بازی خود: کد احراز هویت سرور را با استفاده از سرویس‌های احراز هویت گوگل با یک توکن دسترسی OAuth جایگزین کنید و سپس از آن برای فراخوانی APIهای REST سرویس‌های Play Games استفاده کنید.

قبل از اینکه شروع کنی

قبل از اینکه بتوانید ورود به سیستم گوگل را در بازی خود ادغام کنید، ابتدا باید بازی خود را در کنسول گوگل پلی اضافه کنید، همانطور که در بخش «راه‌اندازی سرویس‌های بازی‌های گوگل پلی» توضیح داده شده است.

یک برنامه وب سمت سرور مرتبط برای بازی خود ایجاد کنید

سرویس‌های بازی گوگل پلی پشتیبانی بک‌اند برای بازی‌های وب ارائه نمی‌دهد. با این حال، پشتیبانی بک‌اند سرور را برای سرور بازی اندروید شما فراهم می‌کند.

اگر می‌خواهید از APIهای REST برای سرویس‌های بازی‌های گوگل پلی در برنامه سمت سرور خود استفاده کنید، این مراحل را دنبال کنید:

  1. یک برنامه وب مرتبط برای بازی خود در بخش برنامه‌های مرتبط در کنسول گوگل پلی ایجاد کنید. توجه داشته باشید که launch_url برای این جریان استفاده نمی‌شود و می‌تواند خالی بماند.
  2. برای دریافت اطلاعات اعتبارنامه برای برنامه خود، این مراحل را دنبال کنید:
    1. از بازی خود در کنسول گوگل پلی، روی جزئیات بازی کلیک کنید.
    2. به بخش پروژه کنسول API بروید و روی پیوند پروژه کنسول API کلیک کنید.
    3. از صفحه APIها و خدمات > اعتبارنامه‌ها در کنسول API گوگل، فایل client_secret.json را برای برنامه وب خود دانلود کنید و آن را در مکانی که سرور شما بتواند به آن دسترسی داشته باشد ذخیره کنید. شناسه کلاینت اعتبارنامه را برای مراجعه بعدی ثبت کنید.
  3. برنامه سمت سرور خود را مجدداً راه‌اندازی کنید تا آماده پذیرش درخواست‌ها از برنامه کلاینت بازی شما باشد.

انجام ورود به سیستم روی کلاینت

کلاس GoogleSignInClient نقطه ورودی اصلی برای بازیابی حساب کاربری بازیکنی است که در حال حاضر وارد سیستم شده است، و اگر بازیکن قبلاً این کار را در برنامه شما در دستگاه انجام نداده باشد، آن را وارد سیستم می‌کند.

برای ایجاد یک کلاینت ورود به سیستم، مراحل زیر را دنبال کنید:

  1. یک کلاینت ورود به سیستم از طریق شیء GoogleSignInOptions ایجاد کنید. در GoogleSignInOptions.Builder برای پیکربندی ورود به سیستم، باید GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN را مشخص کنید.
  2. همچنین باید با فراخوانی متد GoogleSignInOptions.Builder.requestServerAuthCode() با پارامتر شناسه کلاینت سرور، مشخص کنید که بازی شما به یک کد احراز هویت برای سرور backend شما نیاز دارد. کد احراز هویت را بعداً برای توکن‌های دسترسی در سرور backend خود، همانطور که در بخش «دریافت کد احراز هویت سرور» توضیح داده شده است، بازیابی خواهید کرد.
  3. متد GoogleSignIn.getClient() را فراخوانی کنید و گزینه‌هایی را که قبلاً پیکربندی کرده‌اید، به آن ارسال کنید. اگر فراخوانی موفقیت‌آمیز باشد، Google Sign-In API یک نمونه از GoogleSignInClient را برمی‌گرداند.
  4. پس از دریافت نمونه GoogleSignInClient ، باید همانطور که در بخش «انجام ورود بی‌صدا » توضیح داده شده است، بازیکن را به صورت بی‌صدا از طریق onResume() مربوط به activity وارد سیستم کنید.

در اینجا یک مثال آورده شده است:

private static final int RC_SIGN_IN = 9001;
private GoogleSignInClient mGoogleSignInClient;

private void startSignInForAuthCode() {

  // Client ID for your backend server.
  String webClientId = getString(R.string.webclient_id);

  GoogleSignInOptions signInOption = new
      GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
      .requestServerAuthCode(webClientId)
      .build();

  GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOption);
  Intent intent = signInClient.getSignInIntent();
  startActivityForResult(intent, RC_SIGN_IN);
}

دریافت کد احراز هویت سرور

برای بازیابی کد احراز هویت سرور که بازی شما می‌تواند برای توکن‌های دسترسی در سرور backend شما استفاده کند، متد getServerAuthCode() را در شیء GoogleSignInAccount که Google Sign-In در صورت ورود موفقیت‌آمیز بازیکن برمی‌گرداند، فراخوانی کنید.

در اینجا یک مثال آورده شده است:

// Auth code to send to backend server.
private String mServerAuthCode;

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == RC_SIGN_IN) {
    GoogleSignInResult result = Auth.GoogleSignInApi.getSignInResultFromIntent(data);
    if (result.isSuccess()) {
      mServerAuthCode = result.getSignInAccount().getServerAuthCode();
    } else {
      String message = result.getStatus().getStatusMessage();
      if (message == null || message.isEmpty()) {
        message = getString(R.string.signin_other_error);
      }
      new AlertDialog.Builder(this).setMessage(message)
          .setNeutralButton(android.R.string.ok, null).show();
    }
  }
}

کد احراز هویت سرور را با یک توکن دسترسی روی سرور تعویض کنید

کد احراز هویت سرور را برای تبادل توکن‌های دسترسی و به‌روزرسانی به سرور بک‌اند خود ارسال کنید. از توکن دسترسی برای فراخوانی API خدمات بازی‌های گوگل پلی از طرف بازیکن استفاده کنید و در صورت تمایل، توکن به‌روزرسانی را برای دریافت یک توکن دسترسی جدید پس از انقضای توکن دسترسی ذخیره کنید.

قطعه کد زیر نشان می‌دهد که چگونه می‌توانید کد سمت سرور را در زبان برنامه‌نویسی جاوا پیاده‌سازی کنید تا کد احراز هویت سرور را با توکن‌های دسترسی مبادله کنید. این کد از برنامه نمونه clientserverskeleton استفاده می‌کند:

/**
 * Exchanges the authcode for an access token credential.  The credential
 * is the associated with the given player.
 *
 * @param authCode - the non-null authcode passed from the client.
 * @param player   - the player object which the given authcode is
 *                 associated with.
 * @return the HTTP response code indicating the outcome of the exchange.
 */
private int exchangeAuthCode(String authCode, Player player) {
try {

    // The client_secret.json file is downloaded from the Google API
    // console.  This is used to identify your web application.  The
    // contents of this file should not be shared.
    //
    File secretFile = new File("client_secret.json");

    // If we don't have the file, we can't access any APIs, so return
    // an error.
    if (!secretFile.exists()) {
        log("Secret file : " + secretFile
                .getAbsolutePath() + "  does not exist!");
        return HttpServletResponse.SC_FORBIDDEN;
    }

    GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(
            JacksonFactory.getDefaultInstance(), new
            FileReader(secretFile));

    // Extract the application id of the game from the client id.
    String applicationId = extractApplicationId(clientSecrets
            .getDetails().getClientId());

    GoogleTokenResponse tokenResponse =
            new GoogleAuthorizationCodeTokenRequest(
            HTTPTransport,
            JacksonFactory.getDefaultInstance(),
            "https://oauth2.googleapis.com/token",
            clientSecrets.getDetails().getClientId(),
            clientSecrets.getDetails().getClientSecret(),
            authCode,
            "")
            .execute();

    log("hasRefresh == " + (tokenResponse.getRefreshToken() != null));
    log("Exchanging authCode: " + authCode + " for token");
    Credential credential = new Credential
            .Builder(BearerToken.authorizationHeaderAccessMethod())
            .setJsonFactory(JacksonFactory.getDefaultInstance())
            .setTransport(HTTPTransport)
            .setTokenServerEncodedUrl("https://www.googleapis.com/oauth2/v4/token")
            .setClientAuthentication(new HttpExecuteInterceptor() {
                @Override
                public void intercept(HttpRequest request)
                        throws IOException {
                        }
            })
            .build()
            .setFromTokenResponse(tokenResponse);

    player.setCredential(credential);

    // Now that we have a credential, we can access the Games API.
    PlayGamesAPI api = new PlayGamesAPI(player, applicationId,
            HTTPTransport, JacksonFactory.getDefaultInstance());

    // Call the verify method, which checks that the access token has
    // access to the Games API, and that the player id used by the
    // client matches the playerId associated with the accessToken.
    boolean ok = api.verifyPlayer();

    // Call a Games API on the server.
    if (ok) {
        ok = api.updatePlayerInfo();
        if (ok) {
            // persist the player.
            savePlayer(api.getPlayer());
        }
    }

    return ok ? HttpServletResponse.SC_OK :
            HttpServletResponse.SC_INTERNAL_SERVER_ERROR;

  } catch (IOException e) {
    e.printStackTrace();
  }
  return HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
}

برای کسب اطلاعات بیشتر در مورد دسترسی به APIهای گوگل از طریق یک سرور پشتیبان از طرف یک بازیکن وارد شده، به فعال کردن دسترسی سمت سرور مراجعه کنید.

مدیریت خروج بازیکن

برای خروج بازیکنان از بازی، متد signOut() را در GoogleSignInClient فراخوانی کنید. برای مشاهده‌ی یک قطعه کد نمونه، به بخش خروج بازیکن مراجعه کنید.

فراخوانی APIهای REST از سرور

برای شرح کامل فراخوانی‌های API موجود، به APIهای REST برای سرویس‌های بازی‌های Google Play مراجعه کنید.

نمونه‌هایی از فراخوانی‌های REST API که ممکن است برای شما مفید باشند عبارتند از:

بازیکن

  • می‌خواهید شناسه و اطلاعات پروفایل بازیکنی که وارد سیستم شده است را دریافت کنید؟ با استفاده از شناسه 'me' با Players.get تماس بگیرید.

دوستان

حتماً راهنمای دوستان را که دوستان را با جزئیات بیشتری توضیح می‌دهد، مرور کنید.

  • می‌خواهید لیست دوستان بازیکن را بازیابی کنید؟ تابع Players.list را با 'friends_all' به عنوان collection فراخوانی کنید.
  • بررسی کنید که آیا به لیست دوستان دسترسی دارید؟ برای me Players.get را فراخوانی کنید و به فیلد profileSettings.friendsListVisibility در پاسخ نگاه کنید.

دستاوردها

حتماً راهنمای دستاوردها را که جزئیات بیشتری در مورد دستاوردها توضیح می‌دهد، مطالعه کنید.

  • می‌خواهید فهرستی از دستاوردهای فعلی خود داشته باشید؟ می‌توانید AchievementDefinitions.list را فراخوانی کنید.
  • این را با فراخوانی Achievements.list ترکیب کنید تا بفهمید کدام یک از موارد قفل شده توسط بازیکن فعال شده است.
  • آیا بازیکن دستاوردی کسب کرده است؟ برای باز کردن قفل آن از Achievements.unlock استفاده کنید!
  • آیا بازیکن به سمت یک دستاورد جزئی پیشرفت کرده است؟ از Achievements.increment برای گزارش پیشرفت استفاده کنید (و بفهمید که آیا بازیکن آن را قفل‌گشایی کرده است یا خیر).
  • آیا در حال اشکال‌زدایی بازی‌ای هستید که هنوز به مرحله‌ی تولید نرسیده است؟ برای بازگرداندن دستاوردها به حالت اولیه، می‌توانید از توابع Achievements.reset یا Achievements.resetAll در رابط‌های برنامه‌نویسی کاربردی مدیریت (Management APIs) استفاده کنید.

جدول امتیازات

حتماً راهنمای جدول امتیازات را که جزئیات بیشتری در مورد جدول امتیازات توضیح می‌دهد، مطالعه کنید.

  • می‌خواهید فهرستی از تمام تابلوهای امتیاز در بازی داشته باشید؟ با Leaderboards.list تماس بگیرید.
  • آیا بازیکن بازی را تمام کرده است؟ می‌توانید امتیاز او را در Scores.submit ثبت کنید و ببینید که آیا این امتیاز، امتیاز بالایی است یا خیر.
  • می‌خواهید جدول امتیازات را نمایش دهید؟ داده‌ها را از Scores.list دریافت کنید و آن را به کاربر نشان دهید.
  • از Scores.listWindow برای یافتن مجموعه‌ای از امتیازات نزدیک به بالاترین امتیاز کاربر استفاده کنید.
  • برای دریافت اطلاعات بیشتر در مورد امتیاز بازیکن در یک جدول امتیازات خاص (برای مثال، اگر بازیکن جزو ۱۲٪ برتر از کل بازیکنان باشد)، با Scores.get تماس بگیرید.
  • آیا در حال اشکال‌زدایی یک بازی هستید؟ سعی کنید Scores.reset را از APIهای مدیریتی فراخوانی کنید تا تمام امتیازات آن بازیکن از یک جدول امتیازات خاص، مجدداً تنظیم شود.