Background Preferences

Manage user's background settings including updating background preferences and handling custom backgrounds. The background system supports both predefined backgrounds and custom user-uploaded backgrounds.

Get Current Background

Retrieve the user's current background settings. This endpoint returns information about the active background including its type, URLs, and whether it's a custom background.

Endpoint

Method: GET
URL: /api/background

Request Headers

Header	Value	Required
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Query Parameters

Parameter	Type	Required	Description
background_type	string	Yes	Type of backgrounds to fetch. Must be one of: `dark`, `light`, `custom`
perPage	integer	No	Number of items per page for pagination

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "name": "Peaceful Garden",
                "image_url": "https://example.com/backgrounds/peace.jpg",
                "width": 1920,
                "height": 1080,
                "color_theme": "#2E7D32",
                "background_opacity": 0.8,
                "is_vip": false,
                "can_access": true
            }
        ],
        "first_page_url": "http://127.0.0.1:8000/api/backgrounds?background_type=light&page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://127.0.0.1:8000/api/backgrounds?background_type=light&page=1",
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/backgrounds?background_type=light&page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "active": false
            }
        ],
        "next_page_url": null,
        "path": "http://127.0.0.1:8000/api/backgrounds",
        "per_page": 10,
        "prev_page_url": null,
        "to": 1,
        "total": 1
    },
    "status_code": 200
}

Error Response

Unauthorized (401)

{
    "success": false,
    "message": "Unauthenticated",
    "data": null,
    "status_code": 401
}

Validation Error (422)

{
    "success": false,
    "message": "نوع الخلفية يجب أن يكون واحداً من: dark, light, custom",
    "data": null,
    "status_code": 422
}

Update Background

Update the user's current background settings. This endpoint allows users to switch between available backgrounds, including both predefined and custom backgrounds.

Endpoint

Method: PATCH
URL: /api/background

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Request Body

Parameter	Type	Required	Description
background_id	integer	Yes	ID of the background to set as active

{
    "background_id": 1
}

Success Response

{
    "success": true,
    "message": "تم تحديث البيانات بنجاح",
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "avatar": "https://example.com/avatars/john.jpg",
        "is_using_apple_private_relay_email": false,
        "is_app_rated": true,
        "is_subscribed": false,
        "is_app_rated_reminder": true,
        "profile": {
            "date_of_birth": "1990-01-01",
            "age": 33,
            "gender": "male",
            "phone": "555555555",
            "country_phone_code": "+966",
            "letter_intention_index": 1,
            "language_app": "ar",
            "language_affirmation": "ar",
            "profile_progress": 80,
            "marital_status": "single",
            "background_type": "LIGHT",
            "custom_background": {
                "id": 2,
                "name": "Custom Background",
                "image_url": "https://example.com/backgrounds/custom/user_1.jpg",
                "width": 1920,
                "height": 1080,
                "color_theme": "LIGHT",
                "background_opacity": "0.8"
            },
            "reminders_per_day": 3,
            "start_time": "08:00:00",
            "end_time": "22:00:00",
            "start_time_human": "08:00 AM",
            "end_time_human": "10:00 PM",
            "check_if_need_to_update_intention": false
        },
        "nationality": {
            "id": 1,
            "name": "Saudi"
        },
        "intention": {
            "id": 1,
            "name": "Self Development"
        },
        "country": {
            "id": 1,
            "name": "Saudi Arabia"
        },
        "incomeLevel": {
            "id": 2,
            "name": "10,000 - 20,000"
        },
        "educationalLevel": {
            "id": 3,
            "name": "Bachelor's Degree"
        },
        "interests": [
            {
                "id": 1,
                "name": "Reading"
            },
            {
                "id": 2,
                "name": "Writing"
            }
        ],
        "hobbies": [
            {
                "id": 1,
                "name": "Photography"
            }
        ],
        "devices": [
            {
                "device_id": "device_123",
                "is_Expired": false
            }
        ]
    },
    "status_code": 200
}

Error Responses

Background Not Found (404)

{
    "success": false,
    "message": "Background not found",
    "data": null,
    "status_code": 404
}

Validation Error (422)

{
    "success": false,
    "message": "القيمة المحددة background id غير موجودة.",
    "data": null,
    "status_code": 422
}

Upload Custom Background

Allows users to upload their own custom background images. The endpoint supports various image formats and provides options to customize the background appearance through color themes and opacity settings. The uploaded image will be automatically optimized and a thumbnail will be generated (except for GIF files which remain unchanged).

Image Requirements

Supported formats: PNG, JPG, JPEG, GIF
Maximum file size: 3MB (3072KB)
Image will be automatically optimized for better performance
Thumbnails will be generated for non-GIF images

Endpoint

Method: POST
URL: /api/background/custom

Request Headers

Header	Value	Required
Content-Type	multipart/form-data	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Request Body

Parameter	Type	Required	Description
color_theme	string	Yes	Theme color for the background. Must be one of: `DARK`, `LIGHT`. This affects how the app's text and UI elements will be displayed over the background.
background_opacity	string	Yes	Controls the opacity/transparency of the background image. Must be one of: `0`, `0.1`, `0.2`, `0.3`, `0.4`, `0.5`, `0.6`, `0.7`, `0.8`, `0.9`, `1.0`. A lower value makes the background more transparent.
image	File	Yes	The image file to be used as background. Must be PNG, JPG, JPEG, or GIF format, max 3MB size.

