Codelab בנושא AngularFire לאינטרנט

1. סקירה כללית

ב-Codelab הזה תלמדו איך להשתמש ב-AngularFire כדי ליצור אפליקציות אינטרנט על ידי הטמעה ופריסה של לקוח צ'אט באמצעות מוצרים ושירותים של Firebase.

מה תלמדו

• בניית אפליקציית אינטרנט באמצעות Angular ו-Firebase.
• סנכרון נתונים באמצעות Cloud Firestore ו-Cloud Storage for Firebase.
• לאמת את המשתמשים באמצעות אימות ב-Firebase.
• פריסת אפליקציית האינטרנט ב-Firebase App Hosting.
• שליחת התראות באמצעות העברת הודעות בענן ב-Firebase.
• איסוף נתוני הביצועים של אפליקציית האינטרנט.

מה צריך להכין

• חשבון GitHub
• היכולת לשדרג את פרויקט Firebase לתוכנית התמחור והתשלומים של Bllaze.
• עורך IDE/הטקסט לבחירתכם, כמו WebStorm , Sublime או VS Code
• מנהל החבילות npm, שמגיע בדרך כלל עם Node.js
• מסוף/מסוף
• דפדפן לבחירתך, כגון Chrome
• קוד לדוגמה ב-Codelab (כדי לקבל את הקוד, עיינו בשלב הבא ב-Codelab).

2. קבלת קוד לדוגמה

יצירת מאגר ב-GitHub

קוד המקור של ה-codelab נמצא בכתובת https://github.com/firebase/codelab-friendlychat-web. המאגר מכיל פרויקטים לדוגמה לכמה פלטפורמות. עם זאת, ה-Codelab הזה משתמש רק בספרייה angularfire-start.

מעתיקים את התיקייה angularfire-start למאגר שלכם:

1. באמצעות טרמינל, יוצרים תיקייה חדשה במחשב ומשנים אותה לספרייה החדשה:

   mkdir codelab-friendlyeats-web
   
   cd codelab-friendlyeats-web
   

2. משתמשים בחבילת ה-npm giget כדי לאחזר רק את התיקייה angularfire-start:

   npx giget@latest gh:firebase/codelab-friendlychat-web/angularfire-start#master . --install
   

3. מעקב אחר שינויים באופן מקומי באמצעות git:

   git init
   
   git add .
   
   git commit -m "codelab starting point"
   
   git branch -M main
   

4. יוצרים מאגר חדש ב-GitHub: https://github.com/new. נותנים לו שם כלשהו.
   1. GitHub יספק כתובת URL חדשה של מאגר שנראית כמו https://github.com/[user-name]/[repository-name].git או git@github.com:[user-name]/[repository-name].git. מעתיקים את כתובת ה-URL הזו.
5. מעבירים את השינויים המקומיים למאגר החדש ב-GitHub. מריצים את הפקודה הבאה (תוך החלפת כתובת ה-URL של המאגר ב-placeholder של your-repository-url).

   git remote add origin your-repository-url
   
   git push -u origin main
   

6. עכשיו קוד ההתחלה אמור להופיע במאגר שלכם ב-GitHub.

3. יצירה והגדרה של פרויקט Firebase

יצירת פרויקט Firebase

1. נכנסים למסוף Firebase.
2. במסוף Firebase, לוחצים על Add Project (הוספת פרויקט) ומזינים את השם FriendlyChat לפרויקט ב-Firebase. חשוב לזכור את מזהה הפרויקט ב-Firebase.
3. מבטלים את הסימון של Enable Google Analytics for this project (הפעלת Google Analytics עבור הפרויקט הזה).
4. לוחצים על Create Project.

באפליקציה שתבנו נעשה שימוש במוצרי Firebase שזמינים לאפליקציות אינטרנט:

• אימות ב-Firebase כדי לאפשר למשתמשים להיכנס לאפליקציה בקלות.
• Cloud Firestore כדי לשמור נתונים מובְנים בענן ולקבל התראות מיידיות על שינויים בנתונים.
• Cloud Storage for Firebase לשמירת קבצים בענן.
• אירוח אפליקציות ב-Firebase ליצירה, לאירוח ולהצגה של האפליקציה.
• העברת הודעות בענן ב-Firebase כדי לשלוח התראות ולהציג התראות קופצות בדפדפן.
• מעקב אחר ביצועים ב-Firebase כדי לאסוף נתונים על ביצועי המשתמשים באפליקציה.

לחלק מהמוצרים האלה צריך להגדיר הגדרות מיוחדות או להפעיל אותם באמצעות מסוף Firebase.

שדרוג של תוכנית התמחור ב-Firebase

כדי להשתמש באירוח אפליקציות ב-Firebase וב-Cloud Storage for Firebase, הפרויקט ב-Firebase צריך להיות מוגדר לתוכנית תמחור ותשלומים לפי שימוש (Blaze). כלומר, הפרויקט מקושר לחשבון לחיוב ב-Cloud.

• בחשבון לחיוב ב-Cloud נדרש אמצעי תשלום, כמו כרטיס אשראי.
• אם אתם משתמשים חדשים ב-Firebase וב-Google Cloud, כדאי לבדוק אם אתם זכאים לקרדיט בסך 300$ ולחשבון לחיוב ב-Cloud בתקופת ניסיון בחינם.
• אם אתם עורכים את ה-Codelab כחלק מאירוע, כדאי לשאול את המארגן אם יש זיכויים ב-Cloud.

כדי לשדרג את הפרויקט לתוכנית Blaze:

1. במסוף Firebase, בוחרים באפשרות שדרוג התוכנית.
2. בוחרים את התוכנית Blaze. פועלים לפי ההוראות במסך כדי לקשר חשבון לחיוב ב-Cloud לפרויקט.
   אם הייתם צריכים ליצור חשבון לחיוב ב-Cloud כחלק מהשדרוג הזה, ייתכן שתצטרכו לחזור לתהליך השדרוג במסוף Firebase כדי להשלים את השדרוג.

הוספה של אפליקציית אינטרנט ב-Firebase לפרויקט

