Firestore की मदद से लीडरबोर्ड बनाएं

1. शुरुआती जानकारी

पिछली बार अपडेट किए जाने की तारीख: 27-01-2023

लीडरबोर्ड बनाने के लिए क्या करना पड़ता है?

मुख्य रूप से, लीडरबोर्ड सिर्फ़ स्कोर की टेबल होती हैं. इसमें एक मुश्किल फ़ैक्टर हो जाता है: किसी भी स्कोर का रैंक पढ़ने के लिए, किसी न किसी क्रम में अन्य सभी स्कोर की जानकारी होना ज़रूरी है. साथ ही, अगर आपका गेम खेलना जारी रखता है, तो आपके लीडरबोर्ड बड़े हो जाएंगे. साथ ही, उन्हें बार-बार पढ़ा और लिखा जाएगा. लीडरबोर्ड को बेहतर तरीके से बनाने के लिए ज़रूरी है कि रैंकिंग से जुड़ी इस कार्रवाई को तुरंत मैनेज किया जा सके.

आपको क्या बनाना होगा

इस कोडलैब में, आपको कई अलग-अलग लीडरबोर्ड लागू करने होंगे. हर लीडरबोर्ड एक अलग स्थिति के लिए सही होगा.

आपको यह जानकारी मिलेगी

आपको चार अलग-अलग लीडरबोर्ड को लागू करने का तरीका पता चलेगा:

• रैंक तय करने के लिए, आसान रिकॉर्ड-काउंटिंग का इस्तेमाल करके आसान तरीके से लागू करना
• सस्ता, समय-समय पर अपडेट होने वाला लीडरबोर्ड
• बिना किसी तड़क-भड़क वाला रीयल-टाइम लीडरबोर्ड
• बहुत बड़े खिलाड़ी की अनुमानित रैंकिंग के लिए एक स्टोकेस्टिक (संभावित) लीडरबोर्ड

आपको इन चीज़ों की ज़रूरत होगी

• Chrome का नया वर्शन (107 या उसके बाद का वर्शन)
• Node.js 16 या इसके बाद का वर्शन (अगर nvm का इस्तेमाल किया जा रहा है, तो अपना वर्शन नंबर देखने के लिए nvm --version चलाएं)
• पैसे चुकाकर लिया गया Firebase ब्लेज़ प्लान (ज़रूरी नहीं)
• Firebase सीएलआई का v11.16.0 या इसके बाद का वर्शन
  इंस्टॉल करने के ज़्यादा विकल्पों के बारे में जानने के लिए, npm install -g firebase-tools चलाएं या सीएलआई दस्तावेज़ देखें.
• JavaScript, Cloud Firestore, Cloud Functions, और Chrome DevTools की जानकारी

2. सेट अप किया जा रहा है

कोड प्राप्त करें

हमने इस प्रोजेक्ट के लिए आपकी ज़रूरत की हर चीज़ को Git रेपो में डाल दिया है. शुरू करने के लिए, आपको कोड लेना होगा और उसे अपने पसंदीदा डेवलपर एनवायरमेंट में खोलना होगा. इस कोडलैब के लिए, हमने वीएस कोड का इस्तेमाल किया, लेकिन कोई भी टेक्स्ट एडिटर इस्तेमाल कर सकता है.

सोर्स कोड डाउनलोड करें और डाउनलोड की गई ZIP फ़ाइल को अनपैक करें.

या, अपनी पसंद की डायरेक्ट्री में क्लोन करें:

git clone https://github.com/FirebaseExtended/firestore-leaderboards-codelab.git

हमारा शुरुआती पॉइंट क्या है?

हमारा प्रोजेक्ट फ़िलहाल एक खाली स्लेट है, जिसमें कुछ फ़ंक्शन खाली हैं:

• index.html में कुछ ग्लू स्क्रिप्ट होती हैं, जो हमें डेव कंसोल से फ़ंक्शन शुरू करने और उनके आउटपुट देखने देती हैं. हम इसका इस्तेमाल अपने बैकएंड के साथ इंटरफ़ेस करने के लिए करेंगे और फ़ंक्शन को शुरू करने के नतीजे देखने के लिए करेंगे. असल दुनिया में, आपको सीधे अपने गेम से ये बैकएंड कॉल करने होंगे. हम इस कोडलैब में गेम का इस्तेमाल नहीं कर रहे हैं, क्योंकि हर बार लीडरबोर्ड में स्कोर जोड़ने के लिए गेम खेलने में बहुत ज़्यादा समय लगता है.
• functions/index.js में हमारे सभी Cloud फ़ंक्शन होते हैं. आपको कुछ यूटिलिटी फ़ंक्शन दिखेंगे, जैसे कि addScores और deleteScores के साथ ही, वे फ़ंक्शन जिन्हें हम इस कोडलैब में लागू करेंगे. ये फ़ंक्शन, किसी दूसरी फ़ाइल में हेल्पर फ़ंक्शन के बारे में बताते हैं.
• functions/functions-helpers.js में ऐसे खाली फ़ंक्शन हैं जिन्हें हम लागू करेंगे. हर लीडरबोर्ड के लिए, हम पढ़ने, बनाने, और अपडेट करने वाले फ़ंक्शन लागू करेंगे. साथ ही, आपको यह भी पता चलेगा कि लागू करने के हमारे चुने हुए विकल्प से, लागू करने की जटिलता और इसकी स्केलिंग परफ़ॉर्मेंस, दोनों पर क्या असर पड़ता है.
• functions/utils.js में ज़्यादा यूटिलिटी फ़ंक्शन हैं. हम इस कोडलैब में इस फ़ाइल को छुएं नहीं.

Firebase प्रोजेक्ट बनाना और उसे कॉन्फ़िगर करना

1. Firebase कंसोल में, प्रोजेक्ट जोड़ें पर क्लिक करें.
2. नया प्रोजेक्ट बनाने के लिए, प्रोजेक्ट का पसंदीदा नाम डालें.
   इससे प्रोजेक्ट के नाम के आधार पर, प्रोजेक्ट आईडी (प्रोजेक्ट के नाम के नीचे दिखाया गया) भी सेट हो जाएगा. प्रोजेक्ट आईडी को अपनी पसंद के मुताबिक बनाने के लिए, उस पर मौजूद बदलाव करें आइकॉन पर क्लिक करें. हालांकि, ऐसा करना ज़रूरी नहीं है.
3. अगर कहा जाए, तो Firebase की शर्तों को पढ़ें और स्वीकार करें.
4. जारी रखें पर क्लिक करें.
5. इस प्रोजेक्ट के लिए Google Analytics चालू करें विकल्प चुनें. इसके बाद, जारी रखें पर क्लिक करें.
6. इस्तेमाल करने के लिए, कोई मौजूदा Google Analytics खाता चुनें या नया खाता बनाने के लिए, नया खाता बनाएं चुनें.
7. प्रोजेक्ट बनाएं पर क्लिक करें.
8. प्रोजेक्ट बनाने के बाद, जारी रखें पर क्लिक करें.
9. बिल्ड मेन्यू में, फ़ंक्शन पर क्लिक करें और अगर कहा जाए, तो अपने प्रोजेक्ट को ब्लेज़ बिलिंग प्लान का इस्तेमाल करने के लिए अपग्रेड करें.

   Cloud Functions का इस्तेमाल करने के लिए बिलिंग खाते की ज़रूरत होती है. इसके अलावा, फ़ंक्शन को स्थानीय तौर पर चलाने के लिए Firebase एम्युलेटर का इस्तेमाल किया जा सकता है.

10. बिल्ड मेन्यू में, डेटा स्टोर फिर से स्टोर करें पर क्लिक करें.
11. स्क्रीन पर दिखने वाले डेटाबेस बनाएं डायलॉग बॉक्स में, टेस्ट मोड में शुरू करें चुनें. इसके बाद, आगे बढ़ें पर क्लिक करें.
12. Cloud Firestore की जगह के ड्रॉप-डाउन से कोई इलाका चुनें, फिर चालू करें पर क्लिक करें.

अपना लीडरबोर्ड कॉन्फ़िगर करें और चलाएं

1. टर्मिनल में, प्रोजेक्ट रूट पर जाएं और firebase use --add चलाएं. वह Firebase प्रोजेक्ट चुनें जिसे आपने अभी-अभी बनाया है.
2. प्रोजेक्ट के रूट में, firebase emulators:start --only hosting चलाएं.
3. अपने ब्राउज़र में, localhost:5000 पर जाएं.
4. Chrome DevTools का JavaScript कंसोल खोलें और leaderboard.js को इंपोर्ट करें:

   const leaderboard = await import("http://localhost:5000/scripts/leaderboard.js");
   

5. कंसोल में leaderboard.codelab(); चलाएं. अगर आपको वेलकम मैसेज दिखता है, तो इसका मतलब है कि आप पूरी तरह से तैयार हैं! अगर नहीं, तो एम्युलेटर को बंद कर दें और दूसरे से लेकर चौथे चरण तक फिर से चलाएं.

आइए, पहली बार लीडरबोर्ड लागू करने के बारे में बात करते हैं.

3. आसान लीडरबोर्ड लागू करना

इस सेक्शन के आखिर तक हम लीडरबोर्ड में स्कोर जोड़ पाएंगे और इससे हमें अपनी रैंक बताई जा सकेगी.

आगे बढ़ने से पहले, आइए यह बताते हैं कि लीडरबोर्ड को लागू करने का यह तरीका कैसे काम करता है: सभी खिलाड़ियों को एक ही कलेक्शन में सेव किया जाता है. कलेक्शन को फिर से हासिल करके और यह गिनकर कि किसी खिलाड़ी से आगे कितने खिलाड़ी हैं, सभी खिलाड़ियों की रैंक हासिल की जाती है. इससे स्कोर डालना और अपडेट करना आसान हो जाता है. नया स्कोर डालने के लिए, हम उसे कलेक्शन में जोड़ते हैं. इसके बाद, हम मौजूदा उपयोगकर्ता को फ़िल्टर करके, दस्तावेज़ को अपडेट करते हैं. चलिए देखते हैं, कोड में यह कैसा दिखता है.

functions/functions-helper.js में, createScore फ़ंक्शन लागू करें, जो करीब-करीब यह है कि यह उतना ही आसान है:

