Skip to content

AGENTS.md

Latest commit

 

History

History
311 lines (230 loc) · 10.3 KB

AGENTS.md

File metadata and controls

311 lines (230 loc) · 10.3 KB

AI Agent Guide for Conversions API Parameter Builder SDK

Project Overview

The Conversions API Parameter Builder SDK is a multi-language toolkit designed to improve the quality of Conversions API parameter retrieval and validation. The SDK ensures event parameters adhere to best practices across multiple platforms.

Repository: https://github.com/facebook/capi-param-builder

Supported Languages

  • Server-side: PHP, Java, NodeJS, Python, Ruby
  • Client-side: JavaScript

Each language implementation lives in its own top-level directory with its own build system, tests, examples, and documentation.

Project Structure

param_sdk/
├── README.md              # Main project documentation
├── AGENTS.md              # AI Agent guidance (this file)
├── CODE_OF_CONDUCT.md     # Code of conduct
├── CONTRIBUTING.md        # Contribution guidelines
├── LICENSE                # License file
├── composer.json          # PHP root composer file
├── .github/workflows/     # CI/CD workflows for all languages
├── java/                  # Java implementation
├── nodejs/                # Node.js implementation
├── php/                   # PHP implementation
├── python/                # Python implementation
└── ruby/                  # Ruby implementation

Note: The client_js/ directory is not open-sourced yet, the dir only contains examples.

Each language directory follows a consistent structure:

<language>/
├── README.md              # Language-specific quick start guide
├── CHANGELOG.md           # Version history and changes
├── CONTRIBUTING.md        # Contribution guidelines
├── CODE_OF_CONDUCT.md     # Code of conduct
├── LICENSE                # License file
├── capi-param-builder/    # Main SDK implementation (Python/Ruby use capi_param_builder with underscore)
│   ├── src/               # Source code
│   ├── tests/ or test/    # Unit tests
│   └── ...                # Language-specific build files
└── example/ or examples/  # Example usage code (PHP uses "examples")

Core Functionality

The SDK provides utilities for:

  • Cookie parameter extraction - Facebook click identifier (fbc) and browser identifier (fbp)
  • Client IP address retrieval - Enhanced mechanisms for capturing client IP addresses with IPv6 support (IPv4 fallback when IPv6 is unavailable)
  • Customer Information Parameters normalization and hashing - Tools to help adopt best practices for normalizing and hashing customer information including email, phone, name (first and last), address (city, state, zip code, country), gender, date of birth, external ID

For details on features, refer to the Parameter Builder Library.

Testing and Validation

Critical Rule: Always Run Tests Before Committing Changes

MANDATORY: After making any code changes to a language implementation, you MUST run the appropriate test command for that language before considering the task complete.

Test Commands by Language

Node.js

cd nodejs/capi-param-builder
npm install
npm test

Tested on Node.js versions: 18.x, 20.x, 22.x, 24.x

Python

cd python/capi_param_builder
python3 -m unittest test/test_param_builder.py

Tested on Python versions: 3.9, 3.10, 3.11

Java

cd java/capi-param-builder
chmod +x ./gradlew
./gradlew build

Tested on Java versions: 8, 11, 17, 21

PHP

cd php/capi-param-builder
composer install --dev --prefer-source
./vendor/bin/phpunit ./tests/ --debug

Tested on PHP versions: 7.4, 8.0, 8.1, 8.2, 8.3, 8.4

Ruby

cd ruby/capi_param_builder
gem install minitest
ruby -Ilib:test test/test_param_builder.rb

Tested on Ruby versions: 3.0, 3.2, 3.3

Making Code Changes

Language-Specific Considerations

  1. Maintain API Consistency: All language implementations should provide equivalent functionality with language-appropriate idioms. When adding a feature to one language, consider whether it should be added to others.

  2. Backward Compatibility: The SDK is used by external developers. We strongly recommend maintaining backward compatibility with existing flows. Breaking changes require:

    • Version bump (follow semantic versioning)
    • Changelog entry
    • Migration guide if necessary

  3. Human Review for Intrusive Changes: If you have intrusive changes that could break existing integrations or significantly alter SDK behavior, please ensure human review before implementation. Always prefer backward-compatible solutions over breaking changes.

Common File Locations

Note: Python and Ruby use capi_param_builder (with underscores) instead of capi-param-builder (with dashes).

  • Core logic: <language>/capi-param-builder/src/ (or capi_param_builder/ for Python/Ruby)
  • Tests: <language>/capi-param-builder/tests/ or <language>/capi-param-builder/test/ (or capi_param_builder/ for Python/Ruby)
  • Models: <language>/capi-param-builder/src/model/ or similar (or capi_param_builder/ for Python/Ruby)
  • Utilities: <language>/capi-param-builder/src/utils/ (or capi_param_builder/ for Python/Ruby)

Workflow for Adding Features

  1. Research existing implementation - Check if similar functionality exists in other language implementations
  2. Update the implementation - Add code to src/ directory
  3. Add tests - Create or update test files with comprehensive test coverage
  4. Run tests locally - Use the appropriate test command for the language
  5. Update documentation - Update README.md and add inline code documentation
  6. Update CHANGELOG.md - Document the change following existing format
  7. Bump version - If the code change needs to be released, bump the version number following semantic versioning (see Version Files section below)
  8. Test examples - Verify example code still works if applicable

Version Files by Language

When bumping versions, update the version number in these files:

  • Node.js: nodejs/capi-param-builder/package.json
  • Python: python/capi_param_builder/setup.py
  • Java: java/capi-param-builder/build.gradle and java/build.gradle
  • PHP: php/capi-param-builder/composer.json and composer.json
  • Ruby: ruby/capi_param_builder/capi_param_builder.gemspec with ruby/capi_param_builder/lib/release_config.rb

Note: For Client-side JavaScript (Meta Internal Only), see the dedicated section above.

Workflow for Fixing Bugs

  1. Reproduce the issue - Write a failing test that demonstrates the bug
  2. Fix the implementation - Make targeted changes to source code
  3. Verify the fix - Ensure the new test passes
  4. Run full test suite - Confirm no regressions
  5. Update CHANGELOG.md - Document the bug fix
  6. Bump version - If the bug fix needs to be released, bump the version number following semantic versioning
  7. Check other languages - Verify if the same bug exists in other implementations

CI/CD Pipeline

Each language has its own CI workflow in .github/workflows/:

  • <language>_ci.yml - Continuous integration (runs tests)
  • <language>_cd.yml - Continuous deployment (publishes packages)

CI runs automatically on:

  • Push to any branch (for changed files in that language's directory)
  • Pull requests
  • Manual workflow dispatch

The CI matrix tests against multiple versions of each language runtime to ensure compatibility.

Best Practices

Code Quality

  • Follow language-specific conventions and style guides
  • Keep functions focused and testable
  • Add meaningful comments for complex logic
  • Use descriptive variable and function names

Testing

  • Write unit tests for all new functionality
  • Test edge cases (null, empty, invalid input)
  • Mock external dependencies when appropriate

Documentation

  • Update README.md for public API changes
  • Add inline documentation for complex functions
  • Include usage examples for new features
  • Keep CHANGELOG.md up to date

Version Control

  • Make focused commits with clear messages
  • Reference issue numbers in commit messages
  • Keep changes scoped to single language when possible
  • Run tests before pushing

Common Tasks

Updating a shared constant

  1. Find the constants file (e.g., Constants.js, constants.py)
  2. Update the constant value
  3. Check for tests that may be affected
  4. Run full test suite
  5. Update any dependent example code

Adding a new parameter to the builder

  1. Update the main builder class (e.g., ParamBuilder.js, param_builder.py)
  2. Add validation logic if needed
  3. Add tests for the new parameter
  4. Update examples to show usage
  5. Document in README.md

External Resources

Troubleshooting

Tests failing after changes

  1. Read the error message carefully - test frameworks provide specific failure details
  2. Run tests in isolation to identify the failing test
  3. Check if changes affected shared utilities or constants
  4. Verify all dependencies are installed

CI pipeline failures

  1. Check the specific workflow that failed (language-specific)
  2. Review the GitHub Actions logs for error details
  3. Ensure changes work on all tested language versions
  4. Verify no uncommitted files are required

Dependency issues

  1. Check package manager files for each language:
    • Node.js: package.json
    • Python: setup.py
    • Java: build.gradle
    • PHP: composer.json
    • Ruby: capi_param_builder.gemspec
  2. Ensure versions are compatible with the tested runtime versions
  3. Run clean install (delete node_modules, .gradle, cache, etc. and reinstall)

Important Notes

  • Never commit secrets or credentials - This is a public open-source project
  • Cross-language consistency - Keep APIs and behavior consistent across implementations
  • Semantic versioning - Follow semver for version bumps
  • Run tests before submitting - All tests must pass before changes are complete