updated docs

Author: cx-lukas-salkauskas-x

README.rst

@@ -17,6 +17,11 @@ Table of contents
 2. Installation
 3. Google Play (`receipt` + `signature`)
 4. Google Play (verification)
+
+   - Setting up Google Service Account Credentials
+   - Usage Example (with file path)
+   - Usage Example (with credentials dictionary)
+
 5. Google Play (verification with result)
 6. Google Play (consuming products)
 7. App Store (`receipt` + using optional `shared-secret`)
@@ -94,6 +99,95 @@ An additional example showing how to authenticate using dict credentials instead
 
 4. Google Play verification
 ===========================
+
+Setting up Google Service Account Credentials
+----------------------------------------------
+
+Before using Google Play verification, you need to set up a Google Service Account and obtain the credentials file. This section explains what ``GOOGLE_SERVICE_ACCOUNT_KEY_FILE`` is and how to obtain it.
+
+**What is GOOGLE_SERVICE_ACCOUNT_KEY_FILE?**
+
+``GOOGLE_SERVICE_ACCOUNT_KEY_FILE`` is a JSON file containing a service account's private key and credentials. This file authorizes your application to access the Google Play Developer API to verify in-app purchases and subscriptions.
+
+The credentials can be provided in two ways:
+
+1. **As a file path** (string): Path to the JSON key file downloaded from Google Cloud Console
+2. **As a dictionary** (dict): The parsed JSON content of the key file
+
+**How to obtain the Service Account Key File:**
+
+1. **Link Google Cloud Project to Google Play Console**
+
+   - Go to `Google Play Console <https://play.google.com/console>`_
+   - Select your app
+   - Navigate to **Settings → Developer account → API access**
+   - If you haven't linked a project yet, click **Link** to create or link a Google Cloud project
+   - Accept the terms and conditions
+
+2. **Create a Service Account**
+
+   - In the API access page, scroll to **Service accounts**
+   - Click **Create new service account** or **Learn how to create service accounts** (this will take you to Google Cloud Console)
+   - In Google Cloud Console:
+
+     - Go to **IAM & Admin → Service Accounts**
+     - Click **+ CREATE SERVICE ACCOUNT**
+     - Enter a name (e.g., "InAppPy Validator") and description
+     - Click **CREATE AND CONTINUE**
+     - Skip granting roles (not needed for this step)
+     - Click **DONE**
+
+3. **Grant Permissions in Google Play Console**
+
+   - Return to Google Play Console → **Settings → Developer account → API access**
+   - Find your newly created service account in the list
+   - Click **Grant access**
+   - Under **App permissions**, select your app
+   - Under **Account permissions**, enable:
+
+     - **View financial data** (for viewing purchase/subscription info)
+     - **Manage orders and subscriptions** (if you need to consume products or manage subscriptions)
+
+   - Click **Invite user** and then **Send invitation**
+
+4. **Download the JSON Key File**
+
+   - Go back to **Google Cloud Console → IAM & Admin → Service Accounts**
+   - Click on your service account email
+   - Go to the **KEYS** tab
+   - Click **ADD KEY → Create new key**
+   - Select **JSON** as the key type
+   - Click **CREATE**
+   - The JSON key file will be automatically downloaded
+   - **IMPORTANT**: Store this file securely! It contains a private key and cannot be recovered if lost
+
+5. **Important Notes**
+
+   - The JSON key file should contain fields like: ``type``, ``project_id``, ``private_key_id``, ``private_key``, ``client_email``, etc.
+   - Keep this file secure and never commit it to version control
+   - In some cases, you may need to create at least one product in your Google Play Console before the API access works properly
+   - It may take a few minutes for permissions to propagate after granting access
+
+**Example JSON key file structure:**
+
+.. code:: json
+
+    {
+      "type": "service_account",
+      "project_id": "your-project-id",
+      "private_key_id": "a1b2c3d4e5f6...",
+      "private_key": "-----BEGIN PRIVATE KEY-----\nYourPrivateKeyHere\n-----END PRIVATE KEY-----\n",
+      "client_email": "[email protected]",
+      "client_id": "123456789",
+      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+      "token_uri": "https://oauth2.googleapis.com/token",
+      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/..."
+    }
+
+Usage Example (with file path)
+-------------------------------
+
 .. code:: python
 
     from inapppy import GooglePlayVerifier, errors