async function createScore(score, playerID, firestore) {
  return firestore.collection("scores").doc().create({
    user: playerID,
    score: score,
  });
}

स्कोर अपडेट करने के लिए, हमें गड़बड़ी की जांच करने वाली एक जांच जोड़नी होगी, ताकि यह पक्का हो सके कि अपडेट किया जा रहा स्कोर पहले से मौजूद है:

async function updateScore(playerID, newScore, firestore) {
  const playerSnapshot = await firestore.collection("scores")
      .where("user", "==", playerID).get();
  if (playerSnapshot.size !== 1) {
    throw Error(`User not found in leaderboard: ${playerID}`);
  }
  const player = playerSnapshot.docs[0];
  const doc = firestore.doc(player.id);
  return doc.update({
    score: newScore,
  });
}

आखिर में, हमारा आसान, लेकिन कम स्केल करने लायक रैंक फ़ंक्शन:

async function readRank(playerID, firestore) {
  const scores = await firestore.collection("scores")
      .orderBy("score", "desc").get();
  const player = `${playerID}`;
  let rank = 1;
  for (const doc of scores.docs) {
    const user = `${doc.get("user")}`;
    if (user === player) {
      return {
        user: player,
        rank: rank,
        score: doc.get("score"),
      };
    }
    rank++;
  }
  // No user found
  throw Error(`User not found in leaderboard: ${playerID}`);
}

चलिए, इसे आज़माकर देखते हैं! टर्मिनल में इन्हें चलाकर अपने फ़ंक्शन डिप्लॉय करें:

firebase deploy --only functions

और फिर, Chrome के JS कंसोल में, कुछ अन्य स्कोर जोड़ें, ताकि हम अन्य प्लेयर के बीच अपनी रैंकिंग देख सकें.

leaderboard.addScores(); // Results may take some time to appear.

अब हम मिक्स में अपना स्कोर जोड़ सकते हैं:

leaderboard.addScore(999, 11); // You can make up a score (second argument) here.

बदलाव पूरा होने के बाद, आपको कंसोल में "स्कोर बनाया गया" जवाब दिखेगा. क्या इसके बजाय कोई गड़बड़ी दिख रही है? गड़बड़ी देखने के लिए, Firebase कंसोल के ज़रिए फ़ंक्शन लॉग खोलें.

और आख़िर में, हम अपना स्कोर फ़ेच और अपडेट कर सकते हैं.

leaderboard.getRank(999);
leaderboard.updateScore(999, 0);
leaderboard.getRank(999); // we should be last place now (11)

हालांकि, इसे लागू करने से किसी दिए गए स्कोर की रैंक पाने के लिए हमें अनचाहे लीनियर समय और मेमोरी से जुड़ी ज़रूरतें मिल जाती हैं. इसकी वजह यह है कि फ़ंक्शन को प्रोसेस करने में लगने वाला समय और मेमोरी, दोनों ही सीमित होती हैं. इस वजह से, फ़ेच करने की प्रोसेस धीमी हो जाएगी. साथ ही, लीडरबोर्ड में काफ़ी स्कोर जुड़ने के बाद, नतीजे देने से पहले हमारे फ़ंक्शन का समय खत्म हो जाएगा या क्रैश हो जाएगा. यह साफ़ तौर पर कहा गया है कि अगर हम कुछ खिलाड़ियों को टारगेट नहीं करेंगे, तो हमें एक बेहतर गेम की ज़रूरत होगी.

अगर आप Firestore के शौकीन हैं, तो आपको COUNT एग्रीगेशन क्वेरी के बारे में पता होगा. इससे यह लीडरबोर्ड ज़्यादा बेहतर परफ़ॉर्म करेगा. और आप सही होंगे! COUNT क्वेरी के साथ, यह दस लाख या उससे ज़्यादा उपयोगकर्ताओं से काफ़ी कम हो जाता है, हालांकि इसका परफ़ॉर्मेंस अब भी एक जैसा ही रहता है.

हालांकि, आपको अपने मन में यह बात लग रही होगी कि अगर हम कलेक्शन में मौजूद सभी दस्तावेज़ों को फिर से इकट्ठा करते हैं, तो हम हर दस्तावेज़ को एक रैंक दे सकते हैं. इसके बाद, जब हमें उसे फ़ेच करने की ज़रूरत होगी, तब हम फ़ेच करने के लिए O(1) समय और मेमोरी का इस्तेमाल करेंगे! यही वजह है कि हम अपने अगले तरीके यानी समय-समय पर अपडेट होने वाले लीडरबोर्ड पर बात करते हैं.

4. समय-समय पर अपडेट होने वाला लीडरबोर्ड लागू करना

इस तरीके का मुख्य काम है, दस्तावेज़ में रैंक को सेव करना. इसलिए, इसे फ़ेच करने से हमें रैंक मिल जाती है और आपको कुछ भी करने की ज़रूरत नहीं पड़ती. इसे पाने के लिए, हमें एक नए तरह के फ़ंक्शन की ज़रूरत होगी.

index.js में, यह जोड़ें:

// Also add this to the top of your file
const admin = require("firebase-admin");