1. לוחצים על סמל האינטרנט כדי ליצור אפליקציית אינטרנט חדשה של Firebase.
2. לרשום את האפליקציה בכינוי צ'אט ידידותי. אין לסמן את התיבה שלצד יש להגדיר גם אירוח ב-Firebase לאפליקציה זו. לוחצים על רישום האפליקציה.
3. בשלב הבא יופיע אובייקט תצורה. אין צורך בו כרגע. לוחצים על המשך למסוף.

הגדרת אימות

כדי לאפשר למשתמשים להיכנס לאפליקציית האינטרנט באמצעות חשבונות Google שלהם, צריך להשתמש בשיטת הכניסה של Google.

1. במסוף Firebase, עוברים אל Authentication.
2. לוחצים על תחילת העבודה.
3. בעמודה ספקים נוספים, לוחצים על Google > הפעלה.
4. בתיבת הטקסט Public name for project, מזינים שם שקל לזכור, כמו My Next.js app.
5. בתפריט הנפתח Support email for project, בוחרים את כתובת האימייל שלכם.
6. לוחצים על שמירה.

הגדרת Cloud Firestore

אפליקציית האינטרנט משתמשת ב-Cloud Firestore כדי לשמור הודעות צ'אט ולקבל הודעות צ'אט חדשות.

כך מגדירים את Cloud Firestore בפרויקט Firebase:

1. בחלונית השמאלית של מסוף Firebase, מרחיבים את Build ובוחרים באפשרות Firestore מסד נתונים.
2. לוחצים על Create dataset.
3. משאירים את הערך (default) בשדה Database ID.
4. בוחרים מיקום למסד הנתונים ולוחצים על הבא.
   אם מדובר באפליקציה אמיתית, כדאי לבחור מיקום שקרוב למשתמשים שלך.
5. לוחצים על הפעלה במצב בדיקה. קוראים את כתב הוויתור לגבי כללי האבטחה.
   בהמשך הסדנה תוסיפו כללי אבטחה כדי לאבטח את הנתונים. אין להפיץ או לחשוף אפליקציה באופן ציבורי בלי להוסיף כללי אבטחה למסד הנתונים.
6. לוחצים על יצירה.

הגדרת Cloud Storage for Firebase

אפליקציית האינטרנט משתמשת ב-Cloud Storage for Firebase כדי לאחסן, להעלות ולשתף תמונות.

כך מגדירים את Cloud Storage for Firebase בפרויקט Firebase:

1. בחלונית הימנית של מסוף Firebase, מרחיבים את Build ובוחרים באפשרות Storage.
2. לוחצים על תחילת העבודה.
3. יש לבחור מיקום לקטגוריית האחסון המוגדרת כברירת מחדל.
   קטגוריות ב-US-WEST1, ב-US-CENTRAL1 וב-US-EAST1 יכולות לנצל את המסלול 'חינם תמיד' ל-Google Cloud Storage. קטגוריות בכל המיקומים האחרים כפופות לתמחור ולשימוש ב-Google Cloud Storage.
4. לוחצים על התחלה במצב בדיקה. קוראים את כתב הוויתור לגבי כללי האבטחה.
   בהמשך הסדנה תוסיפו כללי אבטחה כדי לאבטח את הנתונים. אין להפיץ או לחשוף אפליקציה באופן ציבורי בלי להוסיף כללי אבטחה לקטגוריית האחסון.
5. לוחצים על יצירה.

4. התקנת ממשק שורת הפקודה של Firebase

ממשק שורת הפקודה של Firebase (CLI) מאפשר לכם להשתמש באירוח ב-Firebase כדי לשרת את אפליקציית האינטרנט שלכם באופן מקומי, וגם לפרוס את אפליקציית האינטרנט שלכם לפרויקט Firebase.

1. כדי להתקין את ה-CLI, מריצים את פקודת ה-npm הבאה:

npm -g install firebase-tools@latest

2. מריצים את הפקודה הבאה כדי לוודא שה-CLI הוטמע כמו שצריך:

firebase --version

צריך לוודא שהגרסה של Firebase CLI היא מגרסה 13.9.0 ואילך.

3. מריצים את הפקודה הבאה כדי להעניק הרשאה ל-CLI של Firebase:

firebase login

הגדרתם את התבנית של אפליקציית האינטרנט כדי למשוך את ההגדרות של האפליקציה ל-Firebase Hosting מהספרייה המקומית של האפליקציה (המאגר ששכפלתם מוקדם יותר ב-codelab). עם זאת, כדי לשלוף את ההגדרות האישיות, צריך לשייך את האפליקציה לפרויקט Firebase.

4. חשוב לוודא ששורת הפקודה ניגשת לספריית angularfire-start המקומית של האפליקציה.
5. כדי לשייך את האפליקציה לפרויקט Firebase, מריצים את הפקודה הבאה:

firebase use --add

6. כשמופיעה בקשה, בוחרים את מזהה הפרויקט ומעניקים לפרופקט ב-Firebase כינוי.

