תגובות מדיה מאפשרות לכם להפעיל תוכן אודיו בפעולות שמשך ההפעלה שלהן ארוך יותר מהמגבלה של 240 שניות ל-SSML. תגובות המדיה פועלות גם במכשירים עם אודיו בלבד וגם במכשירים עם אפשרות להציג תוכן חזותי. במסכים, התגובות למדיה מלוות ברכיב חזותי עם פקדי מדיה ועם (אופציונלי) בתמונת סטילס.
כשמגדירים תגובת מדיה, צריך להשתמש במועמד עם יכולות השטח RICH_RESPONSE
וגם LONG_FORM_AUDIO
, כך ש-Google Assistant תחזיר את התגובה העשירה רק במכשירים נתמכים. בהנחיה אפשר להשתמש רק בתגובה עשירה אחת לכל אובייקט content
.
האודיו להפעלה חייב להיות בקובץ MP3 בפורמט תקין. קובצי MP3 חייבים להתארח בשרת אינטרנט, ולהיות זמינים לציבור דרך כתובת URL מסוג HTTPS. אפשר לשדר סטרימינג בשידור חי רק בפורמט MP3.
התנהגות
הרכיב העיקרי בתגובה למדיה הוא כרטיס הטראק היחיד. הכרטיס מאפשר למשתמש לבצע את הפעולות הבאות:
- הפעלה מחדש של 10 השניות האחרונות
- דילוג קדימה 30 שניות
- הצגת האורך הכולל של תוכן המדיה
- הצגת אינדיקטור התקדמות של הפעלת מדיה
- הצגת זמן ההפעלה שחלף
אפשר להשתמש בתגובות המדיה באמצעות פקדי האודיו הבאים לאינטראקציות קוליות. Google Assistant מטפלת בכולם:
- "Ok Google, play"
- "Ok Google, paused. "
- "Ok Google, stop"
- "Ok Google, start מחדש".
המשתמשים יכולים גם לשלוט בעוצמת הקול על ידי אמירת משפטים כמו "Ok Google, turn the volume up" או "Ok Google, set the volume to 50percent". לאובייקטים של Intent בפעולה יש עדיפות אם הם מטפלים בביטויי אימון דומים. אפשר ל-Assistant לטפל בבקשות המשתמשים האלה, אלא אם יש לפעולה סיבה ספציפית לעשות זאת.
ההתנהגות בטלפונים עם Android
בטלפונים עם Android, בקרי מדיה זמינים גם כשהטלפון נעול. גם פקדי המדיה מופיעים באזור ההודעות, והמשתמשים יכולים לראות תגובות למדיה בכל אחד מהתנאים הבאים:
- Google Assistant פועלת בחזית ומסך הטלפון פועל.
- המשתמש עוזב את Google Assistant בזמן שהאודיו מושמע וחוזר ל-Google Assistant תוך 10 דקות מסיום ההפעלה. כשהמשתמש חוזר ל-Google Assistant, הוא רואה את כרטיס המדיה ואת הצ'יפים של ההצעות.
תכונות
לתגובות מדיה יש את המאפיינים הבאים:
נכס | תיאור | דרישה | התיאור |
---|---|---|---|
media_type |
MediaType |
נדרש | סוג המדיה של התשובה שסופקה. החזרת MEDIA_STATUS_ACK
באישור סטטוס מדיה. |
start_offset |
מחרוזת | אופציונלי | צריך לחפש מיקום כדי להתחיל את הטראק הראשון של המדיה. צריך לציין את הערך בשניות, עם שברים עשרוניים המבוטאים לא יותר מתשע ספרות אחרי הנקודה העשרונית. את הערך הזה צריך להסתיים בסיומת "s". לדוגמה, 3 שניות וננו-שנייה אחת מבטאים את הערך "3.000000001s". |
optional_media_controls |
מערך של OptionalMediaControls |
אופציונלי | נכס שיש לו הסכמה לקבלת קריאות חוזרות (callback) כשמשתמש משנה את סטטוס ההפעלה של המדיה (למשל, באמצעות השהיה או הפסקה של הפעלת המדיה). |
media_objects |
מערך של MediaObject |
נדרש | מייצג את האובייקטים של המדיה שצריך לכלול בהנחיה. כשמאשרים סטטוס מדיה באמצעות MEDIA_STATUS_ACK , אין לספק אובייקטים של מדיה. |
first_media_object_index |
מספר שלם | אופציונלי | אינדקס מבוסס-0 של MediaObject הראשונים במשחק
media_objects . אם לא צוין, אפס או מחוץ לתחום,
ההפעלה תתחיל ב-MediaObject הראשון.
|
repeat_mode |
RepeatMode |
אופציונלי | מצב חזרה על רשימת האובייקטים של המדיה. |
קוד לדוגמה
YAML
candidates: - first_simple: variants: - speech: This is a media response. content: media: start_offset: 2.12345s optional_media_controls: - PAUSED - STOPPED media_objects: - name: Media name description: Media description url: 'https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3' image: large: url: 'https://storage.googleapis.com/automotive-media/album_art.jpg' alt: Jazz in Paris album art media_type: AUDIO
JSON
{ "candidates": [ { "first_simple": { "variants": [ { "speech": "This is a media response." } ] }, "content": { "media": { "start_offset": "2.12345s", "optional_media_controls": [ "PAUSED", "STOPPED" ], "media_objects": [ { "name": "Media name", "description": "Media description", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Jazz in Paris album art" } } } ], "media_type": "AUDIO" } } } ] }
Node.js
// Media response app.handle('media', (conv) => { conv.add('This is a media response'); conv.add(new Media({ mediaObjects: [ { name: 'Media name', description: 'Media description', url: 'https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3', image: { large: JAZZ_IN_PARIS_IMAGE, } } ], mediaType: 'AUDIO', optionalMediaControls: ['PAUSED', 'STOPPED'], startOffset: '2.12345s' })); });
JSON
{ "session": { "id": "session_id", "params": {}, "languageCode": "" }, "prompt": { "override": false, "content": { "media": { "mediaObjects": [ { "name": "Media name", "description": "Media description", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "alt": "Jazz in Paris album art", "height": 0, "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "width": 0 } } } ], "mediaType": "AUDIO", "optionalMediaControls": [ "PAUSED", "STOPPED" ] } }, "firstSimple": { "speech": "This is a media response", "text": "This is a media response" } } }
מתקבלת סטטוס מדיה
במהלך הפעלה של מדיה אצל משתמש או אחריה, Google Assistant יכולה ליצור אירועים של סטטוס מדיה כדי ליידע את הפעולה לגבי התקדמות ההפעלה. צריך לטפל באירועי הסטטוס האלה בקוד של התגובה לפעולה מאתר אחר (webhook) כדי לנתב את המשתמשים בצורה נכונה כשהם מושהים, מפסיקים או מסיימים את ההפעלה של המדיה.
Google Assistant מחזירה אירוע סטטוס מהרשימה הבאה על סמך התקדמות ההפעלה של מדיה ושאילתות של משתמשים:
FINISHED
: המשתמש השלים את הפעלת המדיה (או מדלג לקטע המדיה הבא) והמעבר הוא לא ליציאה משיחה. הסטטוס הזה ממופה גם ל-Intent המערכתMEDIA_STATUS_FINISHED
.PAUSED
: המשתמש השהה את הפעלת המדיה. צריך להביע הסכמה לקבלת אירוע הסטטוס הזה עם הנכסoptional_media_controls
. הסטטוס הזה ממופה גם ל-Intent המערכתMEDIA_STATUS_PAUSED
.STOPPED
: המשתמש הפסיק או יצא מהפעלת המדיה. יש להביע הסכמה לקבלת אירוע הסטטוס הזה עם הנכסoptional_media_controls
. הסטטוס הזה ממופה גם ל-Intent המערכת שלMEDIA_STATUS_STOPPED
.FAILED
: הפעלת המדיה נכשלה. הסטטוס הזה ממופה גם ל-Intent המערכתMEDIA_STATUS_FAILED
.
במהלך הפעלה של מדיה, משתמש עשוי לספק שאילתה שיכולה להתפרש גם כאירוע השהיה של מדיה וגם כאירוע הפסקה (כגון 'עצירה', 'ביטול' או 'יציאה'). במקרה כזה, Assistant מספקת את הכוונה של המערכת actions.intent.CANCEL
לפעולה
שלך, יוצרת אירוע של סטטוס מדיה עם ערך הסטטוס "STOPPED" ויוצאת
מהפעולה לחלוטין.
כש-Assistant יוצרת אירוע של סטטוס מדיה עם ערך הסטטוס PAUSED
או STOPPED
, צריך להגיב בתגובת מדיה שמכילה רק אישור (מהסוג MEDIA_STATUS_ACK
).
התקדמות המדיה
ההתקדמות הנוכחית של הפעלת המדיה זמינה בשדה context.media.progress
בבקשות webhook. אפשר להשתמש בהתקדמות של המדיה כקיזוז של שעת התחלה כדי להמשיך את ההפעלה בנקודה שבה הסתיימה הפעלת המדיה. כדי להחיל את ההיסט של שעת ההתחלה על תגובת מדיה, צריך להשתמש במאפיין start_offset
.
קוד לדוגמה
Node.js
// Media status app.handle('media_status', (conv) => { const mediaStatus = conv.intent.params.MEDIA_STATUS.resolved; switch(mediaStatus) { case 'FINISHED': conv.add('Media has finished playing.'); break; case 'FAILED': conv.add('Media has failed.'); break; case 'PAUSED' || 'STOPPED': if (conv.request.context) { // Persist the media progress value const progress = conv.request.context.media.progress; } // Acknowledge pause/stop conv.add(new Media({ mediaType: 'MEDIA_STATUS_ACK' })); break; default: conv.add('Unknown media status received.'); } });
החזרת פלייליסט
אתם יכולים להוסיף יותר מקובץ אודיו אחד בתגובה כדי ליצור פלייליסט. בסיום השמעת הטראק הראשון, הטראק הבא מופעל אוטומטית, וזה ממשיך עד להשמעת כל טראק. המשתמשים יכולים גם ללחוץ על הלחצן Next במסך, או לומר "Next" או מילה דומה כדי לדלג לטראק הבא.
הלחצן הבא מושבת בטראק האחרון של הפלייליסט. עם זאת, אם מפעילים מצב לולאה, הפלייליסט יתחיל שוב מהטראק הראשון. מידע נוסף על מצב לולאה זמין במאמר הטמעה של מצב לולאה.
כדי ליצור פלייליסט, צריך לכלול יותר מערך MediaObject
אחד במערך media_objects
. קטע הקוד הבא מציג הנחיה שמחזירה פלייליסט של שלושה טראקים:
{ "candidates": [ { "content": { "media": { "media_objects": [ { "name": "1. Jazz in Paris", "description": "Song 1 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } }, { "name": "2. Jazz in Paris", "description": "Song 2 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } }, { "name": "3. Jazz in Paris", "description": "Song 3 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } } ], } } } ] }
הטמעה של מצב לולאה
מצב לולאה מאפשר להשמיע תגובת אודיו שחוזרת באופן אוטומטי. במצב הזה אפשר לחזור על טראק אחד או להפעיל פלייליסט בלופ. אם המשתמש אומר "Next" או משהו דומה לטראק יחיד בלופ, השיר מתחיל שוב. בפלייליסטים בלופ, משתמש שאומר "Next" מתחיל את הטראק הבא בפלייליסט.
כדי להטמיע את מצב לולאה, מוסיפים את השדה repeat_mode
להנחיה ומגדירים את הערך ALL
. התוספת הזו מאפשרת לתגובת המדיה להופיע בלולאה לתחילת אובייקט המדיה הראשון, כשמגיעים לסוף אובייקט המדיה האחרון.
קטע הקוד הבא מציג הנחיה שמחזירה רצועה שחוזרת על עצמה:
{ "candidates": [ { "content": { "media": { "media_objects": [ { "name": "Jazz in Paris", "description": "Single song (repeated)", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } } ], "repeat_mode": "ALL" } } } ] }