תגובות מדיה

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

כשמגדירים תגובת מדיה, צריך להשתמש במועמד עם יכולות השטח RICH_RESPONSE וגם LONG_FORM_AUDIO, כך ש-Google Assistant תחזיר את התגובה העשירה רק במכשירים נתמכים. בהנחיה אפשר להשתמש רק בתגובה עשירה אחת לכל אובייקט content.

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

דוגמה לתגובת מדיה במסך חכם
איור 1. דוגמה לתגובת מדיה במסך חכם

התנהגות

דוגמה לתגובת מדיה בסמארטפון
איור 2. דוגמה לתגובת מדיה בסמארטפון

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

  • הפעלה מחדש של 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"
        }
      }
    }
  ]
}