Google Cüzdan API'sini kullanarak web'de kartlar oluşturun

1. Giriş

Genel Bakış

Google Cüzdan API'si, kullanıcılarla çeşitli kart türleri üzerinden etkileşim kurmanıza olanak tanır: bağlılık kartları, teklifler, hediye kartları, etkinlik biletleri, toplu taşıma biletleri, biniş kartları ve daha fazlası. Her kart türü veya geçme sınıfı, kullanıcı deneyimini geliştirmek için kullanım alanına özel alanlar ve özellikler içerir.

Ancak bunlar her kullanım alanına uygun olmayabilir. Daha özelleştirilmiş bir deneyim oluşturmak için genel kart türünü kullanabilirsiniz. Aşağıda, genel kart türünün kullanım alanlarına örnekler verilmiştir:

  • Otopark kartları
  • Kütüphane üyelik kartları
  • Kayıtlı değer kuponları
  • Spor salonu üyelik kartları
  • Rezervasyonlar

Genel kartları, aşağıdakilerin sunulduğu tüm kullanım alanları için kullanabilirsiniz:

  • En fazla üç satırlık bilgi
  • (İsteğe bağlı) Barkod grafiği
  • (İsteğe bağlı) Ayrıntılar bölümü

Konferans etkinliği için örnek bir Google Cüzdan kartı

Google Cüzdan API'si hakkında daha fazla bilgi edinmek veya bir web sayfasına Google Cüzdan'a ekle düğmesi eklemek için lütfen Google Cüzdan geliştirici dokümanlarına bakın.

Kart sınıfları ve nesneleri

Google Cüzdan API'si aşağıdakilerin oluşturulması için yöntemler sunar:

Tür

Açıklama

Kursu geçme

Tek bir kart nesnesi için şablon. Bu sınıfa ait tüm geçiş nesneleriyle ilgili ortak bilgileri içerir.

Nesneyi geçirin

Bir User-ID için benzersiz olan geçiş sınıfı örneği.

Bu codelab hakkında

Bu codelab'de aşağıdaki görevleri tamamlayacaksınız.

  1. Demo modunda yeni bir veren hesap oluşturma
  2. Kartları vermek için bir hizmet hesabı oluşturun
  3. Yeni genel kart sınıfı oluşturma
  4. Yeni kart nesnesi oluşturun
  5. Kartı kaydetmek için Google Cüzdan'a ekle düğmesi oluşturun
  6. Düğmeyi web sayfanızda gösterin
  7. Kart kaydetme sonucunu işleme

Ön koşullar

Hedefler

Bu codelab'i tamamladıktan sonra şunları yapabileceksiniz:

  • Google Cüzdan'ı kullanarak kart nesneleri oluşturma
  • Google Cüzdan'a ekle düğmesi oluşturun

Destek

Codelab'de herhangi bir noktada takılırsanız google-pay/wallet-web-codelab GitHub deposunda referans olarak kullanabileceğiniz eksiksiz bir çözüm bulabilirsiniz.

2. Kurulum

Bu adımda, demo modunda bir Veren hesap oluşturacaksınız. Böylece, kullanıcı cüzdanlarına eklenebilecek kart sınıfları ve nesneler oluşturabilirsiniz. Şimdi bir Google Cloud projesi ve hizmet hesabı oluşturacaksınız. Bunlar, arka uç sunucusuyla aynı şekilde programatik olarak geçiş sınıfları ve nesneleri oluşturmak için kullanılacaktır. Son olarak, Google Cloud hizmet hesabına, Google Cüzdan'ı veren kuruluş hesabınızdaki kartları yönetme yetkisi verirsiniz.

Google Cüzdan'ı veren kuruluş hesabına kaydolma

Google Cüzdan'a yönelik kartlar oluşturmak ve dağıtmak için Kartı Veren hesap gereklidir. Google Pay ve Cüzdan Konsolu. İlk aşamada, demo modunda kart oluşturabilirsiniz. Dolayısıyla oluşturduğunuz kartları yalnızca belirli test kullanıcıları ekleyebilir. Test kullanıcıları Google Pay ve Cüzdan Konsolu.

Demo modu hakkında daha fazla bilgi edinmek için Genel geçiş ön koşullarını inceleyin.

  1. Google Pay ve Cüzdan Konsolu
  2. Kartı veren kuruluş hesabı oluşturmak için ekrandaki talimatları uygulayın.
  3. Google Cüzdan API'si seçeneğini belirleyin.
  4. Hizmet şartlarını ve gizlilik politikasını anladığınızı onaylayın
  5. Düzenleyen Kimliği değerini bir metin düzenleyiciye veya başka bir konuma kopyalayın
  6. Yönet sekmesinde Test hesapları oluştur'u seçin
  7. Bu codelab'de kullanacağınız e-posta adreslerini ekleyin