exports.scheduledFunctionCrontab = functions.pubsub.schedule("0 2 * * *")
    // Schedule this when most of your users are offline to avoid
    // database spikiness.
    .timeZone("America/Los_Angeles")
    .onRun((context) => {
      const scores = admin.firestore().collection("scores");
      scores.orderBy("score", "desc").get().then((snapshot) => {
        let rank = 1;
        const writes = [];
        for (const docSnapshot of snapshot.docs) {
          const docReference = scores.doc(docSnapshot.id);
          writes.push(docReference.set({rank: rank}, admin.firestore.SetOptions.merge()));
          rank++;
        }
        Promise.all(writes).then((result) => {
          console.log(`Writes completed with results: ${result}`);
        });
      });
      return null;
    });

अब हमारे पढ़ने, अपडेट करने, और लिखने से जुड़े काम, अच्छे और आसान तरीके से किए गए हैं. लिखें और अपडेट करें, दोनों में कोई बदलाव नहीं होता, लेकिन पढ़ा गया स्टेटस (functions-helpers.js में) हो जाता है:

async function readRank(playerID, firestore) {
  const scores = firestore.collection("scores");
  const playerSnapshot = await scores
      .where("user", "==", playerID).get();
  if (playerSnapshot.size === 0) {
    throw Error(`User not found in leaderboard: ${playerID}`);
  }

  const player = playerSnapshot.docs[0];
  if (player.get("rank") === undefined) {
    // This score was added before our scheduled function could run,
    // but this shouldn't be treated as an error
    return {
    user: playerID,
    rank: null,
    score: player.get("score"),
  };
  }

  return {
    user: playerID,
    rank: player.get("rank"),
    score: player.get("score"),
  };
}

माफ़ करें, अपने प्रोजेक्ट में बिलिंग खाता जोड़े बिना, न तो इसे डिप्लॉय किया जा सकता है और न ही इसकी जांच की जा सकती है. अगर आपके पास कोई बिलिंग खाता है, तो शेड्यूल किए गए फ़ंक्शन में इंटरवल कम करें और अपने फ़ंक्शन को अपने लीडरबोर्ड स्कोर के लिए जादुई तरीके से रैंक असाइन करें.

अगर ऐसा नहीं है, तो शेड्यूल किए गए फ़ंक्शन को मिटाएं और इसे लागू करने के अगले चरण पर जाएं.

अगले सेक्शन के लिए तैयारी करने के लिए, स्कोर कलेक्शन के बगल में मौजूद तीन बिंदुओं पर क्लिक करके, अपने Firestore डेटाबेस से स्कोर मिटाएं.

5. रीयल-टाइम ट्री लीडरबोर्ड लागू करें

यह तरीका, खोज डेटा को डेटाबेस कलेक्शन में सेव करके काम करता है. एक जैसे कलेक्शन बनाने के बजाय, हमारा लक्ष्य हर चीज़ को एक पेड़ में स्टोर करना है, जिसे हम दस्तावेज़ों के ज़रिए पार कर सकें. इससे हमें किसी दिए गए स्कोर की रैंक के लिए बाइनरी (या n-री) खोज करने की अनुमति मिलती है. यह कैसा दिख सकता है?

शुरुआत करने के लिए, हम अपने स्कोर को करीब-करीब बराबर बकेट में बांट पाएंगे. इसके लिए, हमें उपयोगकर्ताओं की ओर से लॉग किए जाने वाले स्कोर की वैल्यू की कुछ जानकारी होनी चाहिए; उदाहरण के लिए, अगर किसी कॉम्पटिटिव गेम में स्किल रेटिंग के लिए लीडरबोर्ड बनाया जा रहा है, तो आपके उपयोगकर्ता कौशल रेटिंग अक्सर सामान्य रूप से वितरित होती हैं. हमारा रैंडम स्कोर जनरेट करने वाला फ़ंक्शन JavaScript के Math.random() का इस्तेमाल करता है. इसकी वजह से डिस्ट्रिब्यूशन करीब-करीब बराबर होता है, इसलिए हम बकेट को बराबर बांटते हैं.

इस उदाहरण में, हम सादगी के लिए तीन बकेट का इस्तेमाल करेंगे. हालांकि, इस तरीके को असल ऐप्लिकेशन में इस्तेमाल करने पर, ज़्यादा बकेट तेज़ी से नतीजे मिलेंगे. ज़्यादा बकेट में कम कलेक्शन का मतलब है कि उनका कलेक्शन कम होने और लॉक होने का खतरा कम है.

किसी खिलाड़ी की रैंक, सबसे ज़्यादा स्कोर वाले खिलाड़ियों की संख्या के योग के साथ-साथ खिलाड़ी को दी जाने वाली रैंक के हिसाब से तय की जाती है. scores में हर कलेक्शन के लिए तीन दस्तावेज़ सेव किए जाएंगे. हर कलेक्शन में एक रेंज होगी. इसके बाद, हर कलेक्शन में दस्तावेज़ों की संख्या के बाद तीन सब-कलेक्शन सेव होंगे. रैंक पढ़ने के लिए, हम स्कोर खोजने के लिए इस पेड़ को देखेंगे और सबसे ज़्यादा स्कोर के योग पर नज़र रखेंगे. जब हमें अपना स्कोर मिल जाएगा, तो हमारे पास भी सही योग होगा.

