با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
Recall API به بازی‌ها اجازه می‌دهد پیوندهای بین کاربران خدمات بازی‌های Google Play (PGS) و حساب‌های درون بازی آنها را با ذخیره کردن نشانه‌های فراخوان در سرورهای Google مدیریت کنند. در اینجا یک سناریوی نمونه از نحوه استفاده از Recall API آمده است.
یک کاربر در حال انجام بازی است که در آن توسعه دهنده یک سیستم هویت برای ردیابی پیشرفت کاربر دارد و از PGS به موازات سایر روش های احراز هویت برای ورود کاربران به بازی خود استفاده می کند. در این مثال، یک کاربر به حساب PGS خود Laura وارد شده و یک حساب کاربری درون بازی با سیستم هویت توسعه دهنده به نام Racer94 ایجاد می کند. همانطور که کاربر بازی را انجام می دهد، سرور بازی توسعه دهنده پیشرفت آنها را همگام می کند.
به‌طور جداگانه، توسعه‌دهنده یک توکن فراخوان را با Google ذخیره می‌کند که با حساب کاربری درون بازی کاربر مطابقت دارد. گوگل به طور خودکار توکن های فراخوان را در نمایه PGS کاربر ذخیره می کند.
اکنون کاربر تصمیم می گیرد برای اولین بار بازی را روی GPG روی رایانه شخصی بازی کند. کاربر به طور خودکار با حساب PGS خود وارد می شود و مشتری بازی بررسی می کند که آیا پیشرفتی برای این کاربر PGS وجود دارد یا خیر. سپس سرور بازی از گوگل پرس و جو می کند تا ببیند آیا نشانه هایی برای این حساب PGS وجود دارد یا خیر. از آنجایی که وجود دارد، گوگل توکن فراخوان را پس می‌فرستد و سرور بازی از آن رمز برای یافتن حساب مرتبط کاربر Racer94 و بازیابی پیشرفت آنها استفاده می‌کند. از آنجایی که ورود به سیستم با PGS یک تجربه بدون اصطکاک است، پیشرفت کاربر توسط برنامه بدون نیاز به وارد کردن نام کاربری یا رمز عبور بازیابی می‌شود. علاوه بر این، توسعه‌دهنده می‌تواند از ورود به سیستم PGS با سیستم هویت موجود خود استفاده کند و برای ذخیره پیوند بین پیشرفت بازیکن و حساب PGS خود به Google تکیه کند.
همانطور که در مثال قبلی مشاهده شد، دو عمل اصلی وجود دارد که توسط Recall API انجام می شود:
هنگامی که کاربر با یکی از حساب‌های درون بازی وارد می‌شود، رمز را با Google ذخیره می‌کند .
بازیابی رمز برای یک کاربر به منظور بازیابی حساب های درون بازی خود.
علاوه بر نشانه‌های فراخوان، Recall API همچنین به یک شناسه پایدار مطابق با حساب درون بازی، معروف به persona نیاز دارد تا محدودیت‌های اصلی را اعمال کند. شما ممکن است شخصیت را به عنوان برچسبی در نظر بگیرید که حساب کاربری در بازی کاربر را در سیستم هویت توسعه دهنده نشان می دهد و نشانه فراخوانی را به عنوان کلیدی که برای بازگرداندن حساب کاربری در بازی به بازی استفاده می شود. مقادیر پرسونا و نشانه نباید در پروژه های مختلف PGS دوباره استفاده شوند. همچنین، در حالی که نشانه‌های فراخوان ممکن است در طول زمان تغییر کنند، یک پرسونا باید مطابق با حساب کاربری کاربر در بازی پایدار باشد.
قواعد کاردینالیته
Recall API یک رابطه 1:1 را بین نمایه‌های PGS و حساب‌های درون بازی اعمال می‌کند (که به آنها قوانین اصلی گفته می‌شود)، که در آن یک پرسونا فقط می‌تواند به یک نمایه PGS مرتبط شود و یک نمایه PGS فقط می‌تواند به یک شخصیت مرتبط شود. پرسونا به عنوان یک شناسه پایدار برای یک حساب درون بازی استفاده می شود، زیرا نشانه های فراخوان ممکن است در طول زمان تغییر کنند.
پرسونای پیوند شده به نمایه PGS نیز ممکن است در طول زمان تغییر کند (زیرا حساب‌های مختلف درون بازی به نمایه PGS مرتبط می‌شوند).
جریان های فنی برای ذخیره و بازیابی نشانه های فراخوان
این بخش جریان فنی بین کلاینت بازی و سرورها با سرورهای Google را هنگام ذخیره و بازیابی نشانه‌های فراخوان پوشش می‌دهد.
مرحله 1: به کاربر PGS وارد شوید و شناسه جلسه را بازیابی کنید
بازی PGS SDK را مقداردهی اولیه می کند و سعی می کند کاربر را با PGS وارد کند.
با فرض اینکه کاربر وارد سیستم شده است، یک شناسه جلسه از Games SDK در کلاینت بازی درخواست کنید و یک توکن OAuth 2.0 را از باطن OAuth Google درخواست کنید. شناسه جلسه و نشانه‌های OAuth 2.0 برای برقراری ارتباط با Google Games استفاده می‌شوند.
مرحله 3a: اگر نشانه وجود دارد، پیشرفت را بازیابی کنید
اگر نشانه ای وجود دارد، رمز را بازیابی و رمزگشایی کنید و داده های کاربر را بازیابی کنید.
مرحله 3b: اگر نشانه ای وجود ندارد، یک توکن ذخیره کنید
از آنجایی که هیچ نشانه ای وجود ندارد، هیچ پیشرفتی بازیابی نمی شود. کاربر وارد سیستم هویت توسعه‌دهنده می‌شود یا در صورت عدم وجود یک حساب کاربری جدید ایجاد می‌کند. توجه - این ورود به سیستم با PGS نیست (که قبلا انجام شده است)، بلکه با سیستم هویت توسعه دهنده خارج از PGS است.
یک رمز فراخوان رمزگذاری شده ایجاد کنید که حساب کاربری درون بازی کاربر را رمزگذاری می‌کند و آن را به همراه شناسه جلسه و نشانه OAuth 2.0 به Google ارسال کنید. در این مرحله، گوگل ارتباطی بین توکن فراخوان ارسال شده و حساب PGS بازیکن ایجاد می کند.
برای کاربران بدون نمایه PGS جریان دارد
می‌توانید با استفاده از حالت بدون پروفایل، نشانه‌های فراخوان را برای کاربری ذخیره کنید که هنوز نمایه PGS ایجاد نکرده است. با این حال، دو اخطار مهم وجود دارد:
شما نمی توانید نشانه های کاربری را که نمایه PGS ندارد بازیابی کنید. هنگامی که کاربر سعی می کند با سرویس بازی های Play در دستگاه دوم وارد بازی شما شود، ایجاد نمایه به طور خودکار از شما خواسته می شود.
شما باید دستورالعمل‌های اضافی را دنبال کنید تا اطمینان حاصل کنید که اخطار مناسبی در توصیف موارد زیر و کسب رضایت کاربر نهایی مناسب دارید:
اشتراک‌گذاری داده‌ها با Google برای فعال کردن ویژگی پیوند دادن حساب بازی‌های Play.
در دسترس بودن تنظیماتی برای مدیریت این اشتراک‌گذاری، مانند تنظیمات بازی‌های Play.
کاربر بدون نمایه PGS بازی‌ای را باز می‌کند که فراخوانی بدون پروفایل را فعال کرده است.
Games SDK یک ورود خودکار را راه‌اندازی می‌کند، که به دلیل نداشتن نمایه PGS انجام نمی‌شود.
Games SDK نواری اسنک را نشان می‌دهد که به کاربر اطلاع می‌دهد که بازی با Google ادغام شده است. این نوار اسنک قابل اجرا است - کاربر می تواند تا زمانی که یک نمایه ایجاد شود، فراخوانی را غیرفعال کند.
بازی درخواست دسترسی به یاد آوری می کند. توجه داشته باشید که PGS زمانی که نمایه‌های PGS در دستگاه وجود دارد یا زمانی که حساب Google در دستگاه وجود ندارد، درخواست‌های دسترسی به فراخوان را رد می‌کند. در این صورت، بازی باید بدون استفاده از PGS ادامه یابد.
پس از اینکه کاربر با یک حساب درون بازی وارد شد، بازی یک جفت توکن و پرسونا برای کاربر ایجاد می کند که با حساب درون بازی او مطابقت دارد. بازی این جفت را با گوگل ذخیره می کند. اگر کاربر به حساب‌های دیگر داخل بازی وارد شود، ممکن است بازی بعداً توکن‌های بیشتری ذخیره کند.
یک بازی را در یک دستگاه جدید راه اندازی کنید
کاربر بدون نمایه PGS بازی‌ای را باز می‌کند که فراخوانی بدون پروفایل در دستگاهی فعال است.
بازی یک نشانه فراخوانی بدون پروفایل را ثبت می‌کند، همانطور که در Store a token و جفت پرسونا توضیح داده شده است.
کاربر همان بازی را در دستگاه دیگری که تنظیمات حساب یکسانی دارد باز می کند.
Games SDK باعث ایجاد نمایه می شود. کاربر می تواند توکن های فراخوانی که قبلاً ذخیره شده است را بررسی و رد کند. کاربر در این زمان یک نمایه PGS ایجاد می کند.
ورود خودکار به PGS تکمیل می شود و بازی وضعیت احراز هویت را دریافت می کند.
بازی طبق معمول نشانه های فراخوانی را برای کاربر بازیابی می کند.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Recall API\n\nThe Recall API lets games manage links between Google Play Games Services (PGS) users and\ntheir in-game accounts by storing *recall tokens* with Google servers. Here's a\nsample scenario of how the Recall API might be used.\n\n1. A user is playing a game where the developer has an identity system to track\n user progress, and uses PGS in parallel with other authentication methods to\n log users into their game. In this example, a user is logged into their PGS\n account *Laura* , and creates an in-game account with the developer's\n identity system called *Racer94*. As the user plays the game, the\n developer's game server syncs their progress.\n\n2. Separately, the developer saves a recall token with Google, which\n corresponds with the user's in-game account. Google automatically stores\n that recall token against the user's PGS profile.\n\n3. The user now decides to play the game on [GPG on\n PC](/games/playgames/overview) for the first time. The user is automatically\n signed in with their PGS account, and the game client checks to see if there\n is any progress available for this PGS user. The game server then queries\n Google to see if there are any tokens for this PGS account. Since there are,\n Google sends back the recall token, and the game server uses that token to\n find the user's associated account Racer94, and restore their progress.\n Since signing in with PGS is a frictionless experience, the user's progress\n is restored by the app without the user needing to enter a username or\n password. Furthermore, the developer can use PGS sign-in with their existing\n identity system, and rely on Google to store the link between player\n progress and their PGS account.\n\nAs seen in the example earlier, there are two main actions which are performed\nby the Recall API:\n\n- **Storing** the token with Google when a user logs in with one of the in-game\n accounts.\n\n- **Retrieving** the token for a user in order to restore their in-game\n accounts.\n\nIn addition to recall tokens, the Recall API also requires a stable identifier\ncorresponding to the in-game account, known as *persona* , to enforce\n[cardinality constraints](#enforcing-cardinality). You might think of a persona\nas the label which represents the user's in-game account within the developer's\nidentity system, and the recall token as a key which is used to restore the\nuser's in-game account to the game. Persona and token values must not be reused\nacross different\n[PGS projects](/games/pgs/console/setup#add_your_game_to_the).\nAlso, while recall tokens may be changed over time, a persona should be stable\naccording to the user's in-game account.\n| **Note:** Strings used for recall tokens and personas must be opaque and not contain any sensitive or personally-identifiable information (including but not limited to name, email address, and demographics). Games must use robust encryption algorithms for generating recall tokens.\n\nCardinality rules\n-----------------\n\nThe Recall API enforces a 1:1 relationship between PGS profiles and in-game\naccounts (referred to as *cardinality rules*), where one persona can only be\nlinked to one PGS profile, and one PGS profile can only be linked to one\npersona. The persona is used as a stable identifier for an in-game account,\nsince recall tokens may change over time.\n\nThe persona linked to a PGS profile may also be changed over time (as different\nin-game accounts are linked to the PGS profile).\n\nTechnical flows for storing and retrieving the recall tokens\n------------------------------------------------------------\n\nThis section covers the technical flow between the game client and servers with\nGoogle servers when storing and retrieving recall tokens.\n\n### Step 1: Sign in the PGS User and retrieve the session ID\n\nThe game initializes the PGS SDK and attempts to sign the user in with PGS.\n\nAssuming the user is signed in, request a session ID from the Games SDK on the\ngame client, and request an OAuth 2.0 token from Google's OAuth backend. The\nsession ID and OAuth 2.0 tokens are used to communicate with the Google Games\nbackend.\n\n### Step 2: Retrieve any available recall token\n\nRequest for any associated recall token with the PGS user's account. If a token\nis present, [proceed to Step 3a and restore progress](#restore-progress).\nOtherwise, if this is a new user and they have no token present, [proceed to\nStep 3b and store a new token](#store-tokens).\n\n### Step 3a: If token is present, restore progress\n\nIf a token is present, retrieve and decrypt the token, and restore user data.\n\n### Step 3b: If no token is present, store a token\n\nSince no token is present, no progress is restored. The user proceeds to sign in\nwith the developer's identity system, or creates a new account if one does not\nexist. Note - this isn't signing in with PGS (which has been done already), but\nwith a developer's identity system outside of PGS.\n\nCreate an encrypted recall token which encodes the user's in-game account, and\nsend it to Google along with the session ID and OAuth 2.0 token. At this point,\nGoogle creates an association between the recall token which was sent, and the\nplayer's PGS account.\n\nFlows for users without a PGS profile\n-------------------------------------\n\nYou can store recall tokens for a user who hasn't created a PGS profile yet by\nusing profileless mode. However, there are two important caveats:\n\n- You can't retrieve tokens for a user who doesn't have a PGS profile. Profile creation is automatically prompted when the user tries to log into your game with Play Games Services on a second device.\n- You must follow [additional guidelines](/games/pgs/recall/recall-setup#terms) to ensure you have an appropriate notice describing the following items and obtaining the appropriate end-user consent:\n - Your sharing of the data with Google to enable the Play Games account linking feature.\n - The availability of settings to manage this sharing, such as Play Games settings.\n - The processing of such data under the [Google Privacy\n Policy](https://policies.google.com/privacy).\n\n### Store a token and persona pair\n\n1. A user without a PGS profile opens a game that has profileless recall enabled.\n2. The Games SDK triggers an automatic sign-in, which fails because the user has no PGS profile.\n3. The Games SDK shows a snackbar that informs the user that the game has integration with Google. This snackbar is actionable---the user can disable recall until a profile is created.\n4. The game requests recall access. Note that PGS rejects recall access requests when there are PGS profiles on the device or when there are no Google Accounts on the device. In that case, the game should proceed without using PGS.\n5. After the user logs in with an in-game account, the game creates a token and persona pair for the user that corresponds to their in-game account. The game stores this pair with Google. The game might store more tokens later if the user logs into other in-game accounts.\n\n### Launch a game on a new device\n\n1. A user without a PGS profile opens a game that has profileless recall enabled on a device.\n2. The game records a profileless recall token as described in [Store a token\n and persona pair](#profileless-store).\n3. The user opens the same game on a different device that has the same account setup.\n4. The Games SDK triggers profile creation. The user can review and reject previously stored recall tokens. The user creates a PGS profile at this time.\n5. The automatic sign-in into PGS completes, and the game receives the authenticated status.\n6. The game retrieves recall tokens for the user as usual.\n\nNext steps\n----------\n\nIn order to integrate the Recall API with your client and game server, [follow\nthis guidance](/games/pgs/recall/recall-setup)."]]