Google Cüzdan API'sini etkinleştir

  1. Google Cloud Console'da oturum açın.
  2. Google Cloud projeniz yoksa hemen bir proje oluşturun (daha fazla bilgi için Proje oluşturma ve yönetme başlıklı makaleyi inceleyin)
  3. Projeniz için Google Cüzdan API'sini (Kartlar için Google Pay API'si olarak da bilinir) etkinleştirin.

Hizmet hesabı ve anahtar oluşturma

Google Cüzdan API'sini çağırmak için bir hizmet hesabı ve hizmet hesabı anahtarı gereklidir. Hizmet hesabı, Google Cüzdan API'sini çağıran kimliktir. Hizmet hesabı anahtarı, uygulamanızı hizmet hesabı olarak tanımlayan bir özel anahtar içerir. Bu anahtar hassas olduğu için gizli tutun.

Hizmet hesabı oluşturma

  1. Google Cloud konsolunda Hizmet Hesapları'nı açın.
  2. Hizmet hesabınız için bir ad, kimlik ve açıklama girin
  3. OLUŞTUR VE DEVAM ET'i seçin
  4. BİTTİ'yi seçin

Hizmet hesabı anahtarı oluşturma

  1. Hizmet hesabınızı seçin
  2. KEYS menüsünü seçin.
  3. ANAHTAR EKLE'yi, ardından Yeni anahtar oluştur'u seçin.
  4. JSON anahtar türünü seçin
  5. OLUŞTUR'u seçin.

Anahtar dosyasını yerel iş istasyonunuza kaydetmeniz istenir. Konumunu unutmayın.

GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlayın

GOOGLE_APPLICATION_CREDENTIALS ortam değişkeni, Google SDK'ları tarafından bir hizmet hesabı olarak kimlik doğrulaması yapmak ve bir Google Cloud projesinin farklı API'lerine erişmek için kullanılır.

  1. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlamak için Google Cloud hizmet hesabı anahtarları dokümanındaki talimatları uygulayın.
  2. Ortam değişkeninin yeni bir terminal (MacOS/Linux) veya komut satırı (Windows) oturumunda ayarlandığını doğrulayın (zaten açıksa yeni bir oturum başlatmanız gerekebilir)
    echo $GOOGLE_APPLICATION_CREDENTIALS

Hizmet hesabını yetkilendirme

Son olarak, hizmet hesabını Google Cüzdan kartlarını yönetmesi için yetkilendirmeniz gerekir.

  1. Google Pay ve Cüzdan Konsolu
  2. Kullanıcılar'ı seçin.
  3. Kullanıcı davet et'i seçin.
  4. Hizmet hesabının e-posta adresini girin (ör. test-svc@myproject.iam.gserviceaccount.com)
  5. Erişim düzeyi açılır menüsünden Geliştirici veya Yönetici'yi seçin.
  6. Davet Et'i seçin.

3. Örnek Node.js uygulamasını başlatma

Süre 10:00

Bu adımda alışveriş web sitesi ve arka uç sunucusu olarak çalışan örnek bir Node.js uygulamasını çalıştıracaksınız.

Örnek depoyu klonlama

google-pay/wallet-web-codelab deposu, Node.js tabanlı bir örnek projenin yanı sıra kart sınıflarının ve nesnelerin temel hazırlığını yapmak için kullanılan bir arka uç sunucusunu taklit eden farklı komut dosyası dosyaları içerir. Bunları, ürün ayrıntıları ekranına Google Cüzdan'a ekle düğmesi içerecek şekilde düzenlersiniz.

  1. Depoyu yerel iş istasyonunuza klonlayın
    git clone https://github.com/google-pay/wallet-web-codelab.git