כתובת אימייל חלופית שימושית אם יש לכם כמה סביבות (ייצור, Staging וכו'). עם זאת, עבור ה-Codelab הזה, נשתמש רק בכינוי של default.

7. פועלים לפי שאר ההוראות בשורת הפקודה.

5. התקנת AngularFire

לפני הפעלת הפרויקט, צריך לוודא ש-Agular CLI ו-AgularFire מוגדרים.

1. במסוף, מריצים את הפקודה הבאה:

npm install -g @angular/cli

2. לאחר מכן, במסוף מהספרייה angularfire-start, מריצים את הפקודה הבאה של Angular CLI:

ng add @angular/fire

הפעולה הזו תתקין את כל הרכיבים התלויים הנדרשים לפרויקט.

3. כשמופיעה בקשה, מבטלים את הסימון של ng deploy -- hosting באמצעות מקש הרווח. בוחרים את התכונות הבאות באמצעות מקשי החיצים ומקש הרווח:
   • Authentication
   • Firestore
   • Cloud Messaging
   • Cloud Storage
4. לוחצים על enter ופועלים לפי ההנחיות הנותרות.
5. יוצרים השמירה עם הודעת השמירה 'Install AngularFire' ומעבירים אותה למאגר ב-GitHub.

6. יצירת קצה עורפי של אירוח אפליקציות

בקטע הזה תגדירו קצה עורפי של אירוח אפליקציות כדי לעקוב אחרי הסתעפות במאגר ה-Git.

בסוף הקטע הזה תהיה לכם תשתית לקצה העורפי של אירוח אפליקציות שמחוברת למאגר שלכם ב-GitHub, ותבנה מחדש באופן אוטומטי ותשיק גרסה חדשה של האפליקציה בכל פעם שתדחוף התחייבות חדשה להסתעפות main.

1. עוברים אל הדף App Hosting במסוף Firebase:

2. לוחצים על 'תחילת העבודה' כדי להתחיל בתהליך היצירה של הקצה העורפי. מגדירים את הקצה העורפי באופן הבא:
3. פועלים לפי ההנחיות בשלב הראשון כדי לחבר את מאגר GitHub שיצרתם מקודם.
4. קובעים את הגדרות הפריסה:
   1. אני רוצה לשמור את תיקיית השורש בתור /
   2. מגדירים את ההסתעפות הפעילה ל-main
   3. הפעלת השקות אוטומטיות
5. נותנים שם לקצה העורפי friendlychat-codelab.
6. בקטע 'יצירה או שיוך של אפליקציית אינטרנט של Firebase', בוחרים את אפליקציית האינטרנט שהגדרתם קודם לכן מהתפריט הנפתח 'בחירת אפליקציית אינטרנט קיימת של Firebase'.
7. לוחצים על 'סיום ופריסה'. אחרי רגע, תועברו לדף חדש שבו תוכלו לראות את הסטטוס של הקצה העורפי החדש של אירוח האפליקציות.
8. בסיום ההשקה, לוחצים על הדומיין החינמי בקטע 'דומיינים'. יכול להיות שיחלפו כמה דקות עד שהשינוי יתחיל לפעול בגלל הפצת ה-DNS.

פרסתם את אפליקציית האינטרנט הראשונית! בכל פעם שתוסיפו מחויבות חדשה להסתעפות main של המאגר ב-GitHub, תראו התחלה של build חדש והשקה חדשה במסוף Firebase, והאתר יתעדכן באופן אוטומטי בסיום ההשקה.

אמור להופיע מסך הכניסה של אפליקציית PreferredChat. מסך הכניסה (עדיין!) לא פועל.

האפליקציה לא יכולה לעשות שום דבר כרגע, אבל בעזרתכם היא תוכל לעשות זאת בקרוב!

עכשיו נבנה אפליקציית צ'אט בזמן אמת.

7. ייבוא והגדרה של Firebase

הגדרת Firebase

יהיה עליכם להגדיר את Firebase SDK כדי לדעת באיזה פרויקט Firebase אתם משתמשים.

1. עוברים אל Project settings במסוף Firebase.
2. בכרטיס 'האפליקציות שלך', בוחרים את הכינוי של האפליקציה שעבורה צריך אובייקט תצורה.
3. בוחרים באפשרות 'Config' (הגדרה) בחלונית של קטע הקוד של Firebase SDK.

ניתן לראות שנוצר עבורך קובץ סביבה /angularfire-start/src/environments/environment.ts.

4. מעתיקים את קטע הקוד של אובייקט ה-config ומוסיפים אותו אל angularfire-start/src/firebase-config.js.

environment.ts

export const environment = {
  firebase: {
    apiKey: "API_KEY",
    authDomain: "PROJECT_ID.firebaseapp.com",
    projectId: "PROJECT_ID",
    storageBucket: "PROJECT_ID.firebasestorage.app",
    messagingSenderId: "SENDER_ID",
    appId: "APP_ID",
  },
};

הצגת ההגדרה של AngularFire

התכונות שבחרת במסוף נוספו באופן אוטומטי בקובץ /angularfire-start/src/app/app.config.ts. כך האפליקציה יכולה להשתמש בתכונות ובפונקציות של Firebase.

8. הגדרת כניסה של משתמשים

עכשיו AngularFire אמור להיות מוכן לשימוש, כי הוא יובא ויאופס ב-app.config.ts. עכשיו נטמיע כניסה של משתמשים באמצעות אימות ב-Firebase.

הוספת דומיין מורשה

אימות ב-Firebase מאפשר כניסות רק מרשימת דומיינים מוגדרת שבשליטתכם. מוסיפים את הדומיין החינמי שלכם לאירוח אפליקציות לרשימת הדומיינים:

1. עוברים אל אירוח אפליקציות.
2. מעתיקים את הדומיין של הקצה העורפי.
3. עוברים אל הגדרות אימות.
4. בוחרים בכרטיסייה דומיינים מורשים.
5. לוחצים על Add domain (הוספת דומיין) ומדביקים את הדומיין של הקצה העורפי של אירוח האפליקציות.

אימות המשתמשים באמצעות כניסה באמצעות חשבון Google

באפליקציה, כשמשתמש לוחץ על הלחצן כניסה באמצעות חשבון Google, מופעלת הפונקציה login. עבור ה-Codelab הזה, עליך לתת ל-Firebase הרשאה להשתמש ב-Google כספק הזהויות. תשתמשו בחלון קופץ, אבל יש כמה שיטות אחרות שזמינות ב-Firebase.

1. בספריית המשנה /src/app/services/, פותחים את chat.service.ts.
2. מחפשים את הפונקציה login.
3. מחליפים את הפונקציה כולה בקוד הבא.

chat.service.ts

// Signs-in Friendly Chat.
login() {
    signInWithPopup(this.auth, this.provider).then((result) => {
        const credential = GoogleAuthProvider.credentialFromResult(result);
        this.router.navigate(['/', 'chat']);
        return credential;
    })
}

הפונקציה logout מופעלת כשהמשתמש לוחץ על הלחצן Log out (יציאה מהחשבון).

1. חוזרים לקובץ src/app/services/chat.service.ts.
2. מאתרים את הפונקציה logout.
3. מחליפים את הפונקציה כולה בקוד הבא.

chat.service.ts

// Logout of Friendly Chat.
logout() {
    signOut(this.auth).then(() => {
        this.router.navigate(['/', 'login'])
        console.log('signed out');
    }).catch((error) => {
        console.log('sign out error: ' + error);
    })
}

מעקב אחר מצב האימות

כדי לעדכן את ממשק המשתמש שלנו בהתאם, עליך לבדוק אם המשתמש מחובר או לא מחובר. ב-AngularFire יש פונקציה שמאפשרת לקבל אובייקט observable שמתעדכן בכל פעם שסטטוס האימות משתנה. כבר הטמענו את האפשרות הזאת, אבל כדאי לבדוק את זה.

1. חוזרים לקובץ src/app/services/chat.service.ts.
2. מאתרים את הקצאת המשתנים user$.

chat.service.ts

// observable that is updated when the auth state changes
user$ = user(this.auth);

הקוד שלמעלה קורא לפונקציה user של AngularFire שמחזירה משתמש שניתן לצפות בו. האימות יופעל בכל פעם שמצב האימות ישתנה (כשהמשתמש נכנס לחשבון או יוצא ממנו). רכיבי התבניות של Angular ב-FriendlyChat משתמשים באירוע הנצפה הזה כדי לעדכן את ממשק המשתמש להפניה אוטומטית, להציג את המשתמש בתפריט הניווט בכותרת וכו'.

בדיקת ההתחברות לאפליקציה

1. יוצרים השמירה עם הודעת השמירה 'הוספת אימות Google' ומעבירים אותה למאגר ב-GitHub.
2. פותחים את הדף 'אירוח אפליקציות' במסוף Firebase וממתינים להשלמת ההשקה החדשה.
3. באפליקציית האינטרנט, מרעננים את הדף ומתחברים לאפליקציה באמצעות לחצן הכניסה וחשבון Google. אם מופיעה הודעת שגיאה בנוסח auth/operation-not-allowed, צריך לוודא שהפעלתם את 'כניסה באמצעות חשבון Google' כספק אימות במסוף Firebase.
4. אחרי הכניסה לחשבון, אמורים להופיע תמונת הפרופיל ושם המשתמש:

9. כתיבת הודעות ל-Cloud Firestore

בקטע הזה, נכתוב נתונים מסוימים ב-Cloud Firestore כדי שתוכלו לאכלס את ממשק המשתמש של האפליקציה. אפשר לעשות זאת באופן ידני באמצעות מסוף Firebase, אבל כדי להדגים פעולת כתיבה בסיסית ב-Cloud Firestore, נעשה זאת באפליקציה עצמה.

מודל נתונים

הנתונים ב-Cloud Firestore מחולקים לאוספים, למסמכים, לשדות ולאוספים משניים. כל הודעה בצ'אט תישמר כמסמך באוסף ברמה העליונה שנקרא messages.

הוספת הודעות ל-Cloud Firestore

כדי לאחסן את הודעות הצ'אט שנכתבו על ידי משתמשים, צריך להשתמש ב-Cloud Firestore.

בקטע הזה תוסיפו את הפונקציונליות שמאפשרת למשתמשים לכתוב הודעות חדשות במסד הנתונים. משתמש שילחץ על הלחצן שליחה יפעיל את קטע הקוד שלמטה. הפונקציה מוסיפה אובייקט הודעה עם התוכן של שדות ההודעה למכונה שלכם ב-Cloud Firestore באוסף messages. השיטה add() מוסיפה לאוסף מסמך חדש עם מזהה שנוצר באופן אוטומטי.

1. חוזרים לקובץ src/app/services/chat.service.ts.
2. מאתרים את הפונקציה addMessage.
3. מחליפים את הפונקציה כולה בקוד הבא.

chat.service.ts

// Adds a text or image message to Cloud Firestore.
addMessage = async (
  textMessage: string | null,
  imageUrl: string | null,
): Promise<void | DocumentReference<DocumentData>> => {
  // ignore empty messages
  if (!textMessage && !imageUrl) {
    console.log(
      "addMessage was called without a message",
      textMessage,
      imageUrl,
    );
    return;
  }

  if (this.currentUser === null) {
    console.log("addMessage requires a signed-in user");
    return;
  }

  const message: ChatMessage = {
    name: this.currentUser.displayName,
    profilePicUrl: this.currentUser.photoURL,
    timestamp: serverTimestamp(),
    uid: this.currentUser?.uid,
  };

  textMessage && (message.text = textMessage);
  imageUrl && (message.imageUrl = imageUrl);

  try {
    const newMessageRef = await addDoc(
      collection(this.firestore, "messages"),
      message,
    );
    return newMessageRef;
  } catch (error) {
    console.error("Error writing new message to Firebase Database", error);
    return;
  }
};

בדיקה של שליחת הודעות

1. יוצרים השמירה עם הודעת ההסבר 'פרסום צ'אטים חדשים ב-Firestore' ומעבירים אותה למאגר ב-GitHub.
2. פותחים את הדף App Hosting במסוף Firebase וממתינים להשלמת ההשקה החדשה.
3. מרעננים את FriendlyChat. אחרי הכניסה לחשבון, מזינים הודעה כמו 'היי!' ולוחצים על שליחה. הפעולה הזו תכתוב את ההודעה ב-Cloud Firestore. עם זאת, עדיין לא תראו את הנתונים באפליקציית האינטרנט בפועל, כי עדיין צריך להטמיע את אחזור הנתונים (הקטע הבא בקודלאב).
4. ההודעה החדשה תופיע במסוף Firebase. פותחים את ממשק המשתמש של חבילת האמולטור. בקטע Build, לוחצים על Firestore Database (או לוחצים כאן). האוסף messages עם ההודעה החדשה שהוספתם אמור להופיע:

10. קריאת ההודעות

סנכרון הודעות

כדי לקרוא הודעות באפליקציה, צריך להוסיף אובייקט גלוי שיופעל כשהנתונים משתנים, ולאחר מכן ליצור רכיב בממשק המשתמש שמציג הודעות חדשות.

תוסיפו קוד שמקשיב להודעות חדשות שנוספו מהאפליקציה. בקוד הזה תשלפו את קובץ snapshot של האוסף messages. יוצגו רק 12 ההודעות האחרונות בצ'אט כדי למנוע הצגת היסטוריה ארוכה מאוד בזמן הטעינה.

1. חוזרים לקובץ src/app/services/chat.service.ts.
2. מאתרים את הפונקציה loadMessages.
3. מחליפים את הפונקציה כולה בקוד הבא.

chat.service.ts

// Loads chat message history and listens for upcoming ones.
loadMessages = () => {
  // Create the query to load the last 12 messages and listen for new ones.
  const recentMessagesQuery = query(collection(this.firestore, 'messages'), orderBy('timestamp', 'desc'), limit(12));
  // Start listening to the query.
  return collectionData(recentMessagesQuery);
}

כדי להאזין להודעות במסד הנתונים, יוצרים שאילתה באוסף באמצעות הפונקציה collection, שמציינת באיזה אוסף נתונים רוצים להאזין. בקוד שלמעלה, אתם מקשיב לשינויים באוסף messages, שבו מאוחסנות הודעות הצ'אט. בנוסף, קיימת מגבלה על ידי האזנה ל-12 ההודעות האחרונות בלבד באמצעות limit(12) וסידור ההודעות לפי תאריך באמצעות orderBy('timestamp', 'desc') כדי לקבל את 12 ההודעות החדשות ביותר.

בפונקציה collectionData נעשה שימוש בתמונות מצב (snapshots) ברקע. פונקציית הקריאה החוזרת תופעל כשיהיו שינויים במסמכים שתואמים לשאילתה. למשל, אם הודעה נמחקת, משתנה או מתווספת. מידע נוסף בנושא זמין במסמכי התיעוד של Cloud Firestore.

בדיקת סנכרון הודעות

1. יוצרים השמירה עם הודעת השמירה 'הצגת צ'אטים חדשים בממשק המשתמש' ומעבירים אותה למאגר ב-GitHub.
2. פותחים את הדף App Hosting במסוף Firebase וממתינים להשלמת ההשקה החדשה.
3. רענון של WonderChat. ההודעות שיצרתם קודם לכן במסד הנתונים אמורות להופיע בממשק המשתמש של FriendlyChat (ראו בהמשך). אפשר לכתוב הודעות חדשות באופן מיידי – הן אמורות להופיע מיידית.
4. (אופציונלי) אפשר לנסות למחוק, לשנות או להוסיף הודעות חדשות באופן ידני ישירות בקטע Firestore בחבילת ה-Emulator. השינויים אמורים להופיע בממשק המשתמש.

כל הכבוד! בחרת לקרוא את המסמכים של Cloud Firestore באפליקציה שלך!

11. הוספת תכונות מבוססות-AI

אתם יכולים להשתמש ב-AI מבית Google כדי להוסיף לאפליקציית Chat תכונות מסייעות.

קבלת מפתח API של Google AI

1. עוברים אל Google AI Studio ולוחצים על יצירת מפתח API.
2. צריך לבחור את פרויקט Firebase שיצרתם בשביל ה-Codelab הזה. ההנחיה מתייחסת לפרויקט ב-Google Cloud, אבל כל פרויקט ב-Firebase הוא פרויקט ב-Google Cloud.
3. לוחצים על Create API key in existing project.
4. מעתיקים את מפתח ה-API שנוצר

התקנה של תוסף

התוסף הזה פורס פונקציית Cloud שתופעל בכל פעם שמתווסף מסמך חדש לאוסף messages ב-Firestore. הפונקציה תפעיל קריאה ל-Gemini ותכתוב את התשובה שלה בשדה response במסמך.

1. לוחצים על Install in Firebase console (התקנה במסוף Firebase) בדף התוסף Build Chatbot with the Gemini API (פיתוח צ'אטבוט באמצעות Gemini API).
2. פועלים לפי ההנחיות. כשמגיעים לשלב הגדרת התוסף, מגדירים את ערכי הפרמטרים הבאים:
   • ספק Gemini API: Google AI
   • מפתח Google AI API: מדביקים את המפתח שיצרתם קודם ולוחצים על Create secret.
   • נתיב האיסוף של Firestore: messages
   • שדה ההנחיה: text
   • שדה התגובה: response
   • שדה ההזמנה: timestamp
   • הקשר: Keep your answers short, informal, and helpful. Use emojis when possible.
3. לוחצים על התקנת התוסף.
4. ממתינים לסיום ההתקנה של התוסף.

בדיקת תכונה מבוססת-AI

ב-FriendlyChat כבר יש קוד לקריאת תשובות מתוסף ה-AI. כל מה שצריך לעשות הוא לשלוח הודעה חדשה בצ'אט כדי לבדוק את זה.

1. פותחים את WonderChat ושולחים הודעה.
2. אחרי רגע, אתם אמורים לראות תגובה קופצת לצד ההודעה. בסוף התיאור מופיעה ההערה ✨ ai generated כדי להבהיר שהוא נוצר באמצעות AI גנרטיבי, ולא על ידי משתמש אמיתי.

12. שליחת תמונות

עכשיו נוסיף תכונה לשיתוף תמונות.

Cloud Firestore מתאים לאחסון נתונים מובְנים, אבל Cloud Storage מתאים יותר לאחסון קבצים. Cloud Storage for Firebase הוא שירות לאחסון קבצים או blob ואפשר להשתמש בו כדי לשמור תמונות שהמשתמש משתף באמצעות האפליקציה שלנו.

שמירת תמונות ב-Cloud Storage

ב-Codelab הזה כבר הוספת לחצן שמפעיל תיבת דו-שיח לבחירת קבצים. אחרי שבוחרים קובץ, מתבצעת קריאה לפונקציה saveImageMessage ואפשר לקבל הפניה לקובץ שנבחר. הפונקציה saveImageMessage מבצעת את הפעולות הבאות:

1. יוצר הודעת צ'אט מסוג 'placeholder' בפיד הצ'אט, כדי שהמשתמשים יראו אנימציה של 'נטען' בזמן העלאת התמונה.
2. מעלה את קובץ התמונה ל-Cloud Storage לנתיב הזה: /<uid>/<file_name>
3. יוצרת כתובת URL של קובץ התמונה שגלויה לכולם.
4. המערכת מעדכנת את הודעת הצ'אט בכתובת ה-URL של קובץ התמונה החדש שהועלה, במקום בתמונת הטעינה הזמנית.

בשלב הזה תוסיפו את האפשרות לשליחת תמונות:

1. חוזרים לקובץ src/chat.service.ts.
2. מחפשים את הפונקציה saveImageMessage.
3. מחליפים את כל הפונקציה בקוד הבא.

chat.service.ts

// Saves a new message containing an image in Firestore.
// This first saves the image in Firebase storage.
saveImageMessage = async(file: any) => {
  try {
    // 1 - Add a message with a loading icon that will get updated with the shared image.
    const messageRef = await this.addMessage(null, this.LOADING_IMAGE_URL);

    // 2 - Upload the image to Cloud Storage.
    const filePath = `${this.auth.currentUser?.uid}/${file.name}`;
    const newImageRef = ref(this.storage, filePath);
    const fileSnapshot = await uploadBytesResumable(newImageRef, file);

    // 3 - Generate a public URL for the file.
    const publicImageUrl = await getDownloadURL(newImageRef);

    // 4 - Update the chat message placeholder with the image's URL.
    messageRef ?
    await updateDoc(messageRef, {
      imageUrl: publicImageUrl,
      storageUri: fileSnapshot.metadata.fullPath
    }): null;
  } catch (error) {
    console.error('There was an error uploading a file to Cloud Storage:', error);
  }
}

בדיקת שליחת תמונות

1. יוצרים התחייבות באמצעות ההודעה "Add the option to post images" (הוספת האפשרות לפרסם תמונות) ודוחפים אותה למאגר ב-GitHub.
2. פותחים את הדף 'אירוח אפליקציות' במסוף Firebase וממתינים להשלמת ההשקה החדשה.
3. רענון של WonderChat. אחרי הכניסה לחשבון, לוחצים על לחצן העלאת התמונה בפינה הימנית התחתונה ובוחרים קובץ תמונה באמצעות בורר הקבצים. אם אתם מחפשים תמונה, אתם מוזמנים להשתמש בתמונה הנחמדה הזו של ספל קפה.
4. הודעה חדשה אמורה להופיע בממשק המשתמש של האפליקציה עם התמונה שבחרת:

אם תנסו להוסיף תמונה כשאתם לא מחוברים לחשבון, אמורה להופיע הודעת שגיאה שאומרת שעליכם להיכנס לחשבון כדי להוסיף תמונות.

13. Show notifications – הצגת ההתראות

עכשיו תוסיפו תמיכה בהתראות בדפדפן. האפליקציה תודיע למשתמשים כשיפורסמו הודעות חדשות בצ'אט. Firebase Cloud Messaging‏ (FCM) הוא פתרון להעברת הודעות בפלטפורמות שונות, שמאפשר לשלוח הודעות והתראות בצורה מהימנה ללא עלות.

הוספת קובץ השירות (service worker) של FCM

לאפליקציית האינטרנט צריך להיות קובץ שירות (service worker) שיקבל ויציג התראות מהאינטרנט.

ספק העברת ההודעות היה אמור להיות מוגדר כשהוספת את AngularFire. צריך לוודא שהקוד הבא קיים בקטע הייבוא של /angularfire-start/src/app/app.config.ts

provideMessaging(() => {
    return getMessaging();
}),

app/app.config.ts

ה-Service Worker צריך לטעון ולהפעיל את ה-SDK של העברת הודעות בענן ב-Firebase כדי להציג את ההתראות.

איך מקבלים אסימוני מכשיר של FCM

אחרי שהפעלתם התראות במכשיר או בדפדפן, תקבלו אסימון מכשיר. טוקן המכשיר הזה משמש לשליחת התראה למכשיר מסוים או לדפדפן מסוים.

כשהמשתמש נכנס לחשבון, קוראים לפונקציה saveMessagingDeviceToken. כאן תקבל את אסימון המכשיר של FCM מהדפדפן, ותשמור אותו ב-Cloud Firestore.

chat.service.ts

2. מחפשים את הפונקציה saveMessagingDeviceToken.
3. מחליפים את הפונקציה כולה בקוד הבא.

chat.service.ts

// Saves the messaging device token to Cloud Firestore.
saveMessagingDeviceToken= async () => {
    try {
      const currentToken = await getToken(this.messaging);
      if (currentToken) {
        console.log('Got FCM device token:', currentToken);
        // Saving the Device Token to Cloud Firestore.
        const tokenRef = doc(this.firestore, 'fcmTokens', currentToken);
        await setDoc(tokenRef, { uid: this.auth.currentUser?.uid });
 
        // This will fire when a message is received while the app is in the foreground.
        // When the app is in the background, firebase-messaging-sw.js will receive the message instead.
        onMessage(this.messaging, (message) => {
          console.log(
            'New foreground notification from Firebase Messaging!',
            message.notification
          );
        });
      } else {
        // Need to request permissions to show notifications.
        this.requestNotificationsPermissions();
      }
    } catch(error) {
      console.error('Unable to get messaging token.', error);
    };
}

עם זאת, הקוד הזה לא יפעל בהתחלה. כדי שהאפליקציה תוכל לאחזר את אסימון המכשיר, המשתמש צריך להעניק לאפליקציה הרשאה להציג התראות (השלב הבא ב-Codelab).

בקשת הרשאות להצגת התראות

אם המשתמש עדיין לא העניק לאפליקציה הרשאה להציג התראות, לא תקבלו אסימון מכשיר. במקרה כזה, קוראים ל-method requestPermission(), כדי להציג תיבת דו-שיח של הדפדפן שמבקשת את ההרשאה הזו ( בדפדפנים נתמכים).

1. חוזרים לקובץ src/app/services/chat.service.ts.
2. מאתרים את הפונקציה requestNotificationsPermissions.
3. מחליפים את הפונקציה כולה בקוד הבא.

chat.service.ts

// Requests permissions to show notifications.
requestNotificationsPermissions = async () => {
    console.log('Requesting notifications permission...');
    const permission = await Notification.requestPermission();
    
    if (permission === 'granted') {
      console.log('Notification permission granted.');
      // Notification permission granted.
      await this.saveMessagingDeviceToken();
    } else {
      console.log('Unable to get permission to notify.');
    }
}

איך מקבלים אסימון מכשיר

1. יוצרים השמירה עם הודעת השמירה 'הוספת היכולת לפרסם תמונות' ומעבירים אותה למאגר ב-GitHub.
2. פותחים את הדף App Hosting במסוף Firebase וממתינים להשלמת ההשקה החדשה.
3. רענון של WonderChat. אחרי ההתחברות, אמורה להופיע תיבת הדו-שיח של הרשאת ההתראות:
4. לוחצים על אישור.
5. פותחים את לוח JavaScript בדפדפן. ההודעה הבאה אמורה להופיע: Got FCM device token: cWL6w:APA91bHP...4jDPL_A-wPP06GJp1OuekTaTZI5K2Tu
6. מעתיקים את האסימון של המכשיר. תצטרכו אותו בשלב הבא של סדנת הקוד.

שליחת התראה למכשיר

עכשיו, אחרי שקיבלתם את אסימון המכשיר, אתם יכולים לשלוח התראה.

1. פותחים את הכרטיסייה Cloud Messaging במסוף Firebase.
2. לוחצים על 'התראה חדשה'.
3. מזינים כותרת להתראה וטקסט להודעה.
4. בצד שמאל של המסך, לוחצים על 'שליחת הודעת בדיקה'.
5. מזינים את אסימון המכשיר שהעתקתם מלוח JavaScript של הדפדפן ואז לוחצים על סימן הפלוס ("+")
6. לוחצים על 'בדיקה'

אם האפליקציה נמצאת בחזית, ההודעה תופיע במסוף JavaScript.

אם האפליקציה פועלת ברקע, אמורה להופיע התראה בדפדפן, כמו בדוגמה הבאה:

14. כללי אבטחה של Cloud Firestore

הצגת כללי אבטחה של מסד נתונים

ב-Cloud Firestore נעשה שימוש בשפת כללים ספציפית כדי להגדיר הרשאות גישה, אבטחה ואימות נתונים.

כשהגדרתם את פרויקט Firebase בתחילת הקודלאב, בחרתם להשתמש בכללי האבטחה שמוגדרים כברירת מחדל ב'מצב בדיקה' כדי שלא להגביל את הגישה למאגר הנתונים. במסוף Firebase, בכרטיסייה כללים שבקטע מסד נתונים, אפשר לראות ולשנות את הכללים האלה.

בשלב הזה אמורים להופיע כללי ברירת המחדל, שלא מגבילים את הגישה למאגר הנתונים. המשמעות היא שכל משתמש יכול לקרוא ולכתוב בכל אוספים במאגר הנתונים שלכם.

rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write;
    }
  }
}

