Menyinkronkan Hak Pengguna (Integrasi sisi server)

Penayang terutama menggunakan integrasi sisi server untuk mengelola pembaca dan hak mereka. Penayang menggunakan UpdateReaderEntitlements untuk memperbarui catatan Google tentang hak ID Produk untuk PPID.

Catatan: Untuk membuat dan mengelola langganan tertaut, pembaca harus dibuat menggunakan integrasi JS sisi klien

Penyiapan Google Cloud

Mengonfigurasi Penautan Langganan di Google Cloud mencakup dua komponen utama:

1. Mengaktifkan API untuk project tertentu
2. Membuat akun layanan untuk mengakses API

Mengaktifkan Subscription Linking API

Untuk menggunakan akun layanan dan mengelola hak pembaca, project Google Cloud memerlukan Subscription Linking API diaktifkan dan akun layanan OAuth dikonfigurasi dengan benar. Untuk mengaktifkan Subscription Linking API untuk project, buka menu -> APIs & Services -> Library, lalu telusuri Subscription Linking, atau buka halaman secara langsung:

https://console.cloud.google.com/apis/library?project=gcp_project_id

Gambar 1. Membuka Library API, dan mengaktifkan API untuk project Google Cloud.

Membuat Akun Layanan

Akun layanan digunakan untuk mengizinkan akses dari aplikasi Anda ke Subscription Linking API.

1. Buat akun layanan dalam konsol project Anda.
2. Buat kredensial untuk akun layanan, dan simpan file credentials.json di lokasi yang aman yang dapat diakses oleh aplikasi Anda.
3. Berikan peran IAM "Subscription Linking Admin" ke akun layanan yang Anda buat. Untuk kontrol terperinci atas kemampuan akun layanan, Anda dapat menetapkan peran yang sesuai dari tabel berikut.

Kemampuan / Peran	Admin Penautan Langganan	Subscription Linking Viewer	Subscription Linking Entitlements Viewer
Mendapatkan hak pembaca
Mendapatkan pembaca
Memperbarui hak pembaca
Menghapus pembaca

Perhatian: Kunci akun layanan memiliki risiko keamanan jika tidak dikelola dengan benar. Sebaiknya Anda memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus mengautentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi pengelolaan lainnya seperti rotasi kunci. Untuk mengetahui informasi selengkapnya, lihat praktik terbaik untuk mengelola kunci akun layanan.

Menggunakan Akun Layanan dengan Subscription Linking API

Untuk mengautentikasi panggilan ke Subscription Linking API dengan akun layanan, gunakan library klien googleapis (yang otomatis menangani permintaan access_token) atau tandatangani permintaan secara langsung dengan REST API. Jika menggunakan REST API, Anda harus mendapatkan access_token terlebih dahulu (melalui library Google Auth atau menggunakan JWT akun layanan), lalu menyertakannya di header Authorization

Contoh library klien dan REST API berikut memiliki contoh kode tentang cara memanggil getReader(), getReaderEntitlements(), updateReaderEntitlements(), dan deleteReader().

Catatan: Untuk melihat demonstrasi langsung semua metode API, lihat Demo Penautan Langganan dan kodenya.

Kunci Akun Layanan dan Kredensial Default Aplikasi (ADC)

Untuk memanggil Subscription Linking API, Anda harus memiliki kunci akun layanan. Jika Anda tidak dapat mengekspor kunci akun layanan karena kebijakan organisasi Anda, Anda dapat menggunakan metode Kredensial Default Aplikasi (ADC).

Berikut adalah contoh perintah untuk menyiapkan ADC menggunakan perintah gcloud auth application-default login:

gcloud config set project [YOUR_PROJECT_ID]

gcloud auth application-default login --impersonate-service-account [[e-mail]]

Catatan: Pengguna yang menjalankan perintah gcloud auth harus memiliki peran Service Account Token Creator.

Perintah ini membuat file JSON yang berisi kredensial akun layanan dan menempatkannya di lokasi yang dikenal pada sistem file Anda. Lokasi bergantung pada sistem operasi Anda:

• Linux, macOS: $HOME/.config/gcloud/application_default_credentials.json
• Windows: %APPDATA%\gcloud\application_default_credentials.json

Anda tidak perlu memberikan jalur ke file kunci dalam kode, karena ADC akan otomatis menelusuri kredensial dengan sendirinya.

this.auth = new Auth.GoogleAuth({
   // keyFile: process.env.KEY_FILE, - You don't need to provide this field
    'https://www.googleapis.com/auth/readerrevenue.subscriptionlinking.manage'
  ],
  ...
});

Library klien