लेखन बहुत जटिल है. सबसे पहले, हमें एक ही समय में कई बार लिखे या पढ़े जाने पर, डेटा में अंतर को रोकने के लिए अपने सभी लेख, लेन-देन के दौरान लिखना होगा. हमें उन सभी स्थितियों को भी बनाए रखना होगा जिनके बारे में हमने ऊपर बताया है. इसकी वजह यह है कि हम अपने नए दस्तावेज़ लिखने के लिए पेड़-पौधों से गुज़रते हैं. आखिर में, इस नए तरीके से काम करने वाली सारी मुश्किलों के साथ-साथ हमें अपने सभी मूल दस्तावेज़ों को स्टोर करने की ज़रूरत भी पड़ती है. इसलिए, स्टोरेज के लिए हमारी लागत थोड़ी बढ़ जाएगी. हालांकि, यह तरीका अब भी सामान्य है.

functions-helpers.js में:

async function createScore(playerID, score, firestore) {
  /**
   * This function assumes a minimum score of 0 and that value
   * is between min and max.
   * Returns the expected size of a bucket for a given score
   * so that bucket sizes stay constant, to avoid expensive
   * re-bucketing.
   * @param {number} value The new score.
   * @param {number} min The min of the previous range.
   * @param {number} max The max of the previous range. Must be greater than
   *     min.
   * @return {Object<string, number>} Returns an object containing the new min
   *     and max.
   */
  function bucket(value, min, max) {
    const bucketSize = (max - min) / 3;
    const bucketMin = Math.floor(value / bucketSize) * bucketSize;
    const bucketMax = bucketMin + bucketSize;
    return {min: bucketMin, max: bucketMax};
  }

  /**
   * A function used to store pending writes until all reads within a
   * transaction have completed.
   *
   * @callback PendingWrite
   * @param {admin.firestore.Transaction} transaction The transaction
   *     to be used for writes.
   * @return {void}
   */

  /**
   * Recursively searches for the node to write the score to,
   * then writes the score and updates any counters along the way.
   * @param {number} id The user associated with the score.
   * @param {number} value The new score.
   * @param {admin.firestore.CollectionReference} coll The collection this
   *     value should be written to.
   * @param {Object<string, number>} range An object with properties min and
   *     max defining the range this score should be in. Ranges cannot overlap
   *     without causing problems. Use the bucket function above to determine a
   *     root range from constant values to ensure consistency.
   * @param {admin.firestore.Transaction} transaction The transaction used to
   *     ensure consistency during tree updates.
   * @param {Array<PendingWrite>} pendingWrites A series of writes that should
   *     occur once all reads within a transaction have completed.
   * @return {void} Write error/success is handled via the transaction object.
   */
  async function writeScoreToCollection(
      id, value, coll, range, transaction, pendingWrites) {
    const snapshot = await transaction.get(coll);
    if (snapshot.empty) {
      // This is the first score to be inserted into this node.
      for (const write of pendingWrites) {
        write(transaction);
      }
      const docRef = coll.doc();
      transaction.create(docRef, {exact: {score: value, user: id}});
      return;
    }

    const min = range.min;
    const max = range.max;

    for (const node of snapshot.docs) {
      const data = node.data();
      if (data.exact !== undefined) {
        // This node held an exact score.
        const newRange = bucket(value, min, max);
        const tempRange = bucket(data.exact.score, min, max);

        if (newRange.min === tempRange.min &&
          newRange.max === tempRange.max) {
          // The scores belong in the same range, so we need to "demote" both
          // to a lower level of the tree and convert this node to a range.
          const rangeData = {
            range: newRange,
            count: 2,
          };
          for (const write of pendingWrites) {
            write(transaction);
          }
          const docReference = node.ref;
          transaction.set(docReference, rangeData);
          transaction.create(docReference.collection("scores").doc(), data);
          transaction.create(
              docReference.collection("scores").doc(),
              {exact: {score: value, user: id}},
          );
          return;
        } else {
          // The scores are in different ranges. Continue and try to find a
          // range that fits this score.
          continue;
        }
      }

      if (data.range.min <= value && data.range.max > value) {
        // The score belongs to this range that may have subvalues.
        // Increment the range's count in pendingWrites, since
        // subsequent recursion may incur more reads.
        const docReference = node.ref;
        const newCount = node.get("count") + 1;
        pendingWrites.push((t) => {
          t.update(docReference, {count: newCount});
        });
        const newRange = bucket(value, min, max);
        return writeScoreToCollection(
            id,
            value,
            docReference.collection("scores"),
            newRange,
            transaction,
            pendingWrites,
        );
      }
    }

    // No appropriate range was found, create an `exact` value.
    transaction.create(coll.doc(), {exact: {score: value, user: id}});
  }

  const scores = firestore.collection("scores");
  const players = firestore.collection("players");
  return firestore.runTransaction((transaction) => {
    return writeScoreToCollection(
        playerID, score, scores, {min: 0, max: 1000}, transaction, [],
    ).then(() => {
      transaction.create(players.doc(), {
        user: playerID,
        score: score,
      });
    });
  });
}

