این سند نحوه ادغام دستاوردها را با استفاده از کنسول Google Play یا تماس‌های API توضیح می‌دهد. عناصر و حالات اساسی دستاوردها را پوشش می دهد و نحوه ایجاد، وارد کردن و مدیریت آنها را توضیح می دهد.
قبل از شروع
دستورالعمل های دستاوردهای طراحی با کیفیت بالا را مرور کنید.
اصطلاحات در مبانی دستاوردها را مرور کنید.
دستاوردهای جدید ایجاد یا وارد کنید
برای پیاده سازی دستاوردها از ابتدا، مراحل زیر را دنبال کنید:
افزودن دستاوردها
دو راه برای ایجاد دستاوردها برای اولین بار با استفاده از کنسول Google Play وجود دارد:
- ایجاد یک دستاورد : تعاریف و ابرداده را برای هر دستاورد یکی یکی اضافه کنید.
- دستاوردهای وارد کردن : تعاریف و سایر ابرداده‌ها را برای چندین دستاورد با هم در یک مرحله وارد کنید.
یک دستاورد ایجاد کنید
برای ایجاد یک دستاورد برای یک بازی جدید و منتشر نشده، این مراحل را کامل کنید:
- In the Google Play Console , select a game.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، ایجاد دستاورد را انتخاب کنید.
- In the Add achievements page, complete the form.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- پس از ایجاد یک دستاورد، باید دستاوردهای خود را منتشر کنید .
دستاوردهای وارداتی
برای افزودن چندین دستاورد به طور همزمان به بازی خود، از مراحل زیر استفاده کنید:
- یک فایل فشرده حاوی دستاوردهای خود بسازید.
- فایل را آپلود کنید.
برای اطلاعات بیشتر در مورد فایل فشرده، دستورالعمل های فایل فشرده را ببینید.
برای وارد کردن دستاوردها:
- In the Google Play Console , select a game.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، وارد کردن دستاوردها را انتخاب کنید.
- In the Import achievements page, click Upload .
- فایل فشرده را برای آپلود انتخاب کنید.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- پس از وارد کردن دستاوردها، باید بازی خود را منتشر کنید .
دستورالعمل های فایل فشرده
شما می توانید چندین دستاورد را به طور همزمان با استفاده از یک فایل فشرده وارد کنید. برای استفاده از نام فایل های فشرده در فایل فشرده خود به جدول مراجعه کنید:
| نام فایل | الزامی یا اختیاری | ارزش های پذیرفته شده |
|---|---|---|
AchievementsMetadata.csv | مورد نیاز | فراداده برای هر دستاورد به صفات مراجعه کنید. |
AchievementsLocalizations.csv | اختیاری | ترجمه هایی را برای نام ها و توضیحات دستاوردها ارائه می دهد. |
AchievementsIconMappings.csv | اختیاری | دستاوردها را به فایل‌های نماد خود نقشه‌برداری می‌کند. |
| فایل های آیکون | اختیاری | نمادها با فرمت PNG، JPEG یا JPG. |
الزامات فایل فشرده:
- هیچ زیر شاخه ای وجود ندارد.
- نام فایل های منحصر به فرد
- Only CSV, PNG, JPEG, or JPG files.
- فایل‌های CSV نباید ردیف سرصفحه داشته باشند.
- هر فایل باید کمتر از 1 مگابایت باشد.
- فایل فشرده نباید بیش از 203 فایل داشته باشد.
- Total zip file size must be under 200MB.
AchievementsMetadata.csv format
فایل AchievementsMetadata.csv حاوی ابرداده برای هر دستاورد است. باید اطلاعات را به صورت مقادیر جدا شده با کاما به ترتیب زیر شامل شود:
Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order
این فیلدها در جدول زیر توضیح داده شده است:
| سرصفحه های ستون CSV | الزامی یا اختیاری | ارزش های پذیرفته شده |
|---|---|---|
| نام | مورد نیاز | حداکثر 100 کاراکتر |
| توضیحات | اختیاری | حداکثر 500 کاراکتر |
| ارزش افزایشی | اختیاری | True یا False |
| مراحل مورد نیاز | اگر Incremental Value True. | Number (no fractions or decimals). حداکثر مقدار 10000 است. |
| حالت اولیه | مورد نیاز | Hidden یا Revealed |
| امتیاز | مورد نیاز | عددی که مضربی از 5 است و مقدار آن باید بین 5 تا 200 باشد |
| ترتیب فهرست | اختیاری | عدد (بدون کسری یا اعشاری و بزرگتر از صفر) |
AchievementsMetadata.csv file requirements:
- Each row must have seven values. If you want to omit a value, leave it blank.
- از فیلدهای
NameوDescriptionبه عنوان محلی پیش فرض استفاده می شود. - فیلد
Nameباید در همه دستاوردها منحصر به فرد باشد. - فیلدهای زیر نباید حاوی کاما باشند:
NameوDescription.
A sample AchievementsMetadata.csv file:
Achievement1,Achievement One,True,100,Hidden,5,20 Achievement2,Achievement Two,False,,Revealed,10,30
AchievementsLocalizations.csv format
فایل AchievementsLocalizations.csv یک فایل اختیاری است که تمام داده‌های مورد نیاز برای توصیف هر دستاورد را برای کاربران در مناطق مختلف تنظیم می‌کند. دستاوردها در تراز با مناطق مشخص شده برای بازی ترجمه می شوند.
باید اطلاعات را به صورت مقادیر جدا شده با کاما به ترتیب زیر شامل شود:
Name, Localized name, Localized description, locale
این فیلدها در جدول زیر توضیح داده شده است:
| سرصفحه های ستون CSV | الزامی یا اختیاری | توضیحات | ارزش های پذیرفته شده |
|---|---|---|---|
| نام | مورد نیاز | باید با ستون Name از AchievementsMetadata.csv مطابقت داشته باشد. | حداکثر 100 کاراکتر |
| نام محلی | مورد نیاز | نام محلی برای دستاورد. | حداکثر 100 کاراکتر |
| توضیحات محلی | اختیاری | شرح بومی سازی شده برای دستاورد در منطقه مشخص شده. | حداکثر 500 کاراکتر |
| محلی | مورد نیاز | کد محلی مانند en-US . | قبل از تعیین یک منطقه ، ترجمه هایی را برای بازی خود اضافه کنید . Note that you cannot specify the default locale. کدهای محلی پشتیبانی شده را می توان در لیست زبان های پشتیبانی شده پیدا کرد. |
AchievementsLocalizations.csv file requirements:
- نام دستاوردها در یک بازی باید در هر منطقه منحصر به فرد باشد.
به عنوان مثال، اگر یک بازی از هر دو زبان en-US و fr-FR پشتیبانی می کند، دستاوردی به نام "Achievement1" برای en-US نیز می تواند "Achievement1" برای fr-FR نامیده شود.
- هر ردیف باید چهار مقدار داشته باشد. اگر می خواهید مقدار Localized description را حذف کنید، آن را خالی بگذارید.
نمونه فایل AchievementsLocalizations.csv :
Achievement1,Achievement One,This is the description of achievement one in English.,en-US Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR Achievement2,Achievement Two,Description of achievement two.,en-US Achievement2,Logro Dos,Descripción del logro dos.,es-ES Achievement3,Achievement Three,,en-US Achievement3,Erfolg Drei,,de-DE
AchievementsIconMappings.csv format
فایل AchievementsIconMappings.csv یک فایل اختیاری است که برای نقشه برداری از دستاوردهای شما با نماد داده شده استفاده می شود. باید اطلاعات را به صورت مقادیر جدا شده با کاما به ترتیب زیر شامل شود:
Name, icon filename
این فیلدها در جدول زیر توضیح داده شده است
| سرصفحه های ستون CSV | الزامی یا اختیاری | توضیحات |
|---|---|---|
| نام | مورد نیاز | باید با ستون Name از AchievementsMetadata.csv مطابقت داشته باشد. |
| نام فایل آیکون | مورد نیاز | نام فایل آیکون شما. |
AchievementsIconMappings.csv file requirements:
- هر ردیف باید دو مقدار داشته باشد.
- Icons files can only be in PNG or JPEG formats.
نمونه فایل AchievementsIconMappings.csv :
Valid Achievement,valid-achievement-icon.png Incremental Achievement,incremental-achievement-icon.jpeg No Description,no-description-icon.png Hidden Initial State,hidden-initial-state-icon.png Large Point Value,large-point-value-icon.jpeg
دستورالعمل های آیکون
نمادها باید به صورت فایل‌های PNG، JPEG یا JPG با ابعاد ۵۱۲×۵۱۲ ایجاد شوند. شما فقط باید نماد دستاورد باز شده را در اختیار ما قرار دهید. ما یک نسخه خاکستری برای نماد آشکار شده به طور خودکار تولید می کنیم. به همین دلیل، توصیه می‌کنیم نمادهای دستاورد شما شامل عناصر رنگارنگ باشد، بنابراین کاربران شما می‌توانند بین دستاوردهای آشکار و قفل نشده تمایز قفل کنند.
هنگامی که یک نماد دستاورد در یک Android [toast][a] نمایش داده می شود، نماد با یک دایره پوشانده می شود و گوشه های بیرونی آن پنهان می شود. مطمئن شوید که نماد شما همچنان در این شرایط خوب به نظر می رسد.
نماد یکسان در همه زبان‌ها استفاده می‌شود، بنابراین توصیه می‌کنیم از گنجاندن متن یا محتوای بومی‌سازی شده در یک نماد خودداری کنید.
فایل های آیکون
نمادهایی که در فایل AchievementsIconMappings.csv به آنها ارجاع می دهید باید در آرشیو zip فعلی که وارد می کنید وجود داشته باشد.
بازی ها را با دستاوردهای موجود به روز کنید
می‌توانید دستاوردهای بیشتری را به یک بازی اضافه کنید و دستاوردهای موجود را در کنسول Google Play به‌روزرسانی کنید.
دستاوردهای بیشتری اضافه کنید
اگر از قبل دستاوردهای موجود دارید و می خواهید موارد بیشتری اضافه کنید:
- در کنسول Google Play ، یک بازی را انتخاب کنید.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، افزودن دستاوردها را انتخاب کنید.
ویرایش دستاوردها
اگر از قبل دستاوردهای موجود دارید و می خواهید ویرایش کنید:
- در کنسول Google Play ، یک بازی را انتخاب کنید.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، یک دستاورد را انتخاب کنید.
- شما می توانید هر یک از فیلدها را ویرایش کنید.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- در صفحه خدمات بازی‌های Play - دستاوردها ، دستاورد ویرایش‌شده در وضعیت «در دسترس آزمایش‌کنندگان» قرار دارد.
- پس از آزمایش دستاورد، روی مرور و انتشار کلیک کنید.
این بازی شما را به همراه تمام دستاوردهای به روز شده شما بازنشر می کند.
حذف یک دستاورد
هنگامی که دستاورد شما منتشر شد، نمی توان آن را حذف کرد. فقط می‌توانید یک دستاورد را در حالت از پیش منتشر شده حذف کنید
- In the Play Games Services - Achievements page, select an achievement.
- برای حذف دستاورد، روی حذف دستاورد کلیک کنید.
یک دستاورد را بازنشانی کنید
فقط می‌توانید داده‌های پیشرفت بازیکن را برای دستاوردهای پیش‌نویس خود بازنشانی کنید.
- در صفحه خدمات بازی های Play - دستاوردها ، یک دستاورد را انتخاب کنید.
- برای بازنشانی دستاوردها، روی بازنشانی پیشرفت کلیک کنید.
- To reset achievement data programmatically, call the Management API
Achievementsmethods .
ترجمه برای دستاوردها اضافه کنید
شما می توانید ترجمه های خود را برای دستاوردهایی که با بازی شما مرتبط هستند مشخص کنید. قبل از انجام این کار، ابتدا مطمئن شوید که مراحل توضیح داده شده در افزودن ترجمه برای بازی خود را کامل کرده اید.
دو روش برای اضافه کردن ترجمه برای بازی خود وجود دارد:
می توانید از گزینه واردات دستاوردها برای آپلود ترجمه برای بسیاری از دستاوردهای جدید به طور همزمان استفاده کنید. You cannot use this option to upload translations for already existing achievements.
You can add translations for each achievement in your game. To add your own translation for each achievement:
- در کنسول Google Play، تب Achievements را برای بازی خود باز کنید، سپس یک دستاورد موجود را انتخاب کنید.
- In the achievements details page, select the tab for a language that you previously added in the Game details tab.
- در صفحه جزئیات دستاورد برای آن زبان، فرم را با ترجمه های خود برای آن دستاورد ویرایش کنید.
- Click Save to store your translated achievement details.
پیاده سازی های مشتری
برای یادگیری نحوه پیاده سازی دستاوردها برای پلتفرم خود، به منابع زیر مراجعه کنید:
آزمایش دستاوردها
برای تأیید اینکه دستاوردها همانطور که در نظر گرفته شده کار می کنند، مراحل آزمایش آنها را دنبال کنید:
- Set up an internal test track .
- Add test accounts to your game project for testers.
- نمایه خدمات بازی‌های Play را برای یکی از حساب‌های آزمایشی با استفاده از برنامه بازی‌های Play ایجاد کنید.
- Open the game using the same test account for which you created the Play Games Services profile.
- Verify that Play Games Services "Welcome toast" is shown on the screen as a confirmation of successful automatic authentication on game launch.
- بازی را انجام دهید و مراحل لازم را برای باز کردن قفل دستاوردها انجام دهید.
برای تأیید دستاوردها:
Verify that "achievement unlocked" popup is shown on the screen when the achievement is completed.
برنامه Play Store را باز کنید و بررسی کنید که بخش دستاوردها در YouTab دستاوردهای تکمیل شده و همچنین دستاوردهای در حال پیشرفت (با جزئیات پیشرفت) را نشان می دهد.
عملکرد دستاوردها را در Play Console دنبال کنید
در اینجا نحوه یافتن آمار سریع برای دستاوردهای فردی آورده شده است:
- در کنسول Google Play .
- Go to Settings> Game projects .
- یک بازی را انتخاب کنید.
- On the left-hand menu, click Achievements .
- در صفحه دستاوردها ، می‌توانید آماری را بیابید تا بفهمید که آیا بازیکنانتان قفل دستاوردها را باز می‌کنند یا خیر. For those whose achievements are not hidden, you can see what percentage are unlocking them. برای دستاوردهای مرحله اولیه، درصد باز کردن قفل معمولاً نزدیک به 100٪ است.
You can also track time series performance of achievements in the Grow > Play Games Services > Game statistics page.
دستاوردها را منتشر کنید
پس از اتمام تست، باید بازی خود را منتشر کنید. All of your game's achievements are published with it. انتشار دستاوردها یک مرحله ضروری برای عملکرد مناسب دستاوردها است.
To publish, follow these steps:
- In the Google Play Console , select a game.
- در صفحه خدمات بازی‌های Play - دستاوردها ( رشد > خدمات بازی‌های Play > راه‌اندازی و مدیریت > دستاوردها )، روی بازبینی و انتشار کلیک کنید.
- در صفحه خدمات بازی‌های Play - انتشار ( رشد > خدمات بازی‌های Play > راه‌اندازی و مدیریت > انتشار )، اقدامات را مرور کرده و مشکلات را برطرف کنید.
- روی انتشار کلیک کنید.
All of your game's achievements are published.
اشتباهات رایجی که باید از آنها اجتناب کرد
These points highlight common mistakes to avoid when implementing achievements in a game. They emphasize the importance of:
In the Play Console, go to Grow > Play Games Services > Setup and management > Achievements .
- Before publishing, verify that achievements configured in the Play Console are not in "Draft" state.
- مقادیر شناسه دستاورد را از Play Console به کد بازی اضافه نکنید. Use the client implementations instead.
مطمئن شوید که منطق باز کردن قفل را روی کلاینت خود نیز پیاده سازی کرده اید.
- بازیکنان نمی توانند از مرحله ماشه ای که در آن API باز کردن قفل فراخوانی می شود، بگذرند. به عنوان مثال، تکمیل آموزش یک دستاورد است، اما بازیکنان می توانند خود آموزش را نادیده بگیرند.
This document explains how to integrate achievements into your game using the Google Play Console or API calls. It covers the essential elements and states of achievements, and describes how to create, import, and manage them.
قبل از شروع
دستورالعمل های دستاوردهای طراحی با کیفیت بالا را مرور کنید.
Review the terminology in achievements basics .
Create or import new achievements
برای پیاده سازی دستاوردها از ابتدا، مراحل زیر را دنبال کنید:
افزودن دستاوردها
There are two ways to create achievements for the first time using the Google Play Console:
- Create an achievement : Add definitions and metadata for each achievement one at a time.
- Import achievements : Import definitions and other metadata for multiple achievements together in a single step.
یک دستاورد ایجاد کنید
برای ایجاد یک دستاورد برای یک بازی جدید و منتشر نشده، این مراحل را کامل کنید:
- In the Google Play Console , select a game.
- In the Play Games Services - Achievements page ( Grow > Play Games Services > Setup and management > Achievements ), select Create achievement .
- In the Add achievements page, complete the form.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- After you have created an achievement, you need to publish your achievements .
دستاوردهای وارداتی
برای افزودن چندین دستاورد به طور همزمان به بازی خود، از مراحل زیر استفاده کنید:
- یک فایل فشرده حاوی دستاوردهای خود بسازید.
- فایل را آپلود کنید.
برای اطلاعات بیشتر در مورد فایل فشرده، دستورالعمل های فایل فشرده را ببینید.
برای وارد کردن دستاوردها:
- In the Google Play Console , select a game.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، وارد کردن دستاوردها را انتخاب کنید.
- در صفحه واردات دستاوردها ، روی آپلود کلیک کنید.
- فایل فشرده را برای آپلود انتخاب کنید.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- After you have imported achievements, you need to publish your game .
دستورالعمل های فایل فشرده
You can import multiple achievements at once using a zip file. برای استفاده از نام فایل های فشرده در فایل فشرده خود به جدول مراجعه کنید:
| نام فایل | الزامی یا اختیاری | ارزش های پذیرفته شده |
|---|---|---|
AchievementsMetadata.csv | مورد نیاز | فراداده برای هر دستاورد به صفات مراجعه کنید. |
AchievementsLocalizations.csv | اختیاری | ترجمه هایی را برای نام ها و توضیحات دستاوردها ارائه می دهد. |
AchievementsIconMappings.csv | اختیاری | دستاوردها را به فایل‌های نماد خود نقشه‌برداری می‌کند. |
| فایل های آیکون | اختیاری | نمادها با فرمت PNG، JPEG یا JPG. |
الزامات فایل فشرده:
- هیچ زیر شاخه ای وجود ندارد.
- نام فایل های منحصر به فرد
- فقط فایل‌های CSV، PNG، JPEG یا JPG.
- فایل‌های CSV نباید ردیف سرصفحه داشته باشند.
- هر فایل باید کمتر از 1 مگابایت باشد.
- The zip file shouldn't contain more than 203 files.
- Total zip file size must be under 200MB.
فرمت AchievementsMetadata.csv
فایل AchievementsMetadata.csv حاوی ابرداده برای هر دستاورد است. باید اطلاعات را به صورت مقادیر جدا شده با کاما به ترتیب زیر شامل شود:
Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order
این فیلدها در جدول زیر توضیح داده شده است:
| سرصفحه های ستون CSV | الزامی یا اختیاری | ارزش های پذیرفته شده |
|---|---|---|
| نام | مورد نیاز | حداکثر 100 کاراکتر |
| توضیحات | اختیاری | حداکثر 500 کاراکتر |
| ارزش افزایشی | اختیاری | True یا False |
| مراحل مورد نیاز | Required if Incremental Value is True. | عدد (بدون کسری یا اعشاری). حداکثر مقدار 10000 است. |
| حالت اولیه | مورد نیاز | Hidden یا Revealed |
| امتیاز | مورد نیاز | Number that is a multiple of 5, and the value must be between 5 and 200 |
| ترتیب فهرست | اختیاری | عدد (بدون کسری یا اعشاری و بزرگتر از صفر) |
AchievementsMetadata.csv file requirements:
- Each row must have seven values. اگر می خواهید مقداری را حذف کنید، آن را خالی بگذارید.
- The
NameandDescriptionfields are used as the default locale. - The
Namefield should be unique across all achievements. - فیلدهای زیر نباید حاوی کاما باشند:
NameوDescription.
نمونه فایل AchievementsMetadata.csv :
Achievement1,Achievement One,True,100,Hidden,5,20 Achievement2,Achievement Two,False,,Revealed,10,30
فرمت AchievementsLocalizations.csv
فایل AchievementsLocalizations.csv یک فایل اختیاری است که تمام داده‌های مورد نیاز برای توصیف هر دستاورد را برای کاربران در مناطق مختلف تنظیم می‌کند. Achievements are translated in alignment with the locales specified for the game.
It should include the information as comma-separated values in the following order:
Name, Localized name, Localized description, locale
این فیلدها در جدول زیر توضیح داده شده است:
| سرصفحه های ستون CSV | الزامی یا اختیاری | توضیحات | ارزش های پذیرفته شده |
|---|---|---|---|
| نام | مورد نیاز | Must match the Name column from AchievementsMetadata.csv . | حداکثر 100 کاراکتر |
| نام محلی | مورد نیاز | نام محلی برای دستاورد. | حداکثر 100 کاراکتر |
| توضیحات محلی | اختیاری | The localized description for the achievement in the specified locale. | حداکثر 500 کاراکتر |
| محلی | مورد نیاز | The locale code such as en-US . | Add translations for your game before specifying a locale. توجه داشته باشید که نمی توانید محلی پیش فرض را تعیین کنید. Supported locale codes can be found in the list of supported languages . |
AchievementsLocalizations.csv file requirements:
- نام دستاوردها در یک بازی باید در هر منطقه منحصر به فرد باشد.
به عنوان مثال، اگر یک بازی از هر دو زبان en-US و fr-FR پشتیبانی می کند، دستاوردی به نام "Achievement1" برای en-US نیز می تواند "Achievement1" برای fr-FR نامیده شود.
- Each row should have four values. If you want to omit the Localized description value, leave it blank.
A sample AchievementsLocalizations.csv file:
Achievement1,Achievement One,This is the description of achievement one in English.,en-US Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR Achievement2,Achievement Two,Description of achievement two.,en-US Achievement2,Logro Dos,Descripción del logro dos.,es-ES Achievement3,Achievement Three,,en-US Achievement3,Erfolg Drei,,de-DE
AchievementsIconMappings.csv format
فایل AchievementsIconMappings.csv یک فایل اختیاری است که برای نقشه برداری از دستاوردهای شما با نماد داده شده استفاده می شود. It should include the information as comma-separated values in the following order:
Name, icon filename
این فیلدها در جدول زیر توضیح داده شده است
| سرصفحه های ستون CSV | الزامی یا اختیاری | توضیحات |
|---|---|---|
| نام | مورد نیاز | Must match the Name column from AchievementsMetadata.csv . |
| نام فایل آیکون | مورد نیاز | The name of your icon file. |
AchievementsIconMappings.csv file requirements:
- Each row should have two values.
- Icons files can only be in PNG or JPEG formats.
A sample AchievementsIconMappings.csv file:
Valid Achievement,valid-achievement-icon.png Incremental Achievement,incremental-achievement-icon.jpeg No Description,no-description-icon.png Hidden Initial State,hidden-initial-state-icon.png Large Point Value,large-point-value-icon.jpeg
دستورالعمل های آیکون
نمادها باید به صورت فایل‌های PNG، JPEG یا JPG با ابعاد ۵۱۲×۵۱۲ ایجاد شوند. You only need to provide us with the icon for the unlocked achievement. We will generate a grayscale version for the revealed icon automatically. به همین دلیل، توصیه می‌کنیم نمادهای دستاورد شما شامل عناصر رنگارنگ باشد، بنابراین کاربران شما می‌توانند بین دستاوردهای آشکار و قفل نشده تمایز قفل کنند.
When an achievement icon is displayed in an Android [toast][a], the icon is overlaid with a circle and its outer corners are hidden. Make sure that your icon still looks good under these circumstances.
The same icon is used in all locales, so we recommend against including any text or localized content in an icon.
فایل های آیکون
نمادهایی که در فایل AchievementsIconMappings.csv به آنها ارجاع می دهید باید در آرشیو zip فعلی که وارد می کنید وجود داشته باشد.
Update games with existing achievements
You can add more achievements to a game and update existing ones in the Google Play Console.
دستاوردهای بیشتری اضافه کنید
اگر از قبل دستاوردهای موجود دارید و می خواهید موارد بیشتری اضافه کنید:
- In the Google Play Console , select a game.
- In the Play Games Services - Achievements page ( Grow > Play Games Services > Setup and management > Achievements ), select Add achievements .
ویرایش دستاوردها
اگر از قبل دستاوردهای موجود دارید و می خواهید ویرایش کنید:
- در کنسول Google Play ، یک بازی را انتخاب کنید.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، یک دستاورد را انتخاب کنید.
- شما می توانید هر یک از فیلدها را ویرایش کنید.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- در صفحه خدمات بازی‌های Play - دستاوردها ، دستاورد ویرایش‌شده در وضعیت «در دسترس آزمایش‌کنندگان» قرار دارد.
- پس از آزمایش دستاورد، روی مرور و انتشار کلیک کنید.
This republishes your game, along with all your updated achievement.
حذف یک دستاورد
هنگامی که دستاورد شما منتشر شد، نمی توان آن را حذف کرد. فقط می‌توانید یک دستاورد را در حالت از پیش منتشر شده حذف کنید
- در صفحه خدمات بازی های Play - دستاوردها ، یک دستاورد را انتخاب کنید.
- برای حذف دستاورد، روی حذف دستاورد کلیک کنید.
یک دستاورد را بازنشانی کنید
فقط می‌توانید داده‌های پیشرفت بازیکن را برای دستاوردهای پیش‌نویس خود بازنشانی کنید.
- در صفحه خدمات بازی های Play - دستاوردها ، یک دستاورد را انتخاب کنید.
- برای بازنشانی دستاوردها، روی بازنشانی پیشرفت کلیک کنید.
- برای بازنشانی داده‌های دستاورد به صورت برنامه‌ریزی، روش‌های مدیریت API
Achievementsرا فراخوانی کنید.
ترجمه برای دستاوردها اضافه کنید
شما می توانید ترجمه های خود را برای دستاوردهایی که با بازی شما مرتبط هستند مشخص کنید. قبل از انجام این کار، ابتدا مطمئن شوید که مراحل توضیح داده شده در افزودن ترجمه برای بازی خود را کامل کرده اید.
دو روش برای اضافه کردن ترجمه برای بازی خود وجود دارد:
می توانید از گزینه واردات دستاوردها برای آپلود ترجمه برای بسیاری از دستاوردهای جدید به طور همزمان استفاده کنید. نمی‌توانید از این گزینه برای بارگذاری ترجمه‌های دستاوردهای موجود استفاده کنید.
می توانید برای هر دستاورد در بازی خود ترجمه اضافه کنید. برای افزودن ترجمه خود برای هر دستاورد:
- در کنسول Google Play، تب Achievements را برای بازی خود باز کنید، سپس یک دستاورد موجود را انتخاب کنید.
- در صفحه جزئیات دستاوردها، برگه زبانی را که قبلاً در برگه جزئیات بازی اضافه کرده‌اید، انتخاب کنید.
- در صفحه جزئیات دستاورد برای آن زبان، فرم را با ترجمه های خود برای آن دستاورد ویرایش کنید.
- برای ذخیره جزئیات دستاورد ترجمه شده خود، روی ذخیره کلیک کنید.
پیاده سازی های مشتری
برای یادگیری نحوه پیاده سازی دستاوردها برای پلتفرم خود، به منابع زیر مراجعه کنید:
آزمایش دستاوردها
برای تأیید اینکه دستاوردها همانطور که در نظر گرفته شده کار می کنند، مراحل آزمایش آنها را دنبال کنید:
- یک مسیر تست داخلی راه اندازی کنید.
- حساب های آزمایشی را به پروژه بازی خود برای آزمایش کنندگان اضافه کنید .
- نمایه خدمات بازی‌های Play را برای یکی از حساب‌های آزمایشی با استفاده از برنامه بازی‌های Play ایجاد کنید.
- بازی را با استفاده از همان حساب آزمایشی که نمایه خدمات بازی‌های Play را برای آن ایجاد کرده‌اید باز کنید.
- بررسی کنید که «نان تست خوش آمدید» خدمات بازی‌های Play به‌عنوان تأییدیه تأیید تأیید خودکار موفقیت‌آمیز هنگام راه‌اندازی بازی روی صفحه نمایش داده می‌شود.
- بازی را انجام دهید و مراحل لازم را برای باز کردن قفل دستاوردها انجام دهید.
برای تأیید دستاوردها:
بررسی کنید که پس از تکمیل دستاورد، پنجره بازشو "Achievement unlocked" روی صفحه نمایش داده شود.
برنامه Play Store را باز کنید و بررسی کنید که بخش دستاوردها در YouTab دستاوردهای تکمیل شده و همچنین دستاوردهای در حال پیشرفت (با جزئیات پیشرفت) را نشان می دهد.
عملکرد دستاوردها را در Play Console دنبال کنید
در اینجا نحوه یافتن آمار سریع برای دستاوردهای فردی آورده شده است:
- در کنسول Google Play .
- به تنظیمات> پروژه های بازی بروید.
- یک بازی را انتخاب کنید.
- در منوی سمت چپ، روی دستاوردها کلیک کنید.
- در صفحه دستاوردها ، می‌توانید آماری را بیابید تا بفهمید که آیا بازیکنانتان قفل دستاوردها را باز می‌کنند یا خیر. برای کسانی که دستاوردهایشان پنهان نیست، می توانید ببینید که چند درصد آنها را باز می کنند. برای دستاوردهای مرحله اولیه، درصد باز کردن قفل معمولاً نزدیک به 100٪ است.
همچنین می‌توانید عملکرد سری‌های زمانی دستاوردها را در صفحه رشد > خدمات بازی‌های Play > آمار بازی پیگیری کنید.
دستاوردها را منتشر کنید
پس از اتمام تست، باید بازی خود را منتشر کنید. تمام دستاوردهای بازی شما با آن منتشر می شود. انتشار دستاوردها یک مرحله ضروری برای عملکرد مناسب دستاوردها است.
برای انتشار، مراحل زیر را دنبال کنید:
- در کنسول Google Play ، یک بازی را انتخاب کنید.
- در صفحه خدمات بازی‌های Play - دستاوردها ( رشد > خدمات بازی‌های Play > راه‌اندازی و مدیریت > دستاوردها )، روی بازبینی و انتشار کلیک کنید.
- در صفحه خدمات بازی‌های Play - انتشار ( رشد > خدمات بازی‌های Play > راه‌اندازی و مدیریت > انتشار )، اقدامات را مرور کرده و مشکلات را برطرف کنید.
- روی انتشار کلیک کنید.
تمام دستاوردهای بازی شما منتشر شده است.
اشتباهات رایجی که باید از آنها اجتناب کرد
این نکات اشتباهات رایجی را که باید هنگام اجرای دستاوردها در یک بازی اجتناب کنید، برجسته می کند. آنها بر اهمیت موارد زیر تأکید می کنند:
در کنسول Play، به Grow > Play Games Services > Setup and management > Achievements بروید.
- قبل از انتشار، بررسی کنید که دستاوردهای پیکربندی شده در Play Console در حالت «پیش‌نویس» نیستند.
- مقادیر شناسه دستاورد را از Play Console به کد بازی اضافه نکنید. به جای آن از پیاده سازی های مشتری استفاده کنید.
مطمئن شوید که منطق باز کردن قفل را روی کلاینت خود نیز پیاده سازی کرده اید.
- بازیکنان نمی توانند از مرحله ماشه ای که در آن API باز کردن قفل فراخوانی می شود، بگذرند. به عنوان مثال، تکمیل آموزش یک دستاورد است، اما بازیکنان می توانند خود آموزش را نادیده بگیرند.
این سند نحوه ادغام دستاوردها را با استفاده از کنسول Google Play یا تماس‌های API توضیح می‌دهد. عناصر و حالات اساسی دستاوردها را پوشش می دهد و نحوه ایجاد، وارد کردن و مدیریت آنها را توضیح می دهد.
قبل از شروع
دستورالعمل های دستاوردهای طراحی با کیفیت بالا را مرور کنید.
اصطلاحات در مبانی دستاوردها را مرور کنید.
دستاوردهای جدید ایجاد یا وارد کنید
برای پیاده سازی دستاوردها از ابتدا، مراحل زیر را دنبال کنید:
افزودن دستاوردها
دو راه برای ایجاد دستاوردها برای اولین بار با استفاده از کنسول Google Play وجود دارد:
- ایجاد یک دستاورد : تعاریف و ابرداده را برای هر دستاورد یکی یکی اضافه کنید.
- دستاوردهای وارد کردن : تعاریف و سایر ابرداده‌ها را برای چندین دستاورد با هم در یک مرحله وارد کنید.
یک دستاورد ایجاد کنید
برای ایجاد یک دستاورد برای یک بازی جدید و منتشر نشده، این مراحل را کامل کنید:
- در کنسول Google Play ، یک بازی را انتخاب کنید.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، ایجاد دستاورد را انتخاب کنید.
- در صفحه افزودن دستاوردها ، فرم را تکمیل کنید.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- پس از ایجاد یک دستاورد، باید دستاوردهای خود را منتشر کنید .
دستاوردهای وارداتی
برای افزودن چندین دستاورد به طور همزمان به بازی خود، از مراحل زیر استفاده کنید:
- یک فایل فشرده حاوی دستاوردهای خود بسازید.
- فایل را آپلود کنید.
برای اطلاعات بیشتر در مورد فایل فشرده، دستورالعمل های فایل فشرده را ببینید.
برای وارد کردن دستاوردها:
- در کنسول Google Play ، یک بازی را انتخاب کنید.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، وارد کردن دستاوردها را انتخاب کنید.
- در صفحه واردات دستاوردها ، روی آپلود کلیک کنید.
- فایل فشرده را برای آپلود انتخاب کنید.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- پس از وارد کردن دستاوردها، باید بازی خود را منتشر کنید .
دستورالعمل های فایل فشرده
شما می توانید چندین دستاورد را به طور همزمان با استفاده از یک فایل فشرده وارد کنید. برای استفاده از نام فایل های فشرده در فایل فشرده خود به جدول مراجعه کنید:
| نام فایل | الزامی یا اختیاری | ارزش های پذیرفته شده |
|---|---|---|
AchievementsMetadata.csv | مورد نیاز | فراداده برای هر دستاورد به صفات مراجعه کنید. |
AchievementsLocalizations.csv | اختیاری | ترجمه هایی را برای نام ها و توضیحات دستاوردها ارائه می دهد. |
AchievementsIconMappings.csv | اختیاری | دستاوردها را به فایل‌های نماد خود نقشه‌برداری می‌کند. |
| فایل های آیکون | اختیاری | نمادها با فرمت PNG، JPEG یا JPG. |
الزامات فایل فشرده:
- هیچ زیر شاخه ای وجود ندارد.
- نام فایل های منحصر به فرد
- فقط فایل‌های CSV، PNG، JPEG یا JPG.
- فایل‌های CSV نباید ردیف سرصفحه داشته باشند.
- هر فایل باید کمتر از 1 مگابایت باشد.
- فایل فشرده نباید بیش از 203 فایل داشته باشد.
- حجم کل فایل فشرده باید کمتر از 200 مگابایت باشد.
فرمت AchievementsMetadata.csv
فایل AchievementsMetadata.csv حاوی ابرداده برای هر دستاورد است. باید اطلاعات را به صورت مقادیر جدا شده با کاما به ترتیب زیر شامل شود:
Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order
این فیلدها در جدول زیر توضیح داده شده است:
| سرصفحه های ستون CSV | الزامی یا اختیاری | ارزش های پذیرفته شده |
|---|---|---|
| نام | مورد نیاز | حداکثر 100 کاراکتر |
| توضیحات | اختیاری | حداکثر 500 کاراکتر |
| ارزش افزایشی | اختیاری | True یا False |
| مراحل مورد نیاز | اگر Incremental Value True. | عدد (بدون کسری یا اعشاری). حداکثر مقدار 10000 است. |
| حالت اولیه | مورد نیاز | Hidden یا Revealed |
| امتیاز | مورد نیاز | عددی که مضربی از 5 است و مقدار آن باید بین 5 تا 200 باشد |
| ترتیب فهرست | اختیاری | عدد (بدون کسری یا اعشاری و بزرگتر از صفر) |
الزامات فایل AchievementsMetadata.csv:
- هر ردیف باید هفت مقدار داشته باشد. اگر می خواهید مقداری را حذف کنید، آن را خالی بگذارید.
- از فیلدهای
NameوDescriptionبه عنوان محلی پیش فرض استفاده می شود. - فیلد
Nameباید در همه دستاوردها منحصر به فرد باشد. - فیلدهای زیر نباید حاوی کاما باشند:
NameوDescription.
نمونه فایل AchievementsMetadata.csv :
Achievement1,Achievement One,True,100,Hidden,5,20 Achievement2,Achievement Two,False,,Revealed,10,30
فرمت AchievementsLocalizations.csv
فایل AchievementsLocalizations.csv یک فایل اختیاری است که تمام داده‌های مورد نیاز برای توصیف هر دستاورد را برای کاربران در مناطق مختلف تنظیم می‌کند. دستاوردها در تراز با مناطق مشخص شده برای بازی ترجمه می شوند.
باید اطلاعات را به صورت مقادیر جدا شده با کاما به ترتیب زیر شامل شود:
Name, Localized name, Localized description, locale
این فیلدها در جدول زیر توضیح داده شده است:
| سرصفحه های ستون CSV | الزامی یا اختیاری | توضیحات | ارزش های پذیرفته شده |
|---|---|---|---|
| نام | مورد نیاز | باید با ستون Name از AchievementsMetadata.csv مطابقت داشته باشد. | حداکثر 100 کاراکتر |
| نام محلی | مورد نیاز | نام محلی برای دستاورد. | حداکثر 100 کاراکتر |
| توضیحات محلی | اختیاری | شرح بومی سازی شده برای دستاورد در منطقه مشخص شده. | حداکثر 500 کاراکتر |
| محلی | مورد نیاز | کد محلی مانند en-US . | قبل از تعیین یک منطقه ، ترجمه هایی را برای بازی خود اضافه کنید . توجه داشته باشید که نمی توانید محلی پیش فرض را تعیین کنید. کدهای محلی پشتیبانی شده را می توان در لیست زبان های پشتیبانی شده پیدا کرد. |
الزامات فایل AchievementsLocalizations.csv :
- نام دستاوردها در یک بازی باید در هر منطقه منحصر به فرد باشد.
به عنوان مثال، اگر یک بازی از هر دو زبان en-US و fr-FR پشتیبانی می کند، دستاوردی به نام "Achievement1" برای en-US نیز می تواند "Achievement1" برای fr-FR نامیده شود.
- هر ردیف باید چهار مقدار داشته باشد. اگر می خواهید مقدار Localized description را حذف کنید، آن را خالی بگذارید.
نمونه فایل AchievementsLocalizations.csv :
Achievement1,Achievement One,This is the description of achievement one in English.,en-US Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR Achievement2,Achievement Two,Description of achievement two.,en-US Achievement2,Logro Dos,Descripción del logro dos.,es-ES Achievement3,Achievement Three,,en-US Achievement3,Erfolg Drei,,de-DE
فرمت AchievementsIconMappings.csv
فایل AchievementsIconMappings.csv یک فایل اختیاری است که برای نقشه برداری از دستاوردهای شما با نماد داده شده استفاده می شود. باید اطلاعات را به صورت مقادیر جدا شده با کاما به ترتیب زیر شامل شود:
Name, icon filename
این فیلدها در جدول زیر توضیح داده شده است
| سرصفحه های ستون CSV | الزامی یا اختیاری | توضیحات |
|---|---|---|
| نام | مورد نیاز | باید با ستون Name از AchievementsMetadata.csv مطابقت داشته باشد. |
| نام فایل آیکون | مورد نیاز | نام فایل آیکون شما. |
الزامات فایل AchievementsIconMappings.csv :
- هر ردیف باید دو مقدار داشته باشد.
- فایل‌های نماد فقط می‌توانند در فرمت‌های PNG یا JPEG باشند.
نمونه فایل AchievementsIconMappings.csv :
Valid Achievement,valid-achievement-icon.png Incremental Achievement,incremental-achievement-icon.jpeg No Description,no-description-icon.png Hidden Initial State,hidden-initial-state-icon.png Large Point Value,large-point-value-icon.jpeg
دستورالعمل های آیکون
نمادها باید به صورت فایل‌های PNG، JPEG یا JPG با ابعاد ۵۱۲×۵۱۲ ایجاد شوند. شما فقط باید نماد دستاورد باز شده را در اختیار ما قرار دهید. ما یک نسخه خاکستری برای نماد آشکار شده به طور خودکار تولید می کنیم. به همین دلیل، توصیه می‌کنیم نمادهای دستاورد شما شامل عناصر رنگارنگ باشد، بنابراین کاربران شما می‌توانند بین دستاوردهای آشکار و قفل نشده تمایز قفل کنند.
هنگامی که یک نماد دستاورد در یک Android [toast][a] نمایش داده می شود، نماد با یک دایره پوشانده می شود و گوشه های بیرونی آن پنهان می شود. مطمئن شوید که نماد شما همچنان در این شرایط خوب به نظر می رسد.
نماد یکسان در همه زبان‌ها استفاده می‌شود، بنابراین توصیه می‌کنیم از گنجاندن متن یا محتوای بومی‌سازی شده در یک نماد خودداری کنید.
فایل های آیکون
نمادهایی که در فایل AchievementsIconMappings.csv به آنها ارجاع می دهید باید در آرشیو zip فعلی که وارد می کنید وجود داشته باشد.
بازی ها را با دستاوردهای موجود به روز کنید
می‌توانید دستاوردهای بیشتری را به یک بازی اضافه کنید و دستاوردهای موجود را در کنسول Google Play به‌روزرسانی کنید.
دستاوردهای بیشتری اضافه کنید
اگر از قبل دستاوردهای موجود دارید و می خواهید موارد بیشتری اضافه کنید:
- در کنسول Google Play ، یک بازی را انتخاب کنید.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، افزودن دستاوردها را انتخاب کنید.
ویرایش دستاوردها
اگر از قبل دستاوردهای موجود دارید و می خواهید ویرایش کنید:
- در کنسول Google Play ، یک بازی را انتخاب کنید.
- در صفحه خدمات بازی های Play - دستاوردها ( رشد > خدمات بازی های Play > راه اندازی و مدیریت > دستاوردها )، یک دستاورد را انتخاب کنید.
- شما می توانید هر یک از فیلدها را ویرایش کنید.
- روی ذخیره به عنوان پیش نویس کلیک کنید.
- در صفحه خدمات بازی‌های Play - دستاوردها ، دستاورد ویرایش‌شده در وضعیت «در دسترس آزمایش‌کنندگان» قرار دارد.
- پس از آزمایش دستاورد، روی مرور و انتشار کلیک کنید.
این بازی شما را به همراه تمام دستاوردهای به روز شده شما بازنشر می کند.
حذف یک دستاورد
هنگامی که دستاورد شما منتشر شد، نمی توان آن را حذف کرد. فقط می‌توانید یک دستاورد را در حالت از پیش منتشر شده حذف کنید
- در صفحه خدمات بازی های Play - دستاوردها ، یک دستاورد را انتخاب کنید.
- برای حذف دستاورد، روی حذف دستاورد کلیک کنید.
یک دستاورد را بازنشانی کنید
فقط می‌توانید داده‌های پیشرفت بازیکن را برای دستاوردهای پیش‌نویس خود بازنشانی کنید.
- در صفحه خدمات بازی های Play - دستاوردها ، یک دستاورد را انتخاب کنید.
- برای بازنشانی دستاوردها، روی بازنشانی پیشرفت کلیک کنید.
- برای بازنشانی داده‌های دستاورد به صورت برنامه‌ریزی، روش‌های مدیریت API
Achievementsرا فراخوانی کنید.
ترجمه برای دستاوردها اضافه کنید
You can specify your own translations for achievements that are associated with your game. Before you do so, first make sure to complete the steps described in Adding translations for your game .
There are two ways in which you can add translations for your game:
You can use the import achievements option to upload translations for many new achievements at once. You cannot use this option to upload translations for already existing achievements.
You can add translations for each achievement in your game. To add your own translation for each achievement:
- In the Google Play Console open the Achievements tab for your game, then select an existing achievement.
- In the achievements details page, select the tab for a language that you previously added in the Game details tab.
- In the achievement details page for that language, edit the form with your translations for that achievement.
- Click Save to store your translated achievement details.
پیاده سازی های مشتری
To learn how to implement achievements for your platform, see the following resources:
Testing achievements
To verify that the achievements work as intended, follow the steps to test them:
- Set up an internal test track .
- Add test accounts to your game project for testers.
- Create Play Games Services profile for one of the test account using Play Games App.
- Open the game using the same test account for which you created the Play Games Services profile.
- Verify that Play Games Services "Welcome toast" is shown on the screen as a confirmation of successful automatic authentication on game launch.
- Play the game and complete the required steps to unlock the achievements.
To verify achievements:
Verify that "achievement unlocked" popup is shown on the screen when the achievement is completed.
Open the Play Store app and verify that the achievements section on YouTab shows completed as well as in-progress achievements (with progress details).
Track achievement performance in Play Console
Here's how to find quick statistics for individual achievements:
- In the Google Play Console .
- Go to Settings> Game projects .
- یک بازی را انتخاب کنید.
- On the left-hand menu, click Achievements .
- On your Achievements page, you can find statistics to understand whether your players are unlocking the achievements. For those whose achievements are not hidden, you can see what percentage are unlocking them. For early stage achievements, the unlock percentage is typically closer to 100%.
You can also track time series performance of achievements in the Grow > Play Games Services > Game statistics page.
Publish the achievements
Once you finish testing, you must publish your game. All of your game's achievements are published with it. Publishing achievements is a required step for achievements to function properly.
To publish, follow these steps:
- In the Google Play Console , select a game.
- In the Play Games Services - Achievements page ( Grow > Play Games Services > Setup and management > Achievements ), click Review and publish .
- In the Play Games Services - Publishing page ( Grow > Play Games Services > Setup and management > Publishing ), review the actions and fix the issues.
- روی انتشار کلیک کنید.
All of your game's achievements are published.
اشتباهات رایجی که باید از آنها اجتناب کرد
These points highlight common mistakes to avoid when implementing achievements in a game. They emphasize the importance of:
In the Play Console, go to Grow > Play Games Services > Setup and management > Achievements .
- Before publishing, verify that achievements configured in the Play Console are not in "Draft" state.
- Don't add achievement ID values from the Play Console to the game code. Use the client implementations instead.
Make sure you have also implemented the unlock logic on your client.
- Players cannot skip the trigger step where the unlock API is called. For example, completing the tutorial is an achievement, but players can skip the tutorial itself.