תוכלו להכניס, לעדכן, לקרוא ולמחוק כרטיסים סטטיים באמצעות ממשקי API פשוטים של REST. בנוסף, אתם יכולים לצרף אובייקטים לכרטיס סטטי, כמו מיקום או מדיה.
כיצד מילות מפתח שליליות עובדות
כרטיסים סטטיים נמצאים מימין לשעון Glass כברירת מחדל ומציגים מידע שרלוונטי למשתמש בזמן המסירה. עם זאת, הם לא דורשים תשומת לב מיידית כמו כרטיסים בשידור חי והמשתמשים יכולים לבחור לקרוא את הכרטיס או לפעול בו בזמנם הפנוי.
כש-Glassware מוסיפה כרטיסים סטטיים לציר הזמן, ייתכן ש-Glass ישמיע צליל התראה כדי ליידע את המשתמשים. כל הכרטיסים הסטטיים הקודמים זזו ימינה ונעלמים מציר הזמן אחרי 7 ימים או כש-200 כרטיסים חדשים יותר.
מתי כדאי להשתמש בנכסים לחיפוש מפיצים
כרטיסים סטטיים הם כלי נהדר להעברת התראות תקופתיות למשתמשים כאשר קורים דברים חשובים.
לדוגמה, שירות חדשות ששולח את הכתבות החדשותיות המובילות בזמן אמת. כרטיסים סטטיים של שיקוף API יכולים גם להפעיל כרטיסים בשידור חי או מוטמעות דרך האפשרות בתפריט OPEN_URI
. כך תוכלו ליצור אינטראקציות משולבות שמשתמשות בכרטיסים סטטיים כהתראות וכרטיס בזמן אמת או חוויה סוחפת לחוויה אינטראקטיבית יותר.
במסמכי התיעוד תוכלו לראות רשימה מלאה של הפעולות האפשריות בפריטים בציר הזמן.
הוספת כרטיסים סטטיים
כדי להכניס כרטיסים סטטיים (פריטים של ציר הזמן), צריך לפרסם ייצוג JSON של פריט בציר הזמן לנקודת הקצה ב-REST.
רוב השדות של פריטי ציר הזמן הם אופציונליים. בצורתו הפשוטה ביותר, פריט של ציר הזמן מכיל רק הודעת טקסט קצרה, כמו בדוגמה זו:
HTTP גולמי
POST /mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}
Content-Type: application/json
Content-Length: 26
{ "text": "Hello world" }
Java
TimelineItem timelineItem = new TimelineItem();
timelineItem.setText("Hello world");
service.timeline().insert(timelineItem).execute();
Python
timeline_item = {'text': 'Hello world'}
service.timeline().insert(body=timeline_item).execute()
בסיום תקבלו קוד תגובה של 201 Created
עם עותק מלא של הפריט שנוצר. בדוגמה הקודמת, תגובה מוצלחת עשויה להיראות כך:
HTTP גולמי
HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303
{
"kind": "glass#timelineItem",
"id": "1234567890",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello world"
}
הפריט שנוסף שיופיע בציר הזמן של המשתמש ייראה כך:
הוספת פריט של ציר זמן עם קובץ מצורף
תמונה אחת שווה אלף מילים, וזה הרבה יותר ממה שאפשר להכניס לפריט על ציר הזמן. לשם כך, אתם יכולים לצרף גם תמונות וסרטונים לפריט בציר הזמן. לפניכם דוגמה להוספת פריט ציר זמן עם קובץ מצורף של תמונה:
HTTP גולמי
POST /upload/mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}
Content-Type: multipart/related; boundary="mymultipartboundary"
Content-Length: {length}
--mymultipartboundary
Content-Type: application/json; charset=UTF-8
{ "text": "A solar eclipse of Saturn. Earth is also in this photo. Can you find it?" }
--mymultipartboundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
[binary image data]
--mymultipartboundary--
Java
TimelineItem timelineItem = new TimelineItem();
timelineItem.setText("Hello world");
InputStreamContent mediaContent = new InputStreamContent(contentType, attachment);
service.timeline().insert(timelineItem, mediaContent).execute();
Python
timeline_item = {'text': 'Hello world'}
media_body = MediaIoBaseUpload(
io.BytesIO(attachment), mimetype=content_type, resumable=True)
service.timeline().insert(body=timeline_item, media_body=media_body).execute()
פריט ציר זמן עם תמונה מצורפת נראה בערך כך ב-Glass:
צירוף הסרטון מתבצע
אם מצרפים קובצי וידאו לפריטים בציר הזמן, מומלץ לשדר את הסרטון במקום להעלות את כל המטען הייעודי (payload) בבת אחת. ממשק ה-API של Google Mirror תומך בסטרימינג באמצעות HTTP בשידור חי, הורדה מתקדמת ופרוטוקול סטרימינג בזמן אמת (RTSP). RTSP נחסם לעתים קרובות על ידי חומות אש, לכן כדאי להשתמש באפשרויות האחרות כשאפשר.
כדי לצפות בסרטון בסטרימינג, משתמשים בפריט התפריט PLAY_VIDEO
ומציינים את כתובת ה-URL של הסרטון בתורpayload
. למידע נוסף, תוכלו לקרוא את המאמר הוספת מנות מובנות לתפריט ואת הפורמטים הנתמכים של המדיה.
עימוד
אפשר לעימוד של פריטים בציר הזמן שלא מתאימים לכרטיס ציר זמן אחד, אבל צריך לשייך אותם לאותו כרטיס. לכל הפריטים בעימוד יש אותו timeline.id
, ולכן אותם סטים של מנות בתפריט. כשמשתמש מקיש על פריט של ציר הזמן שעבר עימוד, מופיע פריט התפריט מידע נוסף.
Glass מגדיר עימוד באופן אוטומטי לפריטי ציר הזמן שמוצגים text
. כדי שגרסה של Glass תוצג באופן אוטומטי html
, צריך להשתמש בתג article
עם מאפיין class שמוגדר ל-auto-paginate
כמו בדוגמה הבאה:
<article class="auto-paginate">
<h3>Very long list</h3>
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
<li>Fourth item</li>
<li>Fifth item</li>
<li>Sixth item</li>
<li>...</li>
</ul>
<article>
כדי לבצע עימוד ידני, צריך להשתמש בתג article
עבור התוכן שרוצים להציג בכל כרטיס. התוכן של כל תג article
מוצג ב-Glass בכרטיס ציר זמן נפרד. לדוגמה, אתם יכולים ליצור פריט בציר זמן מעומד עם קוד ה-HTML הבא:
<article>
<section>
<p>First page</p>
</section>
</article>
<article>
<section>
<p>Second page</p>
</section>
</article>
<article>
<section>
<p>Third page</p>
</section>
</article>
כברירת מחדל, הכרטיס הראשון שמוצג בעימוד ציר הזמן מוצג ככרטיס השער ומוצג שוב כשהמשתמש בוחר את האפשרות בתפריט מידע נוסף. כדי למנוע את הצגת הכרטיס הראשון שוב אחרי הקשה על מידע נוסף, אפשר לציין את מחלקת ה-CSS ב-cover-only
עבור התג הראשון <article>
:
<article class="cover-only">
...
אפשר גם להשתמש בפריטים שעברו עימוד אוטומטי במחלקה cover-only
:
<article class="auto-paginate cover-only">
...
קיבוץ
קיבוץ הודעות מאפשר לקבץ יחד פריטים קשורים, אבל נפרדים, כמו להודעות ספציפיות בשרשור של הודעות אימייל. לחבילות יש כרטיס שער ראשי שהמשתמש מקיש עליו כדי להציג ציר זמן שמכיל את הכרטיסים האחרים בחבילה. אפשר להבדיל בין חבילות לכרטיסי ציר זמן רגילים באמצעות קיפול בפינה שבפינה השמאלית העליונה של כרטיס השער של החבילה.
כדי לקבץ פריטים בציר הזמן, יש ליצור אותם עם אותו ערך עבור
bundleId
. הפריט האחרון שנוסף הוא כרטיס השער של החבילה.
התמונות הבאות מציגות כרטיס עם מארז קיפול בפינה השמאלית העליונה, ושני כרטיסים מקובצים מתחתיו.
קורא פריטים בציר הזמן
השירות יכול לגשת לכל הפריטים בציר הזמן שהוא יצר, ולכל הפריטים בציר הזמן ששותפו איתו. כך אפשר לפרט את הפריטים בציר הזמן שגלויים לשירות.
HTTP גולמי
GET /mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}
Java
TimelineItem timelineItem = new TimelineItem();
service.timeline().list().execute();
Python
service.timeline().list().execute()
אפשר להשתמש בפעולות אחרות של REST כדי לקבל, לעדכן ולמחוק פריטים של ציר הזמן.
גישה לקבצים מצורפים
אפשר לגשת לקבצים מצורפים לפריט בציר זמן באמצעות נכס מערך בשם attachments
.
אפשר לקבל את הנתונים הבינאריים של הקובץ המצורף באמצעות המאפיין contentUrl
של הקובץ המצורף או באמצעות נקודת הקצה של הקבצים המצורפים.
HTTP גולמי
GET /mirror/v1/timeline/{itemId}/attachments/{attachmentId} HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}
Java
TimelineItem item = service.timeline().get(itemId).execute();
String attachmentId = item.getAttachments().get(0).getId();
service.attachments().get(itemId, attachmentId).executeAsInputStream();
יצירת אפשרויות בתפריט
האפשרויות בתפריט מאפשרות למשתמשים לבקש פעולות שקשורות לכרטיס של ציר הזמן, והן מגיעות משני סוגים: אפשרויות מובנות בתפריט ומנות מותאמות אישית בתפריט.
האפשרויות המובנות בתפריט מספקות גישה לפונקציות מיוחדות שסופקו על ידי Glass, כמו קריאת כרטיס ציר הזמן בקול, ניווט למיקום, שיתוף תמונה או מענה להודעה:
פריטים בתפריט בהתאמה אישית מאפשרים לאפליקציה לחשוף התנהגות ספציפית ל-Glassware שלכם, וניתן גם לספק סמל של מנה בתפריט כדי שיתאים למותג שלכם.
הוספת אפשרויות בתפריט מובנות
אפשר להוסיף פריטים מובנים של התפריט לאפשרויות בציר הזמן על ידי אכלוס השדה menuItems array
כשמוסיפים אותם.
כדי להשתמש בתפריט מובנה, צריך לאכלס רק את הערך action
של כל menuItem
.
HTTP גולמי
HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303
{
"text": "Hello world",
"menuItems": [
{
"action": "REPLY"
}
]
}
הגדרת אפשרויות בתפריט בהתאמה אישית
אם האפשרויות בתפריט המובנות לא מתאימות, אתם יכולים ליצור מנות מותאמות אישית עם הפעולות שאתם מוסיפים, על ידי הוספה או עדכון של ציר זמן:
- יש לציין את
CUSTOM
עבורmenuItem.action
. - יש לציין
menuItem.id
. כשמשתמשים מקישים על האפשרות בתפריט בהתאמה אישית, Glassware מקבלת התראה עםmenuItem.id
מאוכלס. כך ניתן לקבוע את מקור ההתראה. - מציינים
menuItem.values
כדי להוסיףiconUrl
ו-displayName
שמופיעים ב-Glass. מציבים את התמונה בגודל 50 x 50 PNG, לבן עם רקע שקוף ב-iconUrl
. יש לציין
displayTime
. אם לא מצייניםdisplayTime
, פריט ציר הזמן יעבור לציר הזמן בכל פעם שהמשתמשים מקישים על האפשרות בתפריט בהתאמה אישית.
HTTP גולמי
HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303
{
"text": "Hello world",
"displayTime": "2013-08-08T22:47:31-07:00",
"menuItems": [
{
"action": "CUSTOM",
"id": "complete"
"values": [{
"displayName": "Complete",
"iconUrl": "http://example.com/icons/complete.png"
}]
}
]
}
המשתמשים יכולים להצמיד את כרטיס ציר הזמן שלך
תוכלו ליצור אפשרות בתפריט כדי לאפשר למשתמשים להצמיד את כרטיס ציר הזמן. כך יוצג כרטיס ציר הזמן באופן קבוע מימין לכרטיס השעון הראשי. המשתמשים יכולים גם לבטל את נעילת הכרטיס באמצעות אותו פריט בתפריט.
האפשרות של תפריט ההצמדה היא אפשרות מובנית, כך שכל מה שצריך לעשות הוא לספק TOGGLE_PINNED
action
עבור menuItem
.
HTTP גולמי
HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303
{
"text": "You can pin or unpin this card.",
"menuItems": [
{
"action": "TOGGLE_PINNED"
}
...
]
}
מינויים
ה-שיקוף API מאפשר להירשם לקבלת התראות שנשלחות כשהמשתמש מבצע פעולות ספציפיות לגבי ציר הזמן, או כשמיקום המשתמש מתעדכן. כשאתם נרשמים להתראה, אתם מספקים כתובת URL לקריאה חוזרת (callback) שמעבדת את ההתראה.
קבלת התראות
התראה מ-שיקוף API נשלחת כבקשת POST
לנקודת הקצה הרשומה שכוללת גוף בקשה של JSON
.
HTTP גולמי
{
"collection": "timeline",
"itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
"operation": "UPDATE",
"userToken": "harold_penguin",
"verifyToken": "random_hash_to_verify_referer",
"userActions": [
{
"type": "<TYPE>",
"payload": "<PAYLOAD>"
}
]
}
Java
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.mirror.model.Notification;
import java.io.IOException;
import java.io.InputStream;
// ...
public class MyClass {
// ...
/**
* Parse a request body into a Notification object.
*
* @param requestBody The notification payload sent by the Mirror API.
* @return Parsed notification payload if successful, {@code null} otherwise.
*/
static Notification parseNotification(InputStream requestBody) {
try {
JsonFactory jsonFactory = new JacksonFactory();
return jsonFactory.fromInputStream(requetBody, Notification.class);
} catch (IOException e) {
System.out.println("An error occurred: " + e);
return null;
}
}
// ...
}
Python
import json
def parse_notification(request_body):
"""Parse a request body into a notification dict.
Params:
request_body: The notification payload sent by the Mirror API as a string.
Returns:
Dict representing the notification payload.
"""
return json.load(request_body)
השירות שלך חייב להגיב ל-API עם קוד מצב HTTP של 200 OK
אם לא אירעה שגיאה.
אם השירות שלכם מגיב עם קוד שגיאה, יכול להיות ש-שיקוף API ינסה לשלוח שוב את ההודעה לשירות.
סוגי התראות
ממשק ה-API של השתקפות שולח מטען ייעודי (payload) שונה עבור אירועים שונים.
כתיבת תשובה
המשתמש השיב לאפשרות ציר הזמן באמצעות האפשרות בתפריט
REPLY
המובנית:
{
"collection": "timeline",
"itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
"operation": "INSERT",
"userToken": "harold_penguin",
"verifyToken": "random_hash_to_verify_referer",
"userActions": [
{
"type": "REPLY"
}
]
}
המאפיין itemId
מוגדר לערך ID
של הפריט שמכיל:
- המאפיין
inReplyTo
מוגדר ל-ID
של הפריט בציר הזמן, שאליו הוא משיב. - המאפיין
text
הוגדר לתמליל הטקסט. - המאפיין
recipients
מוגדר ל-creator
של הפריט בציר הזמן, כתשובה, אם היא קיימת.
דוגמה:
{
"kind": "glass#timelineItem",
"id": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
"inReplyTo": "3236e5b0-b282-4e00-9d7b-6b80e2f47f3d",
"text": "This is a text reply",
"recipients": [
{
"id": "CREATOR_ID",
"displayName": "CREATOR_DISPLAY_NAME",
"imageUrls": [
"CREATOR_IMAGE_URL"
]
}
]
}
מחיקה
המשתמש מחק פריט בציר זמן:
{
"collection": "timeline",
"itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
"operation": "DELETE",
"userToken": "harold_penguin",
"verifyToken": "random_hash_to_verify_referer",
"userActions": [
{
"type": "DELETE"
}
]
}
המאפיין itemId
מוגדר למזהה של הפריט שנמחק. הפריט כבר לא מכיל מטא-נתונים מלבד המזהה שלו והנכס isDeleted
.
נבחר פריט בתפריט בהתאמה אישית
המשתמש בחר פריט בתפריט בהתאמה אישית שהוגדר על ידי השירות:
{
"collection": "timeline",
"itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
"operation": "UPDATE",
"userToken": "harold_penguin",
"userActions": [
{
"type": "CUSTOM",
"payload": "PING"
}
]
}
המאפיין itemId
מוגדר למזהה של המנה בתפריט שנבחר על ידי המשתמש.
מערך userActions
מכיל רשימה של פעולות מותאמות אישית שהמשתמש ביצע בפריט הזה. השירות שלכם צריך לטפל בפעולות האלה בהתאם.
עדכון מיקום
מיקום חדש זמין למשתמש הנוכחי:
{
"collection": "locations",
"itemId": "latest",
"operation": "UPDATE",
"userToken": "harold_penguin",
"verifyToken": "random_hash_to_verify_referer"
}
כש-Glassware מקבל עדכון מיקום, שולחים בקשה לנקודת הקצה glass.locations.get כדי לאחזר את המיקום הידוע האחרון. כלי הזכוכית שלכם מקבל עדכוני מיקום כל עשר דקות.
פקודה קולית
המשתמש/ת הפעיל/ה פקודה קולית, לדוגמה: "Ok Glass, Note a note, Cat Stream, Chipte’s birthday is tomorrow". ההתראה הבאה נשלחת ל-Glassware שלכם:
{
"collection": "timeline",
"operation": "INSERT",
"userToken": "chipotle's_owner",
"verifyToken": "mew mew mew",
"itemId": "<ITEM_ID>",
"userActions": [
{“type”: "LAUNCH"}
]
}
ההתראה הזו שונה מהתראות אחרות בערך של LAUNCH
בנכס userActions
.
לאחר מכן, תוכלו להשתמש בערך ב-itemId
כדי לאחזר את הפריט של ציר הזמן:
{
"id": "<ITEM_ID>",
"text": "Chipotle's birthday is tomorrow",
"recipients": [
{"id": "CAT_STREAM"}
]
}
המאפיין recipients
מכיל את id
של איש הקשר שמייצג את הפקודה הקולית שנעשה בה שימוש.