Age Rating Configuration Implementation

Overview

Added age rating configuration to fastlane setup, enabling automated updates of App Store age rating metadata without requiring binary uploads.

Changes Made

1. Age Rating Configuration File

File: Fastlane/age_rating_config.json

Created a JSON configuration file containing all 14 Apple App Store age rating categories:

{
  "age_rating": {
    "CARTOON_FANTASY_VIOLENCE": 0,
    "REALISTIC_VIOLENCE": 0,
    "PROLONGED_GRAPHIC_SADISTIC_REALISTIC_VIOLENCE": 0,
    "PROFANITY_CRUDE_HUMOR": 0,
    "MATURE_SUGGESTIVE": 0,
    "HORROR": 0,
    "MEDICAL_TREATMENT_INFO": 0,
    "ALCOHOL_TOBACCO_DRUGS": 0,
    "GAMBLING": 0,
    "SEXUAL_CONTENT_NUDITY": 0,
    "GRAPHIC_SEXUAL_CONTENT_NUDITY": 0,
    "UNRESTRICTED_WEB_ACCESS": 0,
    "GAMBLING_CONTESTS": 0,
    "SEVENTEEN_PLUS": false
  }
}

Values:

0 = None
1 = Infrequent/Mild
2 = Frequent/Intense

All categories are set to 0 (None) for applications with no concerning content. Adjust values as needed for your app's specific content.

2. Fastlane Lane

File: Fastlane/Fastfile

Added new update_age_rating lane with the following features:

Authentication: Uses existing App Store Connect API key pattern from the beta lane
Configuration Loading: Dynamically loads age rating config from JSON file
Error Handling: Validates config file exists before proceeding
Metadata-Only Update: Only updates age rating metadata without uploading binaries or screenshots
Export Compliance: Sets export compliance encryption flag to false

Key Parameters:

skip_binary_upload: true - Prevents uploading new app binary
skip_screenshots: true - Preserves existing App Store screenshots
skip_metadata: false - Enables metadata updates
force: true - Bypasses HTML verification checks
app_rating_config_path - Points to the age rating JSON file

3. Makefile Integration

File: Makefile

Added update-age-rating to .PHONY declaration

Added new target for easy execution:

update-age-rating: install-fastlane
	@bundle exec fastlane update_age_rating

This follows the existing pattern used for certificate management targets.

Usage

Option 1: Via Makefile (Recommended)

make update-age-rating

Option 2: Direct Fastlane Command

bundle exec fastlane update_age_rating

Option 3: iOS Platform Specific

bundle exec fastlane ios update_age_rating

Environment Variables Required

The lane uses existing App Store Connect API authentication environment variables:

SPACESHIP_CONNECT_API_KEY_ID - App Store Connect API Key ID
SPACESHIP_CONNECT_API_ISSUER_ID - App Store Connect API Issuer ID
SPACESHIP_CONNECT_API_KEY_CONTENT - App Store Connect API Key content (Base64 encoded)

These variables are already configured in the project's CI/CD workflows and can be set locally in .env file.

Verification

After running the lane, verify the changes in App Store Connect:

Log in to App Store Connect
Navigate to Apps → Your App
Go to App Information section
Scroll to Age Rating section
Verify all categories show the expected values

Technical Details

App Identifier

The lane updates metadata for the main app using the app_identifier specified in the Fastfile.

Note: Age ratings apply to the entire app family, including any associated apps (e.g., Apple Watch app).

Authentication Flow

Lane retrieves API key credentials from environment variables
Creates App Store Connect API key object
Passes API key to upload_to_app_store action
Fastlane authenticates with App Store Connect using the API key

Configuration Loading

Constructs absolute path to age_rating_config.json using File.dirname(__FILE__)
Validates file existence
Parses JSON content
Passes parsed configuration to upload_to_app_store via app_rating_config_path

Metadata-Only Update Strategy

The upload_to_app_store action supports partial updates through skip flags:

Binary upload is skipped (no new IPA uploaded)
Screenshots are skipped (existing screenshots preserved)
Metadata update is enabled (age ratings can be modified)
Force flag bypasses HTML preview verification

This allows updating age ratings without requiring a new build or affecting other App Store metadata.

CI/CD Integration

The lane can be integrated into GitHub Actions or other CI/CD pipelines:

- name: Update Age Rating
  run: bundle exec fastlane update_age_rating
  env:
    SPACESHIP_CONNECT_API_KEY_ID: ${{ secrets.APP_STORE_CONNECT_API_KEY_KEY_ID }}
    SPACESHIP_CONNECT_API_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_API_KEY_ISSUER_ID }}
    SPACESHIP_CONNECT_API_KEY_CONTENT: ${{ secrets.APP_STORE_CONNECT_API_KEY_KEY }}

Maintenance

Updating Age Ratings

If content changes require different age ratings:

Edit Fastlane/age_rating_config.json
Update the appropriate category values (0, 1, or 2)
Set SEVENTEEN_PLUS to true if content requires 17+ rating
Run make update-age-rating to apply changes

Adding to Deployment Workflow

Consider adding age rating updates to the beta deployment lane:

lane :beta do
  # ... existing beta lane code ...
  update_age_rating  # Call age rating lane
  upload_to_testflight
end

Troubleshooting

Permission Errors

Issue: "You don't have permission to update metadata"

Solution: Verify the App Store Connect API Key has "App Manager" or "Admin" role in App Store Connect → Users and Access → Keys.

Configuration File Not Found

Issue: "Age rating config file not found"

Solution: Ensure Fastlane/age_rating_config.json exists and is committed to the repository.

API Authentication Failures

Issue: "Invalid API Key" or authentication errors

Solution:

Verify environment variables are set correctly
Check API key hasn't expired in App Store Connect
Regenerate API key if necessary and update secrets

Age Rating Not Updating

Issue: Age ratings don't change in App Store Connect