מעדכנים את הכללים כדי להגביל דברים באמצעות הכללים הבאים:

firestore.כללים

rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {
    // Messages:
    //   - Anyone can read.
    //   - Authenticated users can add and edit messages.
    //   - Validation: Check name is same as auth token and text length below 300 char or that imageUrl is a URL.
    //   - Deletes are not allowed.
    match /messages/{messageId} {
      allow read;
      allow create, update: if request.auth != null
                    && request.resource.data.name == request.auth.token.name
                    && (request.resource.data.text is string
                      && request.resource.data.text.size() <= 300
                      || request.resource.data.imageUrl is string
                      && request.resource.data.imageUrl.matches('https?://.*'));
      allow delete: if false;
    }
    // FCM Tokens:
    //   - Anyone can write their token.
    //   - Reading list of tokens is not allowed.
    match /fcmTokens/{token} {
      allow read: if false;
      allow write;
    }
  }
}

כללי האבטחה אמורים להתעדכן באופן אוטומטי בחבילת ה-Emulator.

הצגת כללי האבטחה של Cloud Storage

ב-Cloud Storage for Firebase נעשה שימוש בשפת כללים ספציפית כדי להגדיר את הרשאות הגישה, האבטחה ואימות הנתונים.

כשהגדרתם את פרויקט Firebase בתחילת הקודלה הזו, בחרתם להשתמש בכלל האבטחה שמוגדר כברירת מחדל ב-Cloud Storage, שמאפשר רק למשתמשים מאומתים להשתמש ב-Cloud Storage. במסוף Firebase, אפשר לראות ולשנות את הכללים, בקטע אחסון בכרטיסייה כללים. אמור להופיע כלל ברירת המחדל שמאפשר לכל משתמש שמחובר לחשבון לקרוא ולכתוב קבצים בקטגוריית האחסון.