Success Response

{
    "success": true,
    "message": "تم رفع الخلفية المخصصة بنجاح",
    "data": {
        "id": 2,
        "name": "Custom Background",
        "image_url": "https://example.com/backgrounds/custom/user_1.jpg",
        "width": 1920,
        "height": 1080,
        "color_theme": "LIGHT",
        "background_opacity": "0.8"
    },
    "status_code": 201
}

Error Responses

Validation Error (422)

{
    "success": false,
    "message": "الرجاء اختيار ملف صورة بحجم أقل من 3 ميجابايت",
    "data": null,
    "status_code": 422
}

Invalid File Type (422)

{
    "success": false,
    "message": "الرجاء اختيار ملف بامتداد png, jpg, jpeg, gif",
    "data": null,
    "status_code": 422
}

Invalid Color Theme (422)

{
    "success": false,
    "message": "الرجاء اختيار لون الخلفية من: DARK, LIGHT",
    "data": null,
    "status_code": 422
}

Invalid Background Opacity (422)

{
    "success": false,
    "message": "الرجاء اختيار قيمة شفافية الخلفية من: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0",
    "data": null,
    "status_code": 422
}

Delete Custom Background

Delete a previously uploaded custom background. This endpoint permanently removes the custom background and its associated files from the system.

Endpoint

Method: DELETE
URL: /api/background/custom/{id}

URL Parameters

Parameter	Type	Required	Description
id	integer	Yes	ID of the custom background to delete

Request Headers

Header	Value	Required
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Success Response

{
    "success": true,
    "message": "تم حذف الخلفية المخصصة بنجاح",
    "data": null,
    "status_code": 200
}

Error Responses

Unauthorized (401)

{
    "success": false,
    "message": "Unauthenticated",
    "data": null,
    "status_code": 401
}

Not Found (404)

{
    "success": false,
    "message": "Custom background not found",
    "data": null,
    "status_code": 404
}

Cannot Delete Active Background (422)

{
    "success": false,
    "message": "لا يمكن حذف الخلفية النشطة",
    "data": null,
    "status_code": 422
}

Example Implementation Flow

Get Current Background

Get the user's API token from storage
Set required query parameters:
- Choose background_type (dark/light/custom)
- Set perPage if needed for pagination
Make GET request to /api/background
Upon success:
- Update UI with the background image
- Cache the background URL for offline use
- Update color theme and opacity settings
- Check VIP access status
Upon error:
- If unauthorized (401), redirect to login
- If validation fails (422), check background_type value
- Use default background as fallback
- Display appropriate error message

Update Background

Get the user's API token from storage
Validate background ID exists and is accessible
Make PATCH request to /api/background
Upon success:
- Update UI with new background
- Update local cache
- Show success message
Upon error:
- If background not found (404), show error
- If unauthorized (401), redirect to login
- If validation fails (422), show specific error
- Maintain current background

Upload Custom Background

Get the user's API token from storage
Validate image file:
- Check file type (jpg, png)
- Verify file size (max 5MB)
- Check image dimensions
Make POST request to /api/background/custom
Upon success:
- Display the new custom background
- Add to user's custom backgrounds list
- Show success message
Upon error:
- If file too large, show size limit message
- If invalid type, show supported formats
- If upload fails, maintain current state

Delete Custom Background

Get the user's API token from storage
Confirm deletion with user
Make DELETE request to /api/background/custom/{id}
Upon success:
- Remove background from custom list
- If current background was deleted, switch to default
- Show success message
Upon error:
- If background is active, show warning
- If not found (404), refresh list
- If unauthorized (401), redirect to login

Get Current Background​

Endpoint​

Request Headers​

Query Parameters​

Success Response​

Error Response​

Unauthorized (401)​

Validation Error (422)​

Update Background​

Endpoint​

Request Headers​

Request Body​

Success Response​

Error Responses​

Background Not Found (404)​

Validation Error (422)​

Upload Custom Background​

Image Requirements​

Endpoint​

Request Headers​

Request Body​

Success Response​

Error Responses​

Validation Error (422)​

Invalid File Type (422)​

Invalid Color Theme (422)​

Invalid Background Opacity (422)​

Delete Custom Background​

Endpoint​

URL Parameters​

Request Headers​

Success Response​

Error Responses​

Unauthorized (401)​

Not Found (404)​

Cannot Delete Active Background (422)​

Example Implementation Flow​

Get Current Background​

Update Background​

Upload Custom Background​

Delete Custom Background​

Get Current Background

Endpoint

Request Headers

Query Parameters

Success Response

Error Response

Unauthorized (401)

Validation Error (422)

Update Background

Endpoint

Request Headers

Request Body

Success Response

Error Responses

Background Not Found (404)

Validation Error (422)

Upload Custom Background

Image Requirements

Endpoint

Request Headers

Request Body

Success Response

Error Responses

Validation Error (422)

Invalid File Type (422)

Invalid Color Theme (422)

Invalid Background Opacity (422)

Delete Custom Background

Endpoint

URL Parameters

Request Headers

Success Response

Error Responses

Unauthorized (401)

Not Found (404)

Cannot Delete Active Background (422)

Example Implementation Flow

Get Current Background

Update Background

Upload Custom Background

Delete Custom Background