DOCSEARCHbyAlgolia
Submit Docs

Uni-Push Documentation

website·Indexed 33 days ago

https://unipushd.singee.me/

An open-source push notification system supporting one-to-one and group pushes with configurable delays and modifiers. Includes API specifications for service management and a guide covering accounts, services, and presets.

Tokens
2K
Snippets
9
Records
12
Agent score
50%

What's inside Uni-Push

  1. Overview of Uni-Push features

    Uni-Push is an open-source push notification tool designed for simplicity and flexibility. Key capabilities include:

    • Easy Configuration: Simple setup with support for various common services.
    • Push Options: Supports one-to-one and group-based push notifications.
    • Advanced Controls: Ability to set delivery delays and use flexible modifiers to modify parameters externally.
    • Open Source: Being open-source, it ensures privacy and allows users to extend the functionality according to their specific needs.

  2. Understand Uni-Push core concepts

    Uni-Push uses a hierarchical system to manage push notifications:

    • Account: A user account linked to a single email address.
    • Service: An official Uni-Push application capable of receiving pushes. All pushers eventually route to a Service.
    • Pusher: The fundamental unit used for API push requests. A Pusher can be a Service, a Preset, or a Group.
    • Preset: A Pusher based on an existing Pusher with added or overridden parameters.
    • Group: A Pusher composed of multiple other Pushers. Groups can also add or override parameters for the Pushers they contain.

  3. Self-host the Uni-Push Backend

    The Uni-Push Backend is built with Django, PostgreSQL 11, Redis 5, and Celery.

    Setup Steps:

    1. Clone Repository: Clone the code into a folder named unipush.
    2. Environment Setup: Create a Python 3.7 virtual environment, activate it, and install dependencies.
    3. Infrastructure: Start PostgreSQL and Redis (can be done via the provided docker-compose.yml for local testing).
    4. Configuration: Copy config.example.ini to config.ini and update connection strings if not using the provided Docker setup.
    5. Database Migration: Run the Django migration command.
    6. Execution: Start the Celery worker and the Django server.
    # 1. Clone
git clone https://github.com/ImSingee/uni-push-backend unipush
cd unipush

# 2. Environment
virtualenv --python=3.7 venv
source venv/bin/activate
pip install -r requirements.txt

# 3. Infrastructure (Local Debugging)
docker-compose up -d

# 5. Migrate
./manage.py migrate

# 6. Run Celery
./run-celery.sh
# OR manually: celery -A unipush worker -l info

# 6. Run Django
./manage.py runserver

  4. Use parameter modifiers for dynamic push content

    Modifiers allow you to replace placeholders in predefined parameters with dynamic values provided during an API request.

    1. Define Placeholders: In a Preset's predefined parameters, use strings like <_0>, <_1>, etc.
    2. Request Replacement: Use the naming convention _parameterName_index in the API query string to replace the corresponding placeholder.

    For example, if a Preset defines:

    • content: "Test<_0>haha"
    • title: "Something<_1> Others"

    A request to /push/PusherID/?_content_0=CONTENT&_title_1=TITLE results in:

    • content: "TestCONTENThaha"
    • title: "SomethingTITLE Others"

    Key Rules:

    • The index after the underscore must be a number.
    • Modifier parameters have higher priority than ordinary parameters.
    • _something can be used as a shorthand for _something_0 (except for the reserved _token).
    • The redefine_content configuration in a Preset can map the URL path content to a modifier.
    // Predefined parameters in Preset
{
  "content": "Test<_0>haha",
  "title": "Something<_1> Others"
}

    // API Request GET /push/PusherID/?_content_0=CONTENT&_title_1=TITLE

  5. Send a push notification

    Trigger a push notification using the /push/:pusher_id/[:content]/ endpoint.

    Parameters:

    • pusher_id (Required): The ID of the pusher.
    • content (Optional): A shortcut parameter in the URL. By default, it overrides the content field in the payload. This can be changed via the redefine_content configuration in a Preset or Group.

    Parameter Priority (Highest to Lowest):

    1. POST request body
    2. URL :content parameter
    3. GET query parameters
    4. Preset predefined parameters
    5. Service predefined parameters

    Scheduling/Delay:

    • delay: Delay in seconds (max 86,400s / 1 day).
    • at: Specific execution time in YYMMDDhhmm format (max 7 days delay). Use YYMMDDhhmm.UTC for UTC time; otherwise, it defaults to GMT+8.
    GET|POST /push/:pusher_id/[:content]/

  6. Configure parameter mapping in Uni-Push Groups

    When using a Group Pusher, modifiers follow the format groupName.groupParameter. You can use Parameter Mapping to simplify API requests by mapping a single external parameter to multiple internal Pusher modifiers.

    Example Scenario: Sending a balance notification to two different services (Service-1 via Preset-1 and Service-2 via Preset-2) where one requires a title and the other a content field.

    Configuration:

    1. Pushers Configuration: Define the placeholders in the base pushers.
    2. Parameter Mapping: Map an external key (e.g., amount) to the specific modifiers of the group members.

    With this setup, a request to /push/G/?amount=10 will automatically distribute the value 10 to the mapped modifiers of all members in the group.

    // Pushers Configuration
