=============================================
B4j - AdFusion – Advertising Server
=============================================


#############################################
IMPORTANT – PLEASE READ

The local SQLite database already includes:
• 5 preloaded banner ads
• 1 preloaded fullscreen ad

Each ad contains an image_url that looks like this:
http://localhost:3000/uploads/[IMAGE_NAME]

This works ONLY when the client is running on the same computer 
as the server (for example, B4J desktop apps or web clients).

However, this WILL NOT work on B4A (Android) or B4i (iOS) apps.

Why?
Because “localhost” always points to the device itself.
On a phone, localhost means “the phone”, not your PC.

To make images load correctly on mobile devices, you MUST replace
“localhost” with the actual IP address of the computer running the server.

Example:
If your PC’s IP is 10.0.0.9, change:
http://localhost:3000/uploads/image.png
to:
http://10.0.0.9:3000/uploads/image.png

#############################################


AdFusion is a simple, fast, cross‑platform advertising server built with B4J.  
It provides a dashboard, analytics, impressions and click tracking, and a clean API  
that works with B4A, B4i, B4J, and Web clients.

Folder Structure:

server/
  ├── additional files/
  │      ├── jars/
  │      ├── db/
  │      └── stop server/
  └──  AdFusion Server/
         └── Objects/
         		├── www/
         		├── adfusion.db
         		├── config_local.json
         		└── config_server.json

clients/
  ├── B4X/
  │      ├── B4A/
  │      ├── B4i/
  │      └── B4J/
  └──  Web/
		 └── NodeJS/


--------------------------------------------------
1. Requirements
--------------------------------------------------

- Java 11 or newer 
- JDK-19.0.2
- B4J 10.3+ 
- MySQL or/and SQLite
- HeidiSQL/DB Browser (optional, for database management)
- Visual Studio Code (optional, HTML, CSS, JS editor)

1.1 Required Libraries:

- BCrypt (jar included in Server/additional files/jars)
- jCore
- jServer
- jSon
- jSql

#AdditionalJar: sqlite-jdbc-3.7.2 					(jar included in Server/additional files/jars)
#AdditionalJar: mysql-connector-java-5.1.47-bin 	(jar included in Server/additional files/jars)


--------------------------------------------------
2. Installation
--------------------------------------------------

2.1 Import the database structure  
   Use HeidiSQL (or any MySQL tool) to run the file:
   database.sql

   This will create the required tables:
   - users
   - promo_ads
   - my_apps
   - impressions
   - clicks

2.2 Run the B4J server  
   Open the project in B4J and run the Main module.

   The server will start on:
   http://localhost:3000/

2.3 Access the dashboard  

   http://localhost:3000/dashboard

--------------------------------------------------
3. Default Login
--------------------------------------------------

Use the default admin account to log in:

Username: admin  
Password: 1234

For production use, make sure to change the default admin password.

You can change this later in the "users" table.

--------------------------------------------------
4. API Usage
--------------------------------------------------

4.1 Fetch an Ad  

GET /api/banner			returns a banner‑sized ad (see API Documentation for filters setup)
GET /api/fullscreen 	returns a fullscreen interstitial ad (see API Documentation for filters setup)

Example response:
{
  "id": 12,
  "ad_type": "banner",
  "title": "Super Sale!",
  "subtitle": "Up to 50% off",
  "image_url": "http://yourserver.com/banner12.png",
  "click_url": "https://example.com",
  "bg_color": "#ffffff",
  "text_color": "#000000",
  "priority": 3,
  "apps": "b4a,b4i",
  "filter_id": "",
  "not_allowed_ids": ""
}

4.2 Register a Click  

POST /api/click  

id=12&app_id=b4a

Response:
{
  "status": "ok",
  "message": "click registered"
}

--------------------------------------------------
5. Client Integration
--------------------------------------------------

5.1 Fetching an Ad (B4A/B4i/B4J)

Dim j As HttpJob
j.Initialize("", Me)
j.Download($"${api_domain}/api/banner?token=${app_token}"$)

5.2 Registering a Click

Dim j As HttpJob
j.Initialize("", Me)
Dim data As String = $"id=${id}&app_id=${app_token}"$
j.PostString($"${api_domain}/api/click"$, data)
j.GetRequest.SetContentType("application/x-www-form-urlencoded")
j.Release

--------------------------------------------------
6. Dashboard
--------------------------------------------------

The dashboard allows you to:

- API Documentation
- Add/Edit/Delete -> Ads  
- Add/Delete -> Users  
- Add/Delete -> Apps  
- View Statistics (impressions and clicks)
- Profile Page 
- See Server Status (admin only!) 

URL:
http://localhost:3000/dashboard

--------------------------------------------------
7. Configuration
--------------------------------------------------

You can modify server settings in the Main module:

- Server port  
- Database connection  (Config Files)

7.1 Switch between 3 Configuration options:

- local				(used for local development SQLite)
- server_local 		(server must run on same pc as sql db)
- server_remote 	(server can connect from remote pc to sql db)

7.2 Update Config Files for SQL Settings:

(Files available inside DirApp Folder)

- config_local.json		(for Local Connection)
- config_server.json 	(for Remote Connection)

7.3 Use Table Create Queries to create the tables

(txt files included in Server/additional files/db)

- ad_stats_summary
- clicks
- impressions
- my_apps
- promo_ads
- users

--------------------------------------------------
8. Testing
--------------------------------------------------

You can test API endpoints using

Endpoint List:

	/api/status
	/api/shutdown
	/api/checksession
	/api/login
	/api/logout
	/api/profile
	/api/ads/list
	/api/addad
	/api/ads/update
	/api/ads/delete	
	/api/stats/aggregate
	/api/uploadimg
	/api/stats
	/api/apps/list
	/api/apps/add
	/api/apps/delete
	/api/users/add
	/api/users/list
	/api/users/delete	
	/api/banner
	/api/fullscreen	
	/api/click
	
-----------------------------------------
9. Stopping the Server
-----------------------------------------

If the server is running in the background or was started without the B4J IDE, you can stop it using the included *stop.bat* script.

This script automatically finds any process listening on port *3000* and terminates it.

** For Windows Server:
_____________________________

@echo off
for /f "tokens=5" %%a in ('netstat -ano ^| find ":3000" ^| find "LISTENING"') do (
    echo Killing PID %%a
    taskkill /PID %%a /F
)
_____________________________

** For Linux servers, you can stop the server using:
_____________________________

kill -9 $(lsof -t -i:3000)
_____________________________

1. Double‑click *Server/additional files/stop server/stop.bat*, or  
2. Run it from a command prompt inside the server folder.

This will immediately close all processes running on port 3000, including the AdFusion server.

--------------------------------------------------
10. License
--------------------------------------------------

MIT License

Copyright (c) 2026 [Your Name]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights  
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
copies of the Software, and to permit persons to whom the Software is  
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in  
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER  
DEALINGS IN THE SOFTWARE.

--------------------------------------------------
11. Version History
--------------------------------------------------

See VERSION_HISTORY.txt for release notes.

-----------------------------------------
END OF FILE
-----------------------------------------