Bagian ini menjelaskan cara menggunakan library klien googleapis di Node.js.

Permintaan sampel

import {readerrevenuesubscriptionlinking_v1, Auth} from 'googleapis';
const subscriptionLinking = readerrevenuesubscriptionlinking_v1.Readerrevenuesubscriptionlinking;

class SubscriptionLinking {
  constructor() {
    this.auth = new Auth.GoogleAuth({
      keyFile: process.env.KEY_FILE,
      scopes: [
        'https://www.googleapis.com/auth/readerrevenue.subscriptionlinking.manage'
      ],
    })
  }

  init() {
    return new subscriptionLinking(
        {version: 'v1', auth: this.auth})
  }
}

const subscriptionLinkingApi = new SubscriptionLinking();
const client = subscriptionLinkingApi.init();

/**
 * Retrieves details for a specific reader associated with the publication.
 * @async
 * @param {string} ppid - The Publisher Provided ID (ppid) for the reader.
 * @return {Promise<object>} A promise that resolves with the reader's details
 *  from the API.
 */
async function getReader(ppid) {
  const publicationId = process.env.PUBLICATION_ID;
  return await client.publications.readers.get({
    name: `publications/${publicationId}/readers/${ppid}`,
  });
}

/**
 * Updates the entitlements for a specific reader.
 * @async
 * @param {string} ppid - The Publisher Provided ID (ppid) for the reader whose
 *  entitlements are being updated.
 * @return {Promise<object>} A promise that resolves with the result of the
 *  updated entitlements object.
 */
async function updateReaderEntitlements(ppid) {
  const publicationId = process.env.PUBLICATION_ID;
  const requestBody = {
    /*
    Refer to
    https://developers.google.com/news/subscribe/subscription-linking/appendix/glossary#entitlements_object
    */
    entitlements : [{
      product_id: `${publicationId}:basic`,
      subscription_token: 'abc1234',
      detail: 'This is our basic plan',
      expire_time: '2025-10-21T03:05:08.200564Z'
    }]
  };
  return await client.publications.readers.updateEntitlements({
    name: `publications/${publicationId}/readers/${ppid}/entitlements`,
    requestBody
  });
}

/**
 * Retrieves the current entitlements for a specific reader.
 * @async
 * @param {string} ppid - The Publisher Provided ID (ppid) for the reader.
 * @return {Promise<object>} A promise that resolves with the reader's entitlements object.
 */
async function getReaderEntitlements(ppid) {
  const publicationId = process.env.PUBLICATION_ID;
  return await client.publications.readers.getEntitlements({
    name: `publications/${publicationId}/readers/${ppid}/entitlements`
  });
}

/**
 * Deletes a specific Subscription Linking reader record associated with the publication.
 * @async
 * @param {string} ppid - The Publisher Provided ID (ppid) for the reader to be deleted.
 * @param {boolean=} forceDelete - If true, delete the user even if their
 *  entitlements are not empty
 * @return {Promise<object>} A promise that resolves upon successful deletion
 *  with an empty object ({})
 */
async function deleteReader(ppid, forceDelete = false) {
  const publicationId = process.env.PUBLICATION_ID;
  return await client.publications.readers.delete({
    name: `publications/${publicationId}/readers/${ppid}`
    force: forceDelete
  });
}

REST API

Jika ingin memanggil endpoint REST API, Anda dapat menggunakan salah satu metode untuk mendapatkan accessToken yang akan ditetapkan ke header Authorization.

1. Menggunakan library GoogleAuth

import { GoogleAuth } from 'google-auth-library';
import credentialJson from 'path_to_your_json_file' with { type: 'json' };

const auth = new GoogleAuth({
    credentials: credential_json,
    scopes: [
      'https://www.googleapis.com/auth/readerrevenue.subscriptionlinking.manage'
    ]
});

async function getAccessToken() {
    const accessToken = await auth.getAccessToken();
    return accessToken;
}

2. Membuat access_token menggunakan JWT Akun Layanan

import fetch from 'node-fetch';
import jwt from 'jsonwebtoken';

function getSignedJwt() {
  /*
    Either store the service account credentials string in an environment variable
    Or implement logic to fetch it.
  */
  const key_file = process.env.CREDENTIALS_STRING

  const issueDate = new Date();
  const expireMinutes = 60;
  const offsetInSeconds = issueDate.getTimezoneOffset() * 60000;
  const expireDate = new Date(issueDate.getTime() + (expireMinutes * 60000));
  const iat = Math.floor((issueDate.getTime() + offsetInSeconds) / 1000);
  const exp = Math.floor((expireDate.getTime() + offsetInSeconds) / 1000);

  const token = {
    iss: key_file.client_email,
    iat,
    exp,
    aud: 'https://oauth2.googleapis.com/token',
    scope:'https://www.googleapis.com/auth/readerrevenue.subscriptionlinking.manage',
  }
  return jwt.sign(token, key_file.private_key, {
    algorithm: 'RS256',
    keyid: key_file.private_key_id,
  })
}