Proje bağımlılıklarını yükleyin

  1. Terminal veya komut satırı isteminizde klonlanan depoyu açın
  2. web dizinine gidin (Bu, codelab'in geri kalanında değiştireceğiniz uygulamadır)
    cd web
  3. Node.js bağımlılıklarını yükleyin
    npm install .
  4. Uygulamayı başlatın
    node app.js
  5. http://localhost:3000 üzerinde çalışan uygulamayı açın

E-posta adresi girebileceğiniz bir alan ve Kart oluştur düğmesi içeren örnek bir web uygulaması

E-posta adresinizi girip Kart oluştur'u seçerseniz hiçbir şey olmaz. Sonraki adımlarda uygulamayı yeni bir geçiş sınıfı ve nesne oluşturacak şekilde yapılandıracaksınız.

4. Genel kart sınıfı oluşturma

Bu adımda, kartınız için temel sınıf oluşturacaksınız. Bir kullanıcı için oluşturulan her yeni kart, ilgili kart sınıfında tanımlanan özellikleri devralır.

Bu codelab'de oluşturacağınız kart sınıfı, Genel kartların esnekliğini kullanarak hem kimlik rozeti hem de meydan okuma puanı izleyicisi olarak çalışan bir nesne oluşturur. Bu sınıftan bir kart nesnesi oluşturulduğunda, aşağıdaki grafik gibi görünür.

Kart sınıfları, doğrudan Google Pay ve Cüzdan Konsolu'nu kullanarak veya Google Cüzdan API'sini kullanarak. Bu codelab'de, API'yi kullanarak genel kart sınıfı oluşturacaksınız. Bu, özel bir arka uç sunucusunun geçiş sınıfları oluşturmak için kullanacağı süreci izler.

  1. web/app.js dosyasını aç
  2. issuerId değerini Google Pay'deki Sertifikayı Veren Kimliğinizle değiştirin ve Cüzdan Konsolu
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. createPassClass işlevini bulun
  4. İşlevde, kimliği doğrulanmış bir HTTP istemcisi oluşturun ve Google Cüzdan API'yi kullanarak yeni bir kart sınıfı oluşturun.
    // TODO: Create a Generic pass class
let genericClass = {
  'id': `${classId}`,
  'classTemplateInfo': {
    'cardTemplateOverride': {
      'cardRowTemplateInfos': [
        {
          'twoItems': {
            'startItem': {
              'firstValue': {
                'fields': [
                  {
                    'fieldPath': 'object.textModulesData["points"]'
                  }
                ]
              }
            },
            'endItem': {
              'firstValue': {
                'fields': [
                  {
                    'fieldPath': 'object.textModulesData["contacts"]'
                  }
                ]
              }
            }
          }
        }
      ]
    },
    'detailsTemplateOverride': {
      'detailsItemInfos': [
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': 'class.imageModulesData["event_banner"]'
                }
              ]
            }
          }
        },
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': 'class.textModulesData["game_overview"]'
                }
              ]
            }
          }
        },
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': 'class.linksModuleData.uris["official_site"]'
                }
              ]
            }
          }
        }
      ]
    }
  },
  'imageModulesData': [
    {
      'mainImage': {
        'sourceUri': {
          'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-2021-card.png'
        },
        'contentDescription': {
          'defaultValue': {
            'language': 'en-US',
            'value': 'Google I/O 2022 Banner'
          }
        }
      },
      'id': 'event_banner'
    }
  ],
  'textModulesData': [
    {
      'header': 'Gather points meeting new people at Google I/O',
      'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.',
      'id': 'game_overview'
    }
  ],
  'linksModuleData': {
    'uris': [
      {
        'uri': 'https://io.google/2022/',
        'description': 'Official I/O \'22 Site',
        'id': 'official_site'
      }
    ]
  }
};

let response;
try {
  // Check if the class exists already
  response = await httpClient.request({
    url: `${baseUrl}/genericClass/${classId}`,
    method: 'GET'
  });

  console.log('Class already exists');
  console.log(response);
} catch (err) {
  if (err.response && err.response.status === 404) {
    // Class does not exist
    // Create it now
    response = await httpClient.request({
      url: `${baseUrl}/genericClass`,
      method: 'POST',
      data: genericClass
    });

    console.log('Class insert response');
    console.log(response);
  } else {
    // Something else went wrong
    console.log(err);
    res.send('Something went wrong...check the console logs!');
  }
}

Kodunuz çalıştırıldığında yeni bir geçiş sınıfı oluşturur ve sınıf kimliğini verir. Sınıf kimliği, kartı verenin kimliği ve ardından geliştirici tarafından tanımlanan bir son ekten oluşur. Bu durumda, sonek codelab_class olarak ayarlanır (sınıf kimliği 1234123412341234123.codelab_class değerine benzerdir). Çıkış günlükleri, Google Cüzdan API'sinin yanıtını da içerir.

5. Genel kart nesnesi oluşturma

Bu adımda, Node.js uygulamanızı, daha önce oluşturduğunuz sınıfı kullanarak bir genel geçiş nesnesi oluşturacak şekilde yapılandıracaksınız. Kullanıcılar için kart nesneleri oluşturmak için iki akış vardır.

Arka uç sunucusunda geçiş nesnesini oluşturma