@@ -105,9 +199,53 @@ An additional example showing how to authenticate using dict credentials instead
         """
         purchase_token = receipt['purchaseToken']
         product_sku = receipt['productId']
+
+        # Pass the path to your service account JSON key file
+        verifier = GooglePlayVerifier(
+            GOOGLE_BUNDLE_ID,
+            '/path/to/your-service-account-key.json',  # Path to the JSON key file
+        )
+        response = {'valid': False, 'transactions': []}
+        try:
+            result = verifier.verify(
+                purchase_token,
+                product_sku,
+				is_subscription=True
+            )
+            response['valid'] = True
+            response['transactions'].append(
+                (result['orderId'], product_sku)
+            )
+        except errors.GoogleError as exc:
+            logging.error('Purchase validation failed {}'.format(exc))
+        return response
+
+
+Usage Example (with credentials dictionary)
+--------------------------------------------
+
+.. code:: python
+
+    import json
+    from inapppy import GooglePlayVerifier, errors
+
+
+    def google_validator(receipt):
+        """
+        Accepts receipt, validates in Google using dict credentials.
+        """
+        purchase_token = receipt['purchaseToken']
+        product_sku = receipt['productId']
+
+        # Load credentials from environment variable or secure storage
+        # NEVER hard-code credentials in your source code!
+        credentials_json = os.environ.get('GOOGLE_SERVICE_ACCOUNT_JSON')
+        credentials_dict = json.loads(credentials_json)
+
+        # Pass the credentials as a dictionary
         verifier = GooglePlayVerifier(
             GOOGLE_BUNDLE_ID,
-            GOOGLE_SERVICE_ACCOUNT_KEY_FILE,
+            credentials_dict,  # Dictionary containing the JSON key data
         )
         response = {'valid': False, 'transactions': []}
         try:
@@ -129,6 +267,8 @@ An additional example showing how to authenticate using dict credentials instead
 =========================================
 Alternative to `.verify` method, instead of raising an error result class will be returned.
 
+**Note:** See section 4 for instructions on setting up ``GOOGLE_SERVICE_ACCOUNT_KEY_FILE``.
+
 .. code:: python
 
     from inapppy import GooglePlayVerifier, errors
@@ -140,9 +280,11 @@ Alternative to `.verify` method, instead of raising an error result class will b
         """
         purchase_token = receipt['purchaseToken']
         product_sku = receipt['productId']
+
+        # Use the service account credentials (see section 4 for setup)
         verifier = GooglePlayVerifier(
             GOOGLE_BUNDLE_ID,
-            GOOGLE_SERVICE_ACCOUNT_KEY_FILE,
+            GOOGLE_SERVICE_ACCOUNT_KEY_FILE,  # Path to JSON key file or dict
         )
         response = {'valid': False, 'transactions': []}
 
@@ -165,6 +307,8 @@ Alternative to `.verify` method, instead of raising an error result class will b
 After validating a purchase, you can consume a one-time product to prevent refunds and allow the user to purchase it again.
 This is a separate operation that should be called after verification to handle cases like power outages between validation and consumption.
 
+**Note:** See section 4 for instructions on setting up ``GOOGLE_SERVICE_ACCOUNT_KEY_FILE``.
+
 .. code:: python
 
     from inapppy import GooglePlayVerifier, errors
@@ -176,9 +320,11 @@ This is a separate operation that should be called after verification to handle
         """
         purchase_token = receipt['purchaseToken']
         product_sku = receipt['productId']
+
+        # Use the service account credentials (see section 4 for setup)
         verifier = GooglePlayVerifier(
             GOOGLE_BUNDLE_ID,
-            GOOGLE_SERVICE_ACCOUNT_KEY_FILE,
+            GOOGLE_SERVICE_ACCOUNT_KEY_FILE,  # Path to JSON key file or dict
         )
 
         try: