bfs_manager 0.0.5

A dynamic local SQLite database to server synchronization manager for Flutter applications.

Flutter bfs_manager SDK ઇન્ટિગ્રેશન ગાઇડ

આ દસ્તાવેજમાં Flutter એપ્લિકેશનમાં bfs_manager SDK નું સેટઅપ, યુઝર ઓથેન્ટિકેશન (Register, Login, Social Login) અને ડાયનેમિક સિંક સિસ્ટમ (Push & Pull) નો ઉપયોગ કેવી રીતે કરવો તેની સંપૂર્ણ માહિતી ગુજરાતીમાં આપવામાં આવી છે.

---

૧. પેકેજ ઇન્સ્ટોલેશન (Package Installation)

તમારા Flutter પ્રોજેક્ટના pubspec.yaml ફાઇલમાં bfs_manager પેકેજને આ રીતે ઉમેરો:

dependencies:
  flutter:
    sdk: flutter
  
  # Pub.dev પરથી ડાયરેક્ટ મેળવો
  bfs_manager: ^0.0.5

ત્યારબાદ ટર્મિનલમાં નીચેનો કમાન્ડ રન કરીને ડિપેન્ડન્સી ઇન્સ્ટોલ કરો:

flutter pub get

---

૨. એસડીકે ઇનિશિયલાઇઝેશન (Initialization)

તમારી એપ્લિકેશન શરૂ થાય ત્યારે main.dart ફાઇલમાં main() ફંક્શનની અંદર SDK ને ઇનિશિયલાઇઝ કરો:

import 'package:flutter/material.dart';
import 'package:bfs_manager/bfs_manager.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // ૧. એસડીકે ઇનિશિયલાઇઝ કરો (તમારા લારાવેલ સર્વરના બેઝ યુઆરએલ સાથે)
  await BfsManager().init(
    baseUrl: "https://your-laravel-api-domain.com/api",
  );

  runApp(const MyApp());
}

---

૩. યુઝર ઓથેન્ટિકેશન એપીઆઈ (Authentication APIs)

ઓથેન્ટિકેશન એપીઆઈ સક્સેસ થશે ત્યારે એસડીકે આપમેળે JWT ટોકનને સેવ કરી લેશે અને ભવિષ્યની સિંક રિકવેસ્ટમાં Bearer ટોકન તરીકે મોકલશે.

A. નવું રજીસ્ટ્રેશન (Register)

BfsManager().apiRegister(
  {
    "name": "Ashok Patel",
    "email": "[e-mail]",
    "password": "securepassword123"
  },
  () {
    print("Registration started...");
  },
  (response) {
    if (response['success'] == true) {
      print("Registration successful! Token: ${response['token']}");
    }
  },
  (error) {
    print("Registration failed: $error");
  }
);

B. મેન્યુઅલ લોગિન (Login)

BfsManager().apiLogin(
  {
    "email": "[e-mail]",
    "password": "securepassword123"
  },
  () {
    print("Login started...");
  },
  (response) {
    if (response['success'] == true) {
      print("Login successful! Saved Token.");
    }
  },
  (error) {
    print("Login failed: $error");
  }
);

C. સોશિયલ લોગિન (Google/Apple/Facebook)

જ્યારે યુઝર Google અથવા Apple દ્વારા લોગિન કરે, ત્યારે તેના ડેટા સર્વર પર સબમિટ કરીને ટોકન મેળવવા માટે:

BfsManager().apiSocialLogin(
  {
    "provider": "google",          // અથવા "apple", "facebook"
    "provider_id": "google-user-id-123456",
    "name": "Ashok Patel",
    "email": "[e-mail]",
    "avatar": "https://lh3.googleusercontent.com/avatar-url.png" // વૈકલ્પિક
  },
  () {
    print("Social login started...");
  },
  (response) {
    if (response['success'] == true) {
      print("Social login successful! Token initialized.");
    }
  },
  (error) {
    print("Social login failed: $error");
  }
);

---

૪. ડાયનેમિક સિંક સિસ્ટમ (Push & Pull)

ઓથેન્ટિકેશન કમ્પ્લીટ થયા પછી તમે ડેટા પુશ અને પુલ ઓપરેશન રન કરી શકો છો. ડેટા ફક્ત તે જ યુઝરનો સિંક થશે જે કરન્ટ લોગઇન છે.

A. સર્વર પરથી બધો જ ડેટા ડાઉનલોડ કરવો (Initial Pull All)

જ્યારે યુઝર ફર્સ્ટ ટાઇમ લોગિન કરે ત્યારે બધી સ્કીમા ટેબલનો ડેટા ડાઉનલોડ કરવા માટે:

BfsManager().afterLoginGetAllData(
  ['tb_tasks', 'tb_users'], // જે ટેબલનો ડેટા ડાઉનલોડ કરવો હોય તેની યાદી
  onStart: () {
    print("Initial sync started...");
  },
  onComplete: () {
    print("Initial sync completed successfully!");
  },
  onError: (errorMessage) {
    print("Sync error: $errorMessage");
  }
);

B. લોકલ ફેરફારો સર્વર પર પુશ કરવા (Push Changes)

જ્યારે લોકલ ડેટાબેઝમાં કોઈ નવો રેકોર્ડ ઉમેરાય, અપડેટ થાય અથવા ડિલીટ થાય ત્યારે SDK ઓટોમેટિકલી બેકગ્રાઉન્ડમાં ફાઇલો અને કન્ટેન્ટને સિંક કરે છે:

// બેકગ્રાઉન્ડ સિંક મેન્યુઅલી ટ્રિગર કરવા માટે:
await BfsManager().pushChanges();

• ...ફાઇલ અપલોડ લોજિક: જો ડેટામાં કોઈ કોલમની વેલ્યુ લોકલ ફાઇલ પાથ (દા.ત. /data/user/.../image.jpg) હશે, તો SDK આપમેળે તેને શોધી લેશે અને મલ્ટિપાર્ટ તરીકે અપલોડ કરશે.
• બુલિયન સ્ટેટસ ફિલ્ટર: સર્વર દરેક ઓપરેશનનું સ્ટેટસ બુલિયન (true/false) તરીકે પરત કરશે. SDK ફક્ત true સ્ટેટસ વાળા રેકોર્ડ્સને જ લોકલ ક્યુમાંથી ક્લિયર કરશે.

C. સર્વર પરથી અપડેટ્સ મેળવવા (Incremental Pull)

છેલ્લા સિંક ટાઇમ પછી સર્વર પર થયેલા નવા ફેરફારો લોકલ એપમાં ડાઉનલોડ કરવા માટે:

await BfsManager().pullUpdates();

---

૫. લોકલ ડેટાબેઝ ફેરફારો સિંક ક્યુમાં સેવ કરવા (Saving Local Changes to Sync Queue)

જ્યારે પણ એપ્લિકેશનમાં કોઈ ફેરફાર થાય (Insert, Update કે Delete), ત્યારે તમારે તમારા લોકલ SQLite ડેટાબેઝમાં ડેટા સેવ કરવાની સાથે સાથે BfsManager().insertLocal() નો કોલ કરવાનો રહેશે. આ કમાન્ડ ડેટાને સિંક ક્યુમાં સબમિટ કરીને ઓટો-સિંક ઓપરેશન બેકગ્રાઉન્ડમાં સ્ટાર્ટ કરે છે.

A. નવો રેકોર્ડ ઉમેરવા માટે (Insert Example)

// ૧. યુનિક UUID જનરેટ કરો
final String taskUuid = BfsManager().generateUuid();

final Map<String, dynamic> newTask = {
  "uuid": taskUuid,
  "title": "Complete dynamic files test",
  "status": "pending",
  "image_path": "/data/user/0/com.example/cache/test_img.png", // લોકલ ફાઇલ પાથ
  "pdf_path": null
};

// A. આ ડેટાને તમારા લોકલ એપ્લિકેશન ડેટાબેઝ ટેબલમાં સેવ કરો
await myLocalDatabase.insertRow("tb_tasks", newTask);

// B. આ ડેટા સિંક ક્યુમાં ઉમેરી સર્વર સાથે સિંક કરાવવા માટે કોલ કરો
await BfsManager().insertLocal(
  tableName: "tb_tasks",
  status: "insert", // ઓપરેશન 'insert' સેટ કરો
  data: newTask,
);

B. રેકોર્ડ અપડેટ કરવા માટે (Update Example)

final Map<String, dynamic> updatedTask = {
  "uuid": "task-uuid-1111", // જે રેકોર્ડ અપડેટ કરવો હોય તેનો સાચો UUID
  "status": "completed",
  "title": "Updated task title"
};

// A. તમારા લોકલ એપના ડેટાબેઝમાં અપડેટ કરો
await myLocalDatabase.updateRow("tb_tasks", updatedTask);

// B. સિંક ક્યુમાં અપડેટ નોંધીને બેકગ્રાઉન્ડ સિંક શરૂ કરવા કોલ કરો
await BfsManager().insertLocal(
  tableName: "tb_tasks",
  status: "update", // ઓપરેશન 'update' સેટ કરો
  data: updatedTask,
);

C. રેકોર્ડ ડિલીટ કરવા માટે (Delete Example)

final String deleteUuid = "task-uuid-1111"; // જે ટાસ્ક ડિલીટ કરવો હોય તેની આઈડી

// A. લોકલ એપ્લિકેશન ડેટાબેઝમાંથી રેકોર્ડ ડિલીટ કરો
await myLocalDatabase.deleteRow("tb_tasks", deleteUuid);

// B. સર્વરને જાણ કરવા માટે સિંક ક્યુમાં ડિલીશન પેલોડ મોકલો
await BfsManager().insertLocal(
  tableName: "tb_tasks",
  status: "delete", // ઓપરેશન 'delete' સેટ કરો
  data: {
    "uuid": deleteUuid // ફક્ત UUID પાસ કરવું ફરજિયાત છે
  },
);

---

૬. લારાવેલ ડાયનેમિક સ્કીમા કન્ફિગરેશન (સંદર્ભ)

તમારા લારાવેલ કંટ્રોલરમાં સ્કીમા ડાયનેમિકલી જનરેટ થાય છે અને કઈ કોલમ nullable (ખાલી રહી શકે તેવી) કે required (ફરજિયાત) રાખવી તે પાઇપલાઇન | થી સેટ થાય છે:

protected array $schema = [
    'tb_tasks' => [
        'uuid'       => 'string',
        'title'      => 'string|required', // NOT NULL
        'status'     => 'string|required', // NOT NULL
        'image_path' => 'string|nullable', // NULL (વૈકલ્પિક ફાઇલ)
        'pdf_path'   => 'string|nullable', // NULL (વૈકલ્પિક ફાઇલ)
    ],
];

જો ડેટાબેઝમાં આ ટેબલ્સ બનેલા નહીં હોય, તો SDK પહેલી રિકવેસ્ટ વખતે જ આપમેળે આ માળખા મુજબ ડેટાબેઝ ક્રિએટ કરી દેશે.