यह हमारे पिछले कार्यान्वयन से निश्चित रूप से ज़्यादा जटिल है, जिसमें सिर्फ़ एक तरीका के लिए कॉल किया गया था और उसमें सिर्फ़ छह लाइन के कोड का इस्तेमाल किया गया था. इस तरीके को लागू करने के बाद, डेटाबेस में कुछ स्कोर जोड़कर देखें. साथ ही, आपको मिलने वाले ट्री की बनावट को भी ध्यान से देखें. अपने JS कंसोल में:

leaderboard.addScores();

डेटाबेस का स्ट्रक्चर कुछ इस तरह का होना चाहिए, जिसमें ट्री स्ट्रक्चर साफ़ तौर पर दिख रहा हो और पेड़ की पत्तियां, अलग-अलग स्कोर को दिखाती हों.

scores
  - document
    range: 0-333.33
    count: 2
    scores:
      - document
        exact:
          score: 18
          user: 1
      - document
        exact:
          score: 22
          user: 2

अब हमारे रास्ते में आने की मुश्किलें कम हो गई हैं. इसलिए, हम ऊपर बताए गए तरीके से पेड़ों की जांच करके स्कोर पढ़ सकते हैं.

async function readRank(playerID, firestore) {
  const players = await firestore.collection("players")
      .where("user", "==", playerID).get();
  if (players.empty) {
    throw Error(`Player not found in leaderboard: ${playerID}`);
  }
  if (players.size > 1) {
    console.info(`Multiple scores with player ${playerID}, fetching first`);
  }
  const player = players.docs[0].data();
  const score = player.score;

  const scores = firestore.collection("scores");

  /**
   * Recursively finds a player score in a collection.
   * @param {string} id The player's ID, since some players may be tied.
   * @param {number} value The player's score.
   * @param {admin.firestore.CollectionReference} coll The collection to
   *     search.
   * @param {number} currentCount The current count of players ahead of the
   *     player.
   * @return {Promise<number>} The rank of the player (the number of players
   *     ahead of them plus one).
   */
  async function findPlayerScoreInCollection(id, value, coll, currentCount) {
    const snapshot = await coll.get();
    for (const doc of snapshot.docs) {
      if (doc.get("exact") !== undefined) {
        // This is an exact score. If it matches the score we're looking
        // for, return. Otherwise, check if it should be counted.
        const exact = doc.data().exact;
        if (exact.score === value) {
          if (exact.user === id) {
            // Score found.
            return currentCount + 1;
          } else {
            // The player is tied with another. In this case, don't increment
            // the count.
            continue;
          }
        } else if (exact.score > value) {
          // Increment count
          currentCount++;
          continue;
        } else {
          // Do nothing
          continue;
        }
      } else {
        // This is a range. If it matches the score we're looking for,
        // search the range recursively, otherwise, check if it should be
        // counted.
        const range = doc.data().range;
        const count = doc.get("count");
        if (range.min > value) {
          // The range is greater than the score, so add it to the rank
          // count.
          currentCount += count;
          continue;
        } else if (range.max <= value) {
          // do nothing
          continue;
        } else {
          const subcollection = doc.ref.collection("scores");
          return findPlayerScoreInCollection(
              id,
              value,
              subcollection,
              currentCount,
          );
        }
      }
    }
    // There was no range containing the score.
    throw Error(`Range not found for score: ${value}`);
  }

  const rank = await findPlayerScoreInCollection(playerID, score, scores, 0);
  return {
    user: playerID,
    rank: rank,
    score: score,
  };
}

अपडेट को सिर्फ़ एक कसरत के तौर पर शामिल किया गया है. leaderboard.addScore(id, score) और leaderboard.getRank(id) तरीकों से अपने JS कंसोल में स्कोर जोड़कर और फ़ेच करके देखें. साथ ही, देखें कि Firebase कंसोल में आपका लीडरबोर्ड कैसा बदलता है.

हालांकि, इस लागू करने से लॉगारिद्मिक परफ़ॉर्मेंस को हासिल करने के लिए हमने जो जटिलता जोड़ी है, उसके लिए कीमत चुकानी पड़ सकती है.

• लीडरबोर्ड को लागू करने के इस तरीके का इस्तेमाल करने पर, लॉक के लिए होने वाले विवाद से जुड़ी समस्याएं आ सकती हैं. ऐसा इसलिए होता है, क्योंकि लेन-देन के दौरान दस्तावेज़ों को एक जैसा बनाए रखने के लिए, उन्हें पढ़ना और लिखना ज़रूरी होता है.
• दूसरा, Firestore में सब-कलेक्शन की गहराई की सीमा 100 होती है. इसका मतलब है कि 100 बराबरी वाले स्कोर के बाद, आपको सबट्री बनाने से बचना होगा. हालांकि, इस तरीके में यह लागू नहीं होता.
• और आखिर में, यह लीडरबोर्ड सिर्फ़ उन आदर्श मामलों में लॉगारिद्मिक तरीके से स्केल करता है जहां पेड़ संतुलित है–अगर यह असंतुलित है, तो इस लीडरबोर्ड का सबसे खराब प्रदर्शन एक बार फिर से लीनियर रहा.

काम पूरा होने के बाद, Firebase कंसोल के ज़रिए scores और players कलेक्शन मिटाएं. इसके बाद, हम लीडरबोर्ड को आखिरी बार लागू करने की प्रोसेस शुरू करेंगे.