async function getAccessToken(signedJwt) {
  let body = new URLSearchParams();
  body.set('grant_type', 'urn:ietf:params:oauth:grant-type:jwt-bearer');
  body.set('assertion', signedJwt);
  const response = await fetch('https://oauth2.googleapis.com/token', {
    method: 'POST',
    headers: {'Content-Type': 'application/x-www-form-urlencoded'},
    body
  })
  const accessResponse = await response.json();
  return accessResponse.access_token;
}

Contoh kode untuk panggilan REST API dengan library Google Auth

import { GoogleAuth } from 'google-auth-library';
import fetch from 'node-fetch'
import credentialJson from 'path_to_your_json_file' with { type: 'json' };

const BASE_SUBSCRIPTION_LINKING_API_URL='https://readerrevenuesubscriptionlinking.googleapis.com/v1';
const publicationId = process.env.PUBLICATION_ID

const auth = new GoogleAuth({
    credentials: credentialJson,
    scopes: [
      'https://www.googleapis.com/auth/readerrevenue.subscriptionlinking.manage'
    ]
});

async function getAccessToken() {
    const accessToken = await auth.getAccessToken();
    return accessToken;
}

/**
 * Retrieves details for a specific reader associated with the publication.
 * @async
 * @param {string} ppid - The Publisher Provided ID (ppid) for the reader.
 * @return {object} reader json for the given ppid
 */
async function getReader(ppid) {
  const endpoint = `${BASE_SUBSCRIPTION_LINKING_API_URL}/publications/${publicationId}/readers/${ppid}`;
  const accessToken = await getAccessToken();
  const response = await fetch(endpoint, {
     method: 'GET',
     headers: {
       Authorization: `Bearer ${accessToken}`,
     },
   });
  const reader = await response.json();
  return reader;
}

/**
 * Updates the entitlements for a specific reader.
 * @async
 * @param {string} ppid - The Publisher Provided ID (ppid) for the reader.
 * @return {object} the updated entitlements object in json.
 */
async function updateReaderEntitlements(ppid) {
  const endpoint = `${BASE_SUBSCRIPTION_LINKING_API_URL}/publications/${publicationId}/readers/${ppid}/entitlements`;
  const requestBody = {
    /*
    Refer to
    https://developers.google.com/news/subscribe/subscription-linking/appendix/glossary#entitlements_object
    */
    entitlements : [{
      product_id: `${publicationId}:basic`,
      subscription_token: 'abc1234',
      detail: 'This is our basic plan',
      expire_time: '2025-10-21T03:05:08.200564Z'
    }]
  };
  const response = await fetch(endpoint, {
     method: 'PATCH',
     headers: {
       Authorization: `Bearer ${accessToken}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify(requestBody)
   })
  const updatedEntitlements = await response.json();
  return updatedEntitlements;
}

/**
 * Retrieves the current entitlements for a specific reader.
 * @async
 * @param {string} ppid - The Publisher Provided ID (ppid) for the reader.
 * @return {object} the reader's entitlements object in json.
 */
async function getReaderEntitlements(ppid) {
  const endpoint = `${BASE_SUBSCRIPTION_LINKING_API_URL}/publications/${publicationId}/readers/${ppid}/entitlements`;
  const accessToken = await getAccessToken();
  const response = await fetch(endpoint, {
     method: 'GET',
     headers: {
       Authorization: `Bearer ${accessToken}`,
     },
   });
  const entitlements = await response.json();
  return entitlements;
}

/**
 * Deletes a specific Subscription Linkikng reader record associated with the publication.
 * @async
 * @param {string} ppid - The Publisher Provided ID (ppid) for the reader.
 * @param {boolean=} forceDelete - If true, delete the user even if their
 *  entitlements are not empty
 * @return {object} returns an empty object ({}) if the delete operation is successful
 */
async function deleteReader(ppid, forceDelete = false) {
  const endpoint = `${BASE_SUBSCRIPTION_LINKING_API_URL}/publications/${publicationId}/readers/${ppid}?force=${forceDelete}`;
  const response = await fetch(endpoint, {
     method: 'DELETE',
     headers: {
       Authorization: `Bearer ${accessToken}`,
     }
   });
  const result = await response.json();
  return result;
}