README

This plugin integrates Shopware 6 stores with the hello again customer loyalty platform, enabling OAuth login, automatic points awards for orders, and seamless SSO for app users.

Features

• OAuth 2.0 Authentication - Connect hello again app accounts with Shopware shop accounts
• Automatic Points Awards - Track and sync completed orders to hello again for points
• Webview SSO - Auto-login app users when visiting the shop

Installation

1. Install the plugin via Shopware plugin manager
2. Configure API credentials in plugin settings
3. Set up the cron job for order synchronization:

bin/console helloagain:data-export

Shopware Version Support

• 6.6 - main branch
• 6.5 - shopware-6.5 branch
• 6.4 - shopware-6.4 branch (deprecated)

Configuration Endpoints

Configure these URIs in your hello again dashboard:

OAuth2 Authorize URI:    BASEURL/hla/oauth2/authorize
OAuth2 Token URI:        BASEURL/hla/oauth2/token
Webview SSO URI:         BASEURL/hla/session/init?helloagain_token={{externalToken}}
Webview with Redirect:   BASEURL/hla/session/init?helloagain_token={{externalToken}}&redirect_uri={{redirectUrl}}

Usage

OAuth 2.0 Login

Users can connect their hello again app account with their shop account through the OAuth flow. The app will redirect users to the authorize endpoint, where they log in and grant permission.

Webview SSO

Automatically log in users from the hello again app by appending a token to any shop URL:

https://yourshop.com/any-page?helloagain_token=<token>

The plugin intercepts the request, validates the token, logs in the user, and redirects to the requested page.

API Alternative (for headless/mobile):

curl -X POST https://yourshop.com/store-api/v1/get-user-by-token \
  -H "Content-Type: application/json" \
  -d '{"helloagain_token": "<token>"}'

# Returns: {"contextToken": "<shopware_session_token>"}

Order Points Export

Orders are automatically tracked when they reach configured statuses (e.g., "paid", "completed"). The cron job syncs them to hello again for points calculation.

Headless/Store API Usage

The plugin provides Store API endpoints for headless Shopware implementations.

OAuth Authorization Flow

Step 1: Get Context Token

curl -X POST https://yourshop.com/store-api/account/login \
  -H "sw-access-key: <SW-ACCESS-KEY>" \
  -F "username=<USERNAME>" \
  -F "password=<PASSWORD>"

Step 2: Request Authorization Code

curl -X POST https://yourshop.com/store-api/v1/authorize \
  -H "sw-access-key: <SW-ACCESS-KEY>" \
  -H "sw-context-token: <SW-CONTEXT-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"scope": "email first_name last_name"}'

Step 3: Exchange Code for Token

curl -X POST https://yourshop.com/store-api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "<AUTHORIZATION_CODE>",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "grant_type": "authorization_code"
  }'

SSO via Token

curl -X POST https://yourshop.com/store-api/v1/get-user-by-token \
  -H "Content-Type: application/json" \
  -d '{"helloagain_token": "<hello-again-token>"}'

# Returns: {"contextToken": "<shopware_session_token>"}

API References

• hello again API Documentation
• Shopware Store API Authentication

Testing

Unit Tests

Automated PHPUnit tests live in tests/ and cover the plugin's services, listeners, command, and repositories with mocked Shopware dependencies (no database, no Shopware kernel needed).

One-time setup:

composer install --no-security-blocking

The --no-security-blocking flag is required because the plugin pins firebase/php-jwt ^6.0, which has an open advisory on Packagist.

Run the suite:

composer test

With coverage (requires pcov or xdebug PHP extension):

./vendor/bin/phpunit --coverage-html var/coverage --coverage-text

Test layout mirrors src/:

tests/
├── TestCase.php          # Shared base with mock builders (makeDataHelper, fakeOrder, …)
├── Service/
├── Listener/
├── Command/
└── Models/

Manual / End-to-End Testing

For step-by-step manual testing of OAuth login, SSO, and order points award against a real Shopware shop and the hello again API, see TESTING.md.

Postman Collection

A Postman collection is available in docs/postman/ with ready-to-use API requests for:

• OAuth authorization flow
• SSO token validation
• Order export testing
• Headless Store API operations

See docs/postman/README.md for setup instructions.

Releases

Releases are tag-driven and produced by GitLab CI:

./release.sh <plugin-version>      # e.g. ./release.sh 1.8.0

The script reads shopware/core from composer.json to derive the Shopware version, then pushes a tag of the form vX.Y.Z-sw<major>.<minor> (e.g. v1.8.0-sw6.6). The CI on the tag push builds the plugin ZIP and attaches it to a GitLab Release, downloadable from the project's Releases page.

Versioning

Plugin versions are aligned across Shopware branches: the same X.Y.Z is used everywhere a release ships, and the Shopware version lives in the tag suffix (-sw6.5 / -sw6.6 / -sw6.7), not in the plugin version. Bug fixes that only apply to one branch bump only that branch's tag — versions may drift slightly until the next change that ships everywhere realigns them.

Development

Run Order Export Manually:

bin/console helloagain:data-export

Support

• Company: hello again
• Website: https://www.helloagain.com
• Email: info@helloagain.at

Additional Documentation

See CLAUDE.md for detailed technical documentation, architecture overview, and development guidelines.