6. स्टोकेस्टिक (संभावित) लीडरबोर्ड लागू करना

इंसर्शन कोड को चलाते समय, आपको ऐसा लग सकता है कि अगर उसे एक साथ कई बार चलाया जाता है, तो आपके फ़ंक्शन लेन-देन लॉक के विवाद से जुड़ा गड़बड़ी का मैसेज नहीं दिखा पाएंगे. ऐसे कई तरीके हैं जिन्हें हम इस कोडलैब में नहीं एक्सप्लोर करेंगे. हालांकि, अगर आपको सटीक रैंकिंग की ज़रूरत नहीं है, तो पिछले तरीके की सभी जटिलता को आसान और तेज़ बनाने के लिए हटाया जा सकता है. आइए, देखते हैं कि हम अपने खिलाड़ियों की अनुमानित रैंक कैसे वापस कर सकते हैं के स्कोर को बदल देता है और वह हमारे डेटाबेस के लॉजिक में कैसे बदलाव करता है.

इस तरीके के लिए, हम अपने लीडरबोर्ड को 100 बकेट में विभाजित करेंगे, जिसमें से हर हमें उस स्कोर का करीब एक प्रतिशत दिखाई देगा, जिसे हम मिलने की उम्मीद करते हैं. यह तरीका हमारे स्कोर डिस्ट्रिब्यूशन की जानकारी के बिना भी काम करता है. इस मामले में, हमारे पास पूरे बकेट में करीब-करीब बराबर स्कोर के डिस्ट्रिब्यूशन की गारंटी देने का कोई तरीका नहीं है. हालांकि, अगर हमें यह पता होगा कि हमारे स्कोर कैसे डिस्ट्रिब्यूट होंगे, तो हम ज़्यादा सटीक तरीके से अनुमान लगा पाएंगे.

हमारे काम करने के तरीके के बारे में यहां बताया गया है: पहले की तरह, हर बकेट में स्कोर की संख्या और स्कोर की रेंज का पता चलता है. नया स्कोर डालने पर, हम स्कोर के लिए बकेट ढूंढेंगे और उसकी संख्या बढ़ाएंगे. कोई रैंक फ़ेच करते समय, हम उससे पहले बकेट का योग करेंगे और फिर आगे खोजने की बजाय अपनी बकेट में अनुमानित करेंगे. इसकी वजह से, हमें काफ़ी अच्छे और लगातार समय का पता लगाने और क्वेरी डालने की सुविधा मिलती है. साथ ही, इसके लिए बहुत कम कोड की ज़रूरत होती है.

पहला, इंसर्शन:

// Add this line to the top of your file.
const admin = require("firebase-admin");

// Implement this method (again).
async function createScore(playerID, score, firestore) {
  const scores = await firestore.collection("scores").get();
  if (scores.empty) {
    // Create the buckets since they don't exist yet.
    // In a real app, don't do this in your write function. Do it once
    // manually and then keep the buckets in your database forever.
    for (let i = 0; i < 10; i++) {
      const min = i * 100;
      const max = (i + 1) * 100;
      const data = {
        range: {
          min: min,
          max: max,
        },
        count: 0,
      };
      await firestore.collection("scores").doc().create(data);
    }
    throw Error("Database not initialized");
  }

  const buckets = await firestore.collection("scores")
      .where("range.min", "<=", score).get();
  for (const bucket of buckets.docs) {
    const range = bucket.get("range");
    if (score < range.max) {
      const writeBatch = firestore.batch();
      const playerDoc = firestore.collection("players").doc();
      writeBatch.create(playerDoc, {
        user: playerID,
        score: score,
      });
      writeBatch.update(
          bucket.ref,
          {count: admin.firestore.FieldValue.increment(1)},
      );
      const scoreDoc = bucket.ref.collection("scores").doc();
      writeBatch.create(scoreDoc, {
        user: playerID,
        score: score,
      });
      return writeBatch.commit();
    }
  }
}

आपको दिखेगा कि इस इंसर्शन कोड में सबसे ऊपर आपके डेटाबेस की स्थिति को शुरू करने के लिए कुछ लॉजिक हैं. साथ ही, आपको प्रोडक्शन में ऐसा कुछ न करने की चेतावनी भी मिलेगी. शुरू करने के लिए, कोड को रेस कंडिशन के हिसाब से बिलकुल भी सुरक्षित नहीं किया गया है. इसलिए, अगर आपको ऐसा करना है, तो एक साथ कई लिखने पर, आपको कई डुप्लीकेट बकेट देकर आपका डेटाबेस खराब कर देगा.

अपने फ़ंक्शन को डिप्लॉय करें. इसके बाद, सभी बकेट को शुरू करने के लिए शून्य की गिनती के साथ कोई इंसर्शन चलाएं. इससे एक गड़बड़ी दिखेगी, जिसे आप अनदेखा कर सकते हैं.

leaderboard.addScore(999, 0); // The params aren't important here.

