Plik danych Kampanie

Sprzedawcy będą mogli dodawać linki do kampanii fundraisingowych do swoich informacji w Google. Plik danych o kampaniach służy dostawcy kampanii do przesyłania danych o wynikach wszystkich kampanii z poprzednich dni. Kanał kampanii będzie korzystał z ogólnego serwera SFTP, a wartość „name” w pliku deskryptora będzie ustawiona na „fundraising.campaign”. Instrukcje korzystania z ogólnego serwera SFTP znajdziesz w tym samouczku. Specyfikacja protokołu jest dostępna poniżej, podobnie jak przykładowy plik danych JSON.

Uwaga: ta sekcja dotyczy tylko tych partnerów, którzy przeprowadzają integrację z usługą zbiórki funduszy na rzecz małych firm. Jeśli nie masz pewności, czy bierzesz udział w tym projekcie, skontaktuj się z osobą kontaktową w zespole Google Business Development.

Specyfikacja proto

Poniższa specyfikacja jest dostępna w formacie proto. Służy do określania wszystkich pól dostępnych w pliku danych. Podczas przesyłania na ogólny serwer SFTP możesz też używać formatowania JSON, jak pokazano w przykładzie JSON.

Definicja pliku danych kampanii

message CampaignFeed {
  repeated Campaign data = 1;
}

Definicja kampanii

message Campaign {
  // Unique identifier for the campaign. (required)
  // (Note: could be the same as the campaign 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 campaign
  // entry.)
  string campaign_id = 1;

  // Whether this campaign entry is active (i.e. able to accept donation) or
  // inactive. (required)
  CampaignStatus campaign_status = 2;

  // The campaign url that merchants might upload to Google if they have a
  // campaign set up with the partner. (required)
  string campaign_url = 3;

  // Name/title of the campaign. (optional)
  string campaign_title = 4;

  // More detailed description of the campaign. (optional)
  string campaign_description = 5;

  // The start/publish timestamp for the campaign. Format: Seconds of UTC time
  // since the Unix epoch. (optional)
  int64 campaign_start_sec = 6;

  // The end timestamp for the campaign. Format: Seconds of UTC time since the
  // Unix epoch. (optional)
  int64 campaign_end_sec = 7;

  // The monetary amount for the campaign goal. (optional)
  MonetaryAmount campaign_goal = 8;

  // The date in YYYY-MM-DD format indicating 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. The feed must include all campaign entries for the given date
  // (no partial uploads). (required)
  string data_retrieval_date = 9;

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

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

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

Definicja stanu kampanii

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

    // Unused.
    STATUS_UNSPECIFIED = 0;

    // Able to accept donation.
    ACTIVE = 1;

    // Unable to accept donation.
    INACTIVE = 2;
  }

  Status status = 1;
}

Definicja sprzedawcy

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

Definicja kwoty pieniężnej

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

Definicja adresu pocztowego

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

Przykładowa kampania (w formacie JSON)

Poniższy przykład JSON zawiera 1 aktywną kampanię dla Jetters Pizza, w której w poprzednim dniu odnotowano 2 transakcje. Wartość transakcji użytkowników Google z poprzedniego dnia wyniosła 50,00 PLN, a cel kampanii to 20 000,00 PLN. Oprócz tego pliku na ogólny serwer SFTP należy przesłać plik deskryptora, w którym wartość „name” jest ustawiona na „fundraising.campaign”. Więcej informacji o korzystaniu z ogólnego serwera SFTP znajdziesz w tym samouczku.

{
  "data": [
    {
      "campaign_id": "1",
      "campaign_status": {
        "status": "ACTIVE"
      },
      "campaign_url": "www.example.com/jetterspizza",
      "campaign_title": "Fundraiser for Jetters Pizza",
      "campaign_start_sec": 1546300800,
      "campaign_goal": {
        "monetary_amount_centi": 2000000,
        "currency_code": "USD"
      },
      "data_retrieval_date": "2020-04-24",
      "amount_contributed_previous_day": {
        "monetary_amount_centi": 5000,
        "currency_code": "USD"
      },
      "num_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"
      }
    }
  ]
}