הוספת הטבות

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

היקף ההרשאות הנדרש

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

• photoslibrary.appendonly
• photoslibrary.library
• photoslibrary.sharing

בכל היקף, הקריאה enrichAlbum מוגבלת רק לאלבומים שהאפליקציה יצרה.

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

סוגי העשרה

Google Photos תומך בשלושה סוגים של העשרות באלבומים: טקסט, מיקומים ומפות.

העשרת טקסט

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

העשרת מיקום

העשרת המיקום היא סמן ושם המקום שאפשר להוסיף כדי להוסיף הערה על מיקום.

העשרות מפה

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

מיקומים

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

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

תחילת האלבום

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

סוף האלבום

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

ביחס לפריט מדיה

ניתן להוסיף פריט מדיה/העשרה ביחס לפריט מדיה שמתחיל אחרי המיקום שלו באלבום.

ביחס לפריט העשרה

ניתן להוסיף פריט מדיה/העשרה ביחס לפריט העשרה שמתחיל אחרי המיקום שלו באלבום.

הוספת שיפורים לאלבום

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

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

REST

זוהי בקשת POST:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment
Content-type: application/json
Authorization: Bearer oauth2-token
request-body

גוף הבקשה מכיל את פריט העשרה ואת המיקום שלו:

{
  "newEnrichmentItem": {
    enrichment-to-be-added
  },
  "albumPosition": {
    position-of-enrichment
}

הנה תשובה לדוגמה:

{
  "enrichmentItem": {
    "id": "enrichment-item-id",
  }
}

Java

try {
  // Create the enrichment using the NewEnrichmentItemFactory helper
  NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createTextEnrichment("");

  // Set the position of the enrichment within the album
  AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

  // To add an enrichment, specify the album, the enrichment item,
  // and the position in the album where the enrichment is to be added
  AddEnrichmentToAlbumResponse response = photosLibraryClient
      .addEnrichmentToAlbum(albumId, newEnrichmentItem, albumPosition);
  // The response contains an EnrichmentItem
  // whose ID can be used to position media items or other enrichments
  EnrichmentItem enrichmentItem = response.getEnrichmentItem();
  String itemId = enrichmentItem.getId();
} catch (ApiException e) {
  // Handle error
}

PHP

// Create the enrichment item using the PhotosLibraryResourceFactory helper
$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("");
// ...
// Set the position of the enrichment within the album
$position = new AlbumPosition();
// ...
try {
    // To add an enrichment, specify the album, the enrichment item,
    // and the position in the album where the enrichment is to be added
    $response = $photosLibraryClient->addEnrichmentToAlbum($albumId, $newEnrichmentItem, $position);
    // The response contains an EnrichmentItem
    // whose ID can be used to position media items or other enrichments
    $enrichmentItem = $response->getEnrichmentItem();
    $itemId = $enrichmentItem->getId();

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

העשראות נתמכות

העשרת טקסט

עשרים טקסט מכילים מחרוזת טקסט יחידה (עד 1,000 תווים), כפי שמוצג בדוגמה הבאה:

REST

{
  "text": "Text to be shown"
}

Java

// Use the NewEnrichmentItemFactory helper to create a text enrichment item
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createTextEnrichment("text to be shown");

PHP

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("text to be shown");

העשרת מיקום

העשרת המיקום כוללות שם שרירותי של מיקום ואת מיקומי קווי האורך והרוחב. השדה locationName מוגבל ל-500 תווים.

REST

{
  "location": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  }
}

Java

// Use the NewEnrichmentItemFactory helper to create a location enrichment
// with the name, latitude, and longitude of the location
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createLocationEnrichment("Australia", -21.197, 95.821);

PHP

// Create a new location object and set the name, latitude, and longitude of the location
$newLocation = new Location();
$newLocation->setLocationName("Australia");
$newLocation->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithLocation($newLocation);

העשרות מפה

העשרה של מפות מציגות שני מיקומים, כשכל אחד מהם מכיל שם וקו רוחב וקו אורך. בדומה להעשרת המיקום, השדה locationName בתוך המקור ו-destination מוגבל ל-500 תווים.

REST

{
  "origin": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  },
  "destination": {
    "locationName": "San Francisco",
    "latlng": {
      "latitude": "37.757",
      "longitude": "122.507"
    }
  }
}

Java

// Use the NewEnrichmentItemFactory helper to create a map enrichment item for
// an origin and a destination location
NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createMapEnrichment(
    "Australia", -21.197, 95.821, // origin
    "San Francisco", 37.757, 122.507 // destination
);

PHP

// Create two new location objects to create a map enrichment item
// for an origin and a destination location
$locationAustralia = new Location();
$locationAustralia->setLocationName("Australia");
$locationAustralia->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));

$locationSanFrancisco = new Location();
$locationSanFrancisco->setLocationName("San Francisco");
$locationSanFrancisco->setLatlng((new LatLng())->setLatitude(37.757)->setLongitude(122.507));

$newEnrichmentItem =
  PhotosLibraryResourceFactory::newEnrichmentItemWithMap($locationAustralia, $locationSanFrancisco);

מיקום נתמך

תחילת האלבום

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

REST

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);

סוף האלבום

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

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::LAST_IN_ALBUM);

ביחס לפריט מדיה

ציון המיקום relativeMediaItem מתייחס למיקום ביחס לפריט מדיה. הפריטים יתווספו אחרי פריט המדיה שצוין.

REST

{
  "position": "after-media-item",
  "relativeMediaItemId": "media-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);

ביחס לפריט העשרה

ציון relativeEnrichmentItemId מתייחס למיקום ביחס לפריט העשרה. הפריטים יתווספו אחרי פריט ההעשרה שצוין.

REST

{
  "position": "after-enrichment-item",
  "relativeEnrichmentItemId": "enrichment-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);

שינוי העשראות

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