अब डेटाबेस सही तरीके से शुरू हो गया है, इसलिए हम addScores चलाकर 'Firebase कंसोल' में अपने डेटा का स्ट्रक्चर देख सकते हैं. हमने आखिरी बार जो स्ट्रक्चर लागू किया था उसकी तुलना में यह स्ट्रक्चर काफ़ी बेहतर है. हालांकि, वे काफ़ी हद तक एक जैसे हैं.

leaderboard.addScores();

और, अब स्कोर के बारे में जानने के लिए:

async function readRank(playerID, firestore) {
  const players = await firestore.collection("players")
      .where("user", "==", playerID).get();
  if (players.empty) {
    throw Error(`Player not found in leaderboard: ${playerID}`);
  }
  if (players.size > 1) {
    console.info(`Multiple scores with player ${playerID}, fetching first`);
  }
  const player = players.docs[0].data();
  const score = player.score;

  const scores = await firestore.collection("scores").get();
  let currentCount = 1; // Player is rank 1 if there's 0 better players.
  let interp = -1;
  for (const bucket of scores.docs) {
    const range = bucket.get("range");
    const count = bucket.get("count");
    if (score < range.min) {
      currentCount += count;
    } else if (score >= range.max) {
      // do nothing
    } else {
      // interpolate where the user is in this bucket based on their score.
      const relativePosition = (score - range.min) / (range.max - range.min);
      interp = Math.round(count - (count * relativePosition));
    }
  }

  if (interp === -1) {
    // Didn't find a correct bucket
    throw Error(`Score out of bounds: ${score}`);
  }

  return {
    user: playerID,
    rank: currentCount + interp,
    score: score,
  };
}

हमने addScores फ़ंक्शन से स्कोर का एक समान वितरण जनरेट किया है और हम बकेट में लीनियर इंटरपोलेशन का इस्तेमाल करते हैं, इसलिए हमें बहुत सटीक नतीजे मिलेंगे, क्योंकि हम उपयोगकर्ताओं की संख्या बढ़ाते हैं और हमारे लीडरबोर्ड का परफ़ॉर्मेंस खराब नहीं होगा. साथ ही, हमें गिनती अपडेट करते समय लॉक होने के विवाद (ज़्यादा से ज़्यादा) के बारे में चिंता नहीं करनी होगी.

7. परिशिष्ट: नकल

रुकिए, आप सोच रहे होंगे कि अगर मैं ब्राउज़र टैब के JS कंसोल के ज़रिए अपने कोडलैब (कोड बनाना सीखना) में वैल्यू लिख रहा हूं, तो क्या मेरे खिलाड़ी सिर्फ़ लीडरबोर्ड पर जाकर यह नहीं कह सकते कि उन्होंने ज़्यादा स्कोर किया है जिसे वे सही तरीके से हासिल नहीं कर पाए?

हां, वे कर सकते हैं. अगर आपको धोखाधड़ी से बचना है, तो सुरक्षा नियमों की मदद से क्लाइंट को आपके डेटाबेस में लिखने और Cloud Functions का सुरक्षित ऐक्सेस बंद करने की सुविधा मिलती है, ताकि क्लाइंट उन्हें सीधे कॉल न कर सकें. इसके बाद, लीडरबोर्ड पर स्कोर का अपडेट भेजने से पहले अपने सर्वर पर इन-गेम कार्रवाइयों की पुष्टि करें.

यह ध्यान रखना ज़रूरी है कि इस रणनीति से धोखाधड़ी से बचने की कोई सुविधा नहीं होती. इसके पास ही काफ़ी इंसेंटिव होता है. धोखाधड़ी करने वाले लोग, सर्वर साइड की पुष्टि से बचने के नए-नए तरीके ढूंढ सकते हैं. साथ ही, कई बड़े और सफल वीडियो गेम लगातार अपने चीयरों की पहचान करके, उनकी मदद से नए-नए चीतों की पहचान करके उन्हें बढ़ने से रोकते हैं. इस वजह से, यह तय करना बहुत मुश्किल है कि हर गेम के लिए सर्वर साइड से की जाने वाली पुष्टि पहले से ही तय होती है; Firebase, ऐप्लिकेशन की जांच जैसे गलत इस्तेमाल को रोकने के लिए टूल उपलब्ध कराता है. ये किसी उपयोगकर्ता को स्क्रिप्ट के मुताबिक बनाए गए आसान क्लाइंट की मदद से आपका गेम कॉपी करने से रोकते हैं. हालांकि, Firebase धोखाधड़ी को रोकने के लिए ऐसी कोई सेवा नहीं देता है.

अगर सर्वर साइड से की जाने वाली पुष्टि की कोई ज़रूरत नहीं है, तो यह गेम लोगों को धोखाधड़ी वाले किसी गेम या गेम में धोखाधड़ी करने से रोकने में काफ़ी कम समय लगता है. ऐसे में, आपको एक लीडरबोर्ड दिखेगा, जिसमें सभी टॉप वैल्यू धोखाधड़ी करने वालों को शामिल की जाएंगी.

8. बधाई

बधाई हो, आपने Firebase पर चार अलग-अलग लीडरबोर्ड बना लिए हैं! आपके गेम की सटीक जानकारी और स्पीड के हिसाब से, आपके पास कम कीमत में वह गेम चुनने का विकल्प होता है जो आपके लिए सही हो.

इसके बाद, गेम के लिए सीखने के पाथवे देखें.