خلاصة بطاقات الهدايا

سيتمكّن التجّار من إضافة روابط لشراء بطاقات الهدايا إلى بياناتهم على Google. تُستخدَم خلاصة بطاقات الهدايا في منصة بطاقات الهدايا لإرسال مقاييس حول نتائج الأيام السابقة لجميع بطاقات الهدايا. ستستخدم خلاصة بطاقات الهدايا خادم SFTP العام مع ضبط قيمة "الاسم" في ملف الواصف على fundraising.giftcard. للحصول على تعليمات حول كيفية استخدام خادم بروتوكول النقل الآمن للملفات (SFTP) العام، يمكنك الرجوع إلى هذا البرنامج التعليمي. تتوفّر مواصفات البروتوكول أدناه بالإضافة إلى نموذج لخلاصة JSON.

ملاحظة: لا ينطبق هذا القسم إلا على الشركاء الذين يكملون عملية دمج ميزة "جمع التبرّعات للأنشطة التجارية الصغيرة". إذا لم تكن متأكّدًا مما إذا كنت مشاركًا في هذا المشروع، يُرجى التواصل مع جهة الاتصال المسؤولة عن تطوير الأعمال في Google.

مواصفات Proto

تتوفّر المواصفات أدناه بتنسيق proto. يُستخدَم هذا لتحديد جميع الحقول المتوفّرة في الخلاصة. عند التحميل إلى خادم Generic SFTP، يمكنك أيضًا استخدام تنسيق JSON كما هو موضّح في نموذج JSON.

تعريف خلاصة بطاقات الهدايا

message GiftCardFeed {
  repeated GiftCard data = 1;
}

تعريف بطاقة الهدايا

message GiftCard {
  // Unique identifier for the gift card. (required)
  // (Note: could be the same as the gift card url if that's the only unique
  // identifier the partner uses. This will mainly be used for identification
  // when Google and partners communicate issues for a particular gift card
  // entry.)
  string gift_card_id = 1 [features.(pb.cpp).string_type = STRING];

  // Whether this gift card entry is active (i.e. able to be purchased) or
  // inactive. (required)
  GiftCardStatus gift_card_status = 2;

  // The gift card url on the platform. (required)
  string gift_card_url = 3 [features.(pb.cpp).string_type = STRING];

  // The date in YYYY-MM-DD format indicates when the
  // amount_contributed_previous_day and num_of_transactions_previous_day data
  // below are retrieved. Should always be one day after the date which the
  // stats in xxx_previous_day corresponds to. UTC timezone should be used to
  // delineate which transactions fall on which dates.
  //  E.g. if the amount_contributed_previous_day corresponds to the amount
  //  contributed yesterday, then the data_retrieval_date here should be set as
  //  today's date. (required)
  // The feed must include all gift card entries for the given date (no partial
  // uploads). (required)
  string data_retrieval_date = 4 [features.(pb.cpp).string_type = STRING];

  // Previous day's monetary amount contributed through the Enhanced User
  // Referral Feature(s) to this gift card program. (required)
  MonetaryAmount amount_contributed_previous_day = 5;

  // Previous day's number of transactions through the Enhanced User Referral
  // Feature(s) for this gift card program. (required)
  int32 num_transactions_previous_day = 6;

  // Information about the merchant that initiated the campaign. (required)
  MerchantInfo merchant_info = 7;
}

تعريف حالة بطاقة الهدايا

message GiftCardStatus {
  enum Status {
    option features.(pb.cpp).enum_name_uses_string_view = false;

    // Unused.
    STATUS_UNSPECIFIED = 0;

    // Able to be purchased.
    ACTIVE = 1;

    // Unable to be purchased.
    INACTIVE = 2;
  }

  Status status = 1;
}

تعريف التاجر

message MerchantInfo {
  // Unique identifier for the merchant.
  // (recommended for Campaign feed, required for others)
  string merchant_id = 1;

  // Name of the merchant that initiated the campaign.
  // (recommended for Campaign feed, required for others)
  string merchant_name = 2;

  // Unstructured address of the merchant that initiated the gift card.
  // (optional)
  // E.g. "1600 Amphitheatre Pkwy, Mountain View, CA, USA, 94043"
  string merchant_address_unstructured = 3;

  // Structured address of the merchant that initiated the gift card. (required)
  PostalAddress merchant_postal_address = 4;

  // Business category of the merchant, e.g. restaurant. (optional)
  // See https://developers.google.com/places/supported_types for possible
  // categories.
  string merchant_category = 5;
}

تعريف المبلغ النقدي

message MonetaryAmount {
  // The monetary amount in centi-units of the currency.
  // For example: 1.95 USD is 195 in centi-units.
  // If your amount contains fractions of the smallest currency unit, then it
  // will be rounded using nearest even rounding (e.g. 2.5 cents rounded
  // to 2 cents, 3.5 cents rounded to 4 cents, 0.5 cents rounded to 0 cents,
  // 2.51 cents rounded to 3 cents). (required)
  int64 monetary_amount_centi = 1;

  // The currency of the price that is defined in ISO 4217. (required)
  string currency_code = 2;
}

تعريف العنوان البريدي

// The postal address for a merchant.
message PostalAddress {
  // The country, e.g. "US". (required)
  string country = 1;

  // The locality/city, e.g. "Mountain View". (required)
  string locality = 2;

  // The region/state/province, e.g. "CA". This field is only required in
  // countries where region is commonly a part of the address. (optional)
  string region = 3;

  // The postal code, e.g. "94043". (required)
  string postal_code = 4;

  // The street address, e.g. "1600 Amphitheatre Pkwy". (optional)
  string street_address = 5;
}

مثال على بطاقة هدايا (بتنسيق JSON)

يحتوي مثال JSON أدناه على بطاقة هدايا نشطة واحدة متاحة للبيع في Jetters Pizza. تمت عمليتان لبيع بطاقات الهدايا في اليوم السابق بإجمالي مبيعات بلغ 50.00 دولار أمريكي من مستخدمي Google. بالإضافة إلى هذا الملف، يجب أيضًا تحميل ملف واصف إلى خادم SFTP العام مع ضبط قيمة "الاسم" في ملف الواصف على "fundraising.giftcard". لمزيد من المعلومات حول كيفية استخدام مرجع خادم SFTP العام، يُرجى الرجوع إلى هذا البرنامج التعليمي.

{
  "data": [
    {
      "gift_card_id": "1",
      "gift_card_status": {
        "status": "ACTIVE"
      },
      "gift_card_url": "www.example.com/jetterspizza",
      "data_retrieval_date": "2020-04-24",
      "amount_contributed_previous_day": {
        "monetary_amount_centi": 5000,
        "currency_code": "USD"
      },
      "num_of_transactions_previous_day": 2,
      "merchant_info": {
        "merchant_id": "A",
        "merchant_name": "Jetters Pizza",
        "merchant_address_unstructured": "1600 Amphitheatre Pkwy, Mountain View, CA, USA, 94043",
        "merchant_postal_address": {
          "country": "United States",
          "region": "CA",
          "postal_code": "94043",
          "street_address": "1600 Amphitheatre Pkwy",
          "locality": "Mountain View"
        },
        "merchant_category": "restaurant"
      }
    }
  ]
}