إضافة معلومات مفصّلة

تتيح التحسينات لتطبيقك التحكم في بنية الصور وطريقة عرضها داخل ألبوم في "صور Google". وهي تسمح لك بتقديم سياق إضافي للمستخدم من خلال التعليقات التوضيحية النصية أو للموقع وترتيب الصور/الصور التي تحكي قصة معًا.

نطاق التفويض المطلوب

لإضافة معلومات مفصّلة، يجب توفّر أحد النطاقات التالية على الأقل:

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

بالنسبة إلى كل نطاق، يقتصر استدعاء enrichAlbum على الألبومات التي أنشأها التطبيق فقط.

عند استخدام نطاق .sharing، يقتصر enrichAlbum على الحالات التي يتصرف فيها المطوّر نيابةً عن مالك الألبوم المشترَك.

أنواع التحسين

يتيح تطبيق "صور Google" استخدام ثلاثة أنواع من الميزات المفيدة في الألبومات: النصوص والمواقع الجغرافية والخرائط.

إثراءات النص

إثراء النص هو سلسلة نص عادي يمكن إدراجها للتعليق على الألبوم.

لقطة شاشة لعملية تحسين النص المعروضة في "صور Google"

إضافات المواقع الجغرافية

توضيح الموقع الجغرافي هو علامة واسم المكان الذي يمكن إدراجه لإضافة تعليقات توضيحية إلى الموقع.

لقطة شاشة تُظهر تحسين الموقع الجغرافي في "صور Google"

تفاصيل الخرائط

تحسين الخريطة هو خريطة تتضمّن أصل ووجهة محدّدين يمكن إدراجهما في الألبوم.

لقطة شاشة تعرض معلومات مفصّلة في "صور Google"

المواضع

لإدراج عناصر الوسائط وإثراءات الألبوم، عليك تحديد موضع الألبوم. إنّ تحديد موضع اختياري لعناصر الوسائط، ولكن يجب تحديده لتضمينه في الألبوم.

لا يمكن تحديد الموضع إلا عند إنشاء عنصر وسائط أو إضافة إضافات. لا يمكن إعادة تنظيم عناصر الوسائط الحالية في ألبوم، لذا من المهم ضبط موضع العنصر عند إضافته.

بداية الألبوم

يمكن إضافة عنصر وسائط/تحسين إلى بداية الألبوم كتحديد موضع مطلق.

نهاية الألبوم

يمكن إضافة عنصر وسائط/تحسين إلى نهاية الألبوم كتعيين مطلق.

نسبةً إلى عنصر الوسائط

يمكن إضافة عنصر وسائط/تحسين نسبةً إلى عنصر وسائط يبدأ بعد موضعه في الألبوم.

مقارنةً بعنصر العرض

يمكن إضافة الوسائط أو عنصر التحسين نسبةً إلى العنصر الإرشادي الذي يبدأ بعد وضعه في الألبوم.

جارٍ إضافة إثراءات إلى الألبوم

تتم إضافة التحسينات واحدة تلو الأخرى ويجب إضافتها إلى موضع في ألبوم. لإضافة مزيد من التفاصيل إلى ألبوم، يمكنك طلب الرمز albums.addEnrichment.

إذا نجح الطلب، سيتم عرض id الخاص بمادة العرض، والتي يمكن استخدامها لتحديد موضع الوسائط أو معلومات الاستفادة الأخرى.

راحة

إليك طلب 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 حرف)، كما هو موضّح في المثال التالي:

راحة

{
  "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 حرف.

راحة

{
  "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 حرف.

راحة

{
  "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 إلى بداية الألبوم. يتم عرض العناصر الموجودة هنا للمستخدم أولاً:

راحة

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

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

نهاية الألبوم

يشير الموضع LAST_IN_ALBUM إلى نهاية الألبوم. يتم عرض العناصر الموجودة هنا للمستخدم الأخير.

راحة

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

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

نسبةً إلى عنصر الوسائط

يشير تحديد الموضع relativeMediaItem إلى موضع نسبة إلى عنصر وسائط. تتم إضافة العناصر بعد عنصر الوسائط المحدّد.

راحة

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

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

مقارنةً بعنصر العرض

يشير تحديد relativeEnrichmentItemId إلى موضع نسبة إلى عنصر التحسين. تتم إضافة السلع بعد عنصر التحسين المحدّد.

راحة

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

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

تعديل الإضافات

وما من طريقة حاليًا لتعديل البيانات المجانية. ومع ذلك، بعد إنشاء قسم مخصص وإضافته إلى ألبوم، يمكن للمستخدم تعديل التحسينات من خلال تطبيق "صور Google".