README

English | 中文

A comprehensive Symfony bundle for integrating Jiguang (JPush) push notification service. It provides complete account management, device registration, tag grouping, and flexible push message delivery with support for multiple platforms.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Configuration
• API Reference
• Documentation
• Security
• Contributing
• License

Features

• Multi-Account Management: Support for multiple Jiguang push accounts with separate configurations
• Device Registration: Automatic device registration and management with alias support
• Tag Grouping: Flexible tag-based device grouping for targeted push notifications
• Flexible Audience Targeting: Support for all, tag, alias, registrationId, and segment targeting
• Rich Push Types: Support for both notification and message push types
• Platform Support: Full support for iOS, Android, QuickApp, and HMS platforms
• Embedded Entities: Advanced push features with options, callback, and live activity support
• Symfony Integration: Deep integration with Symfony framework and Doctrine ORM
• Event System: Event-driven architecture with push lifecycle management
• HTTP Client Integration: Built-in HTTP client with automatic authentication

Requirements

• PHP >= 8.1
• Symfony >= 6.4
• Doctrine ORM >= 3.0

Installation

Install via Composer

composer require tourze/jiguang-push-bundle

Bundle Registration

If you're not using Symfony Flex, add the bundle to your config/bundles.php:

<?php
// config/bundles.php
return [
    // ...
    JiguangPushBundle\JiguangPushBundle::class => ['all' => true],
];

Database Migration

Create and run the database migration:

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

Quick Start

1. Create Push Account

First, create a Jiguang push account in your database:

<?php

use JiguangPushBundle\Entity\Account;

$account = new Account();
$account->setTitle('My App Push Account');
$account->setAppKey('your-app-key-from-jiguang');
$account->setMasterSecret('your-master-secret-from-jiguang');
$account->setValid(true);

$entityManager->persist($account);
$entityManager->flush();

2. Register Device

Register user devices for push notifications:

<?php

use JiguangPushBundle\Entity\Device;

$device = new Device();
$device->setAccount($account);
$device->setRegistrationId('device-registration-id');
$device->setAlias('user-alias');
$device->setMobile('13800138000');

$entityManager->persist($device);
$entityManager->flush();

3. Send Push Notification

Send a simple notification:

<?php

use JiguangPushBundle\Entity\Push;
use JiguangPushBundle\Entity\Embedded\Audience;
use JiguangPushBundle\Entity\Embedded\Notification;
use JiguangPushBundle\Enum\PlatformEnum;
use JiguangPushBundle\Request\PushRequest;
use JiguangPushBundle\Service\JiguangService;

// Create push entity
$push = new Push();
$push->setAccount($account);
$push->setPlatform(PlatformEnum::ALL);

// Configure audience
$audience = new Audience();
$audience->setAll(true);
$push->setAudience($audience);

// Configure notification
$notification = new Notification();
$notification->setAlert('Hello from Jiguang!');
$notification->setTitle('Welcome');
$push->setNotification($notification);

// Send push
$request = new PushRequest();
$request->setAccount($account);
$request->setMessage($push);

$service = $container->get(JiguangService::class);
$result = $service->request($request);

4. Advanced Usage

Send targeted push with tags:

<?php

use JiguangPushBundle\Entity\Embedded\Audience;
use JiguangPushBundle\Entity\Embedded\AndroidNotification;
use JiguangPushBundle\Entity\Embedded\IosNotification;

// Create audience with tags
$audience = new Audience();
$audience->setTag(['vip', 'premium']);
$push->setAudience($audience);

// Platform-specific notifications
$androidNotification = new AndroidNotification();
$androidNotification->setTitle('Android Title');
$androidNotification->setBuilderId(1);

$iosNotification = new IosNotification();
$iosNotification->setSound('default');
$iosNotification->setBadge(1);

$notification = new Notification();
$notification->setAlert('Cross-platform notification');
$notification->setAndroid($androidNotification);
$notification->setIos($iosNotification);

$push->setNotification($notification);

Configuration

Service Configuration

The bundle automatically configures the JiguangService. You can customize it in your config/services.yaml:

services:
    JiguangPushBundle\Service\JiguangService:
        # Custom configuration if needed

Entity Relationships

The bundle provides the following main entities:

• Account: Jiguang push account configuration
• Device: User device registration information
• Tag: Device grouping tags
• Push: Push message entity with full configuration

API Reference

Main Classes

• JiguangPushBundle\Service\JiguangService - Main service for sending push notifications
• JiguangPushBundle\Request\PushRequest - Push request wrapper
• JiguangPushBundle\Entity\Push - Push message entity
• JiguangPushBundle\Entity\Account - Account configuration entity
• JiguangPushBundle\Entity\Device - Device registration entity

Event System

The bundle dispatches events during push operations:

• JiguangPushBundle\Event\PushEvent - Fired when push is sent

Documentation

For detailed documentation, see:

• Entity Design - Database schema and entity relationships
• Workflow - Push notification workflow
• Jiguang API Documentation

Security

If you discover any security related issues, please email security@tourze.cn instead of using the issue tracker.

Security Best Practices

• Store Jiguang credentials securely using environment variables
• Validate all input data before creating push notifications
• Use HTTPS for all API communications
• Regularly rotate API keys and credentials
• Monitor push activities and implement rate limiting

Contributing

Please see CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

The MIT License (MIT). Please see License File for more information.