rules_version = '2';

service firebase.storage {
  match /b/{bucket}/o {
    match /{allPaths=**} {
      allow read, write: if request.auth != null;
    }
  }
}

מעדכנים את הכללים כך:

• לאפשר לכל משתמש לכתוב רק בתיקיות הספציפיות שלו
• מתן הרשאת קריאה לכולם ב-Cloud Storage
• חשוב לוודא שהקבצים שהועלו הם תמונות
• צריך להגביל את הגודל של התמונות שאפשר להעלות ל-5MB לכל היותר

אפשר ליישם את זה לפי הכללים הבאים:

storage.כללים

rules_version = '2';

// Returns true if the uploaded file is an image and its size is below the given number of MB.
function isImageBelowMaxSize(maxSizeMB) {
  return request.resource.size < maxSizeMB * 1024 * 1024
      && request.resource.contentType.matches('image/.*');
}

service firebase.storage {
  match /b/{bucket}/o {
    match /{userId}/{messageId}/{fileName} {
      allow write: if request.auth != null && request.auth.uid == userId && isImageBelowMaxSize(5);
      allow read;
    }
  }
}

15. כל הכבוד!

השתמשתם ב-Firebase כדי ליצור אפליקציית אינטרנט לצ'אט בזמן אמת!

מה נכלל?

• Firebase App Hosting
• אימות ב-Firebase
• Cloud Firestore
• Firebase SDK ל-Cloud Storage
• העברת הודעות בענן ב-Firebase
• מעקב אחר ביצועים ב-Firebase

השלבים הבאים

מידע נוסף

• firebase.google.com

16. [אופציונלי] אכיפה באמצעות בדיקת אפליקציה

בדיקת אפליקציות ב-Firebase עוזרת לאבטח את השירותים שלכם מפני תנועה לא רצויה ולהגן על הקצה העורפי שלכם מפני ניצול לרעה. בשלב הזה, תוסיפו אימות של פרטי הכניסה ותחסום לקוחות לא מורשים באמצעות App Check ו-reCAPTCHA Enterprise.

קודם כול, צריך להפעיל את App Check ואת reCaptcha.

הפעלת reCaptcha Enterprise

1. במסוף Cloud, מחפשים את reCaptcha Enterprise בקטע Security ובוחרים בו.
2. מפעילים את השירות לפי ההנחיה ולוחצים על Create Key.
3. מזינים שם לתצוגה כשמופיעה ההודעה הרלוונטית ובוחרים באפשרות אתר כסוג הפלטפורמה.
4. מוסיפים את כתובות ה-URL שנפרסו לרשימת הדומיינים, ומוודאים שהאפשרות 'שימוש באתגר של תיבת סימון' לא מסומנת.
5. לוחצים על Create Key (יצירת מפתח) ומאחסנים את המפתח שנוצר במקום מסוים כדי לשמור עליו. תצטרכו אותו בהמשך השלב הזה.

הפעלת בדיקת אפליקציה

1. במסוף Firebase, מאתרים את הקטע Build בחלונית השמאלית.
2. לוחצים על בדיקת האפליקציה ואז על הכרטיסייה שיטת הכניסה כדי לעבור אל בדיקת האפליקציה.
3. לוחצים על Register (רישום) ומזינים את המפתח של reCaptcha Enterprise כשמופיעה בקשה לעשות זאת, ואז לוחצים על Save (שמירה).
4. בתצוגת ממשקי ה-API, בוחרים באפשרות אחסון ולוחצים על אכיפה. חוזרים על הפעולה עבור Cloud Firestore.

יש לאכוף עכשיו את בדיקת האפליקציה! מרעננים את האפליקציה ומנסים להציג או לשלוח את ההודעות בצ'אט. הודעת השגיאה אמורה להופיע:

Uncaught Error in snapshot listener: FirebaseError: [code=permission-denied]: Missing or insufficient permissions.

המשמעות היא שבדיקת האפליקציה חוסמת בקשות לא מאומתות כברירת מחדל. עכשיו נוסיף אימות לאפליקציה.

עוברים לקובץ environment.ts ומוסיפים את reCAPTCHAEnterpriseKey לאובייקט environment.

export const environment = {
  firebase: {
    apiKey: 'API_KEY',
    authDomain: 'PROJECT_ID.firebaseapp.com',
    databaseURL: 'https://PROJECT_ID.firebaseio.com',
    projectId: 'PROJECT_ID',
    storageBucket: 'PROJECT_ID.firebasestorage.app',
    messagingSenderId: 'SENDER_ID',
    appId: 'APP_ID',
    measurementId: 'G-MEASUREMENT_ID',
  },
  reCAPTCHAEnterpriseKey: {
    key: "Replace with your recaptcha enterprise site key"
  },
};

מחליפים את הערך של key באסימון של reCaptcha Enterprise.

לאחר מכן, עוברים לקובץ app.config.ts ומוסיפים את הייבוא הבא:

import { getApp } from '@angular/fire/app';
import {
  ReCaptchaEnterpriseProvider,
  initializeAppCheck,
  provideAppCheck,
} from '@angular/fire/app-check';

באותו קובץ app.config.ts, מוסיפים את ההצהרה הבאה לגבי משתנים גלובליים:

declare global {
  var FIREBASE_APPCHECK_DEBUG_TOKEN: boolean;
}

@NgModule({ ...

בייבוא, מוסיפים את האימפולס של בדיקת האפליקציה באמצעות ReCaptchaEnterpriseProvider, ומגדירים את isTokenAutoRefreshEnabled כ-true כדי לאפשר לאסימונים להתעדכן באופן אוטומטי.

imports: [
BrowserModule,
AppRoutingModule,
CommonModule,
FormsModule,
provideFirebaseApp(() => initializeApp(environment.firebase)),
provideAppCheck(() => {
const appCheck = initializeAppCheck(getApp(), {
  provider: new ReCaptchaEnterpriseProvider(
  environment.reCAPTCHAEnterpriseKey.key
  ),
  isTokenAutoRefreshEnabled: true,
  });
  if (location.hostname === 'localhost') {
    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
  }
  return appCheck;
}),

כדי לאפשר בדיקה מקומית, מגדירים את self.FIREBASE_APPCHECK_DEBUG_TOKEN כ-true. אחרי רענון האפליקציה ב-localhost, יירשם אסימון לניפוי באגים במסוף באופן דומה לזה:

App Check debug token: CEFC0C76-7891-494B-B764-349BDFD00D00. You will need to add it to your app's App Check settings in the Firebase console for it to work.

עכשיו עוברים אל תצוגת האפליקציות של App Check במסוף Firebase.

לוחצים על 'אפשרויות נוספות' ובוחרים באפשרות ניהול אסימוני ניפוי באגים.

לאחר מכן, לוחצים על הוספת אסימון לניפוי באגים ומדביקים את האסימון לניפוי באגים מהמסוף לפי ההוראות.

עוברים לקובץ chat.service.ts ומוסיפים את הייבוא הבא:

import { AppCheck } from '@angular/fire/app-check';

באותו קובץ chat.service.ts, מוסיפים את התכונה 'בדיקת אפליקציות' לצד השירותים האחרים של Firebase.

export class ChatService {
appCheck: AppCheck = inject(AppCheck);
...

1. יוצרים השמירה עם הודעת השמירה 'חסימת לקוחות לא מורשים באמצעות App Check' ומעבירים אותה למאגר ב-GitHub.
2. פותחים את הדף 'אירוח אפליקציות' במסוף Firebase וממתינים להשלמת ההשקה החדשה.

כל הכבוד! עכשיו App Check אמור לפעול באפליקציה.