[
  {
    "name": "p1",
    "base_pusher": "Preset-1",
    "params": { "title": "Balance: <_0> USD" }
  },
  {
    "name": "p2",
    "base_pusher": "Preset-2",
    "params": { "content": "Balance: <_0> USD" }
  }
]

// Parameter Mapping Configuration
{
  "amount": [
    "p1._title",
    "p2._content"
  ]
}

  7. Activate a user account

    Activate a user account using the confirmation token. Users must be activated within 24 hours of registration or their data will be deleted.

    Admin Override: Admins can force-activate a user by setting the confirm_token to force.

    GET /account/user/confirm/:confirm_token/

  8. UniPushD API General Conventions

    All UniPushD API requests follow these conventions:

    URL Structure:

    • Parameters in the URL are denoted by a colon (e.g., :parameter).
    • Optional parameters are enclosed in square brackets (e.g., [:optional]).
    • All request URLs must end with a trailing slash /.

    Request Body:

    • POST requests support application/json and application/x-www-form-urlencoded. The Content-Type header must be explicitly set.

    Response Body:

    • success (bool): Indicates if the request was successful.
    • code (string): "0" indicates success; other values indicate failure. Use code for error handling logic rather than the message.
    • message (string): The reason for failure.
    • data (variable): The result of the request or detailed error information.

  9. Create a user account with invitation code

    Create a new user account using a valid invitation code.
    POST /account/user/create/

Body:
{
  "code": "INVITATION_CODE",
  "email": "user@example.com",
  "password": "secure_password"
}

  10. Authenticate user and obtain token

    Login to the system to retrieve a user token.
    POST /account/user/login/

Body:
{
  "email": "user@example.com",
  "password": "secure_password"
}

  11. Generate invitation codes

    Generate invitation codes using the /account/invite/:type/ endpoint. The :type parameter determines the generation logic:

    1. Auto (type=auto): Generates a single code for a specific email.

    • Required POST param: limit_email (The email allowed to use the code).
    • Optional POST param: recaptcha_response (Required if Google Recaptcha is enabled).

    2. Referer (type=referer): Requires authorization. Used by verified users to invite others.

    • Optional POST params: quantity (default 1), limit_email (if set, quantity is forced to 1).

    3. Admin (type=admin): Requires Admin authorization.

    • Optional POST params: times (usage limit, default 1), quantity (number of codes, default 1). Note: times and quantity cannot be used together. Also supports limit_email, valid_time (seconds), and source.
    POST /account/invite/:type/

  12. Cancel a pending push task

    Cancel a push task using the task ID returned from the Push API.

    Constraints:

    • Only tasks that are currently 'waiting' can be cancelled. Tasks already running or completed cannot be revoked.
    • For Group pushes, multiple tasks are created; each must be cancelled individually.
    • The API currently returns success regardless of whether the task existed or was successfully cancelled.
    • Note: Permission restrictions are currently unimplemented; any user with the task_id can cancel the task.
    GET /revoke/task/:task_id/