儲值卡動態饋給

商家可以在 Google 上的自家商家資訊中加入儲值卡購買連結。儲值卡動態饋給可讓儲值卡平台傳送所有儲值卡前幾天的結果指標。如果一般 Dropbox 的描述元檔案中的「name」值設為「fundraising.giftcard」，則儲值卡動態饋給便會使用該 Dropbox。如需一般 Dropbox 的使用操作說明，請參閱本教學課程。下文會提供 Proto 規格及範例 JSON 動態饋給。

注意：本節內容僅適用於已完成小型企業募款整合的合作夥伴。如果您不確定自己是否要參與這項專案，請洽詢您的 Google 業務開發聯絡人。

Proto 規格

下列規格以 proto 格式提供，用來定義動態饋給中所有可用的欄位。上傳至一般 Dropbox 時，您也可以按照相關範例說明使用 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;

  // 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;

  // 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;

  // 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 {
    // 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 範例中，有一個可供銷售的「傑特披薩」有效儲值卡；前一天有兩筆來自 Google 使用者的儲值卡銷售，銷售總額為 $50.00 美元。除了這個檔案外，您還必須將描述元檔案上傳至一般 Dropbox，並在該檔案中將「name」值設為「fundraising.giftcard」。如要進一步瞭解如何使用一般 Dropbox，請參閱本教學課程。

{
  "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"
      }
    }
  ]
}