Bu yaklaşımda, geçiş nesnesi bir arka uç sunucusunda oluşturulur ve istemci uygulamasına imzalı bir JWT olarak döndürülür. Bu seçenek, kullanıcının cüzdanına eklemeye çalışmadan önce nesnenin mevcut olmasını sağladığından, kullanıcı benimseme oranının yüksek olduğu durumlar için daha uygundur.

Kullanıcı cüzdanına eklediğinde kart nesnesini oluşturma

Bu yaklaşımda, geçiş nesnesi tanımlanır ve arka uç sunucusunda imzalı bir JWT olarak kodlanır. Ardından, JWT'ye referans veren istemci uygulamasında Google Cüzdan'a ekle düğmesi oluşturulur. Kullanıcı düğmeyi seçtiğinde, kart nesnesini oluşturmak için JWT kullanılır. Bu yöntem, geçiş nesnelerin oluşturulmasını ve kullanılmamasını önlediği için kullanıcı benimsemesinin değişken veya bilinmediği durumlar için daha uygundur. Bu yaklaşım codelab'de kullanılacaktır.

  1. web/app.js dosyasını aç
  2. createPassObject işlevini bulun
  3. İşlevde, kullanıcınız için yeni bir kart nesnesi tanımlayın
    // TODO: Create a new Generic pass for the user
let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`;
let objectId = `${issuerId}.${objectSuffix}`;

let genericObject = {
  'id': `${objectId}`,
  'classId': classId,
  'genericType': 'GENERIC_TYPE_UNSPECIFIED',
  'hexBackgroundColor': '#4285f4',
  'logo': {
    'sourceUri': {
      'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg'
    }
  },
  'cardTitle': {
    'defaultValue': {
      'language': 'en',
      'value': 'Google I/O \'22'
    }
  },
  'subheader': {
    'defaultValue': {
      'language': 'en',
      'value': 'Attendee'
    }
  },
  'header': {
    'defaultValue': {
      'language': 'en',
      'value': 'Alex McJacobs'
    }
  },
  'barcode': {
    'type': 'QR_CODE',
    'value': `${objectId}`
  },
  'heroImage': {
    'sourceUri': {
      'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg'
    }
  },
  'textModulesData': [
    {
      'header': 'POINTS',
      'body': '1234',
      'id': 'points'
    },
    {
      'header': 'CONTACTS',
      'body': '20',
      'id': 'contacts'
    }
  ]
};

// TODO: Create the signed JWT and link
res.send("Form submitted!");

Uygulamayı yeniden yükleyip e-posta adresinizi girip formu gönderirseniz herhangi bir çıkış görmezsiniz. Kart nesnesi, arka uç uygulaması tarafından tanımlanıyor ancak herhangi bir çıkış döndürülmüyor. Ardından, kartı Google Cüzdan'a ekle bağlantısına dönüştürün.

6. Bir metin oluştur: Google Cüzdan'a ekle düğmesi

Son adımda imzalı bir JWT oluşturacak ve Google Cüzdan'a ekle düğmesinde kullanılabilecek bir bağlantı döndüreceksiniz. Kullanıcı düğmeyi seçtiğinde kartı cüzdanına kaydetmesi istenir.

  1. JWT hak taleplerini oluşturun, hizmet hesabı özel anahtarını kullanarak kodlayın ve yerleştirilmiş bağlantıyı içeren Google Cüzdan'a ekle düğmesini döndürün
    // TODO: Create the signed JWT and link
const claims = {
  iss: credentials.client_email,
  aud: 'google',
  origins: [],
  typ: 'savetowallet',
  payload: {
    genericObjects: [
      genericObject
    ]
  }
};

const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' });
const saveUrl = `https://pay.google.com/gp/v/save/${token}`;

res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`);
  2. Tarayıcınızda çalışan uygulamayı yeniden yükleyin
  3. E-posta adresinizi forma girip Kart oluştur'u seçin
  4. Gösterildiğinde Google Cüzdan'a ekle düğmesini seçin

Google Cüzdan&#39;a ekle düğmesi, uygulama ön ucunda başarıyla oluşturuldu

7. Tebrikler

Örnek genel kart nesnesi

Tebrikler, Web'de Google Cüzdan API'sini başarıyla entegre ettiniz.

Daha fazla bilgi

google-pay/wallet-web-codelab GitHub deposundaki eksiksiz entegrasyona göz atın.

Kart oluşturun ve üretim erişimi isteyin

Üretimde kendi kartlarınızı düzenlemeye hazır olduğunuzda Google Pay ve Cüzdan Konsolu'nu kullanabilirsiniz.

Daha fazla bilgi edinmek için Web API Ön Koşulları'na bakın.