1. برنامه IntelliJ IDE را باز کنید.
   از منوی باز شده، روی Create New Project کلیک کنید.

   

   یا از طریق File > New > Project یک پروژه جدید ایجاد کنید.
2. از میان گزینه‌های ساخت پروژه جدید، appsan را انتخاب کرده و روی Next کلیک کنید.

   

3. برای پروژه جدید، نام مناسب انتخاب کرده و روی Finish کلیک کنید.

   

4. پروژه‌ای مشابه ساختار زیر ساخته خواهد شد:

   

از منو فایل، Settings را انتخاب کنید:

در پنجره باز شده، به Languages & Frameworks > Appsan مراجعه کرده و آدرس پوشه SDK دانلود شده را در قسمت Path to SDK وارد نمایید:

برای اجرای مینی‌اپ، در قسمت Run Config در بالا سمت راست IntelliJ روی Add Configuration یا Edit Configuration کلیک کنید. در پنجره باز شده، روی + زده و Appsan را انتخاب نمایید.

سپس نام موردنظر برای اجرا و فایل اجرایی را انتخاب کنید. Run type را روی Web قرار دهید.

پس از اجرای پروژه، آدرس وب نمایش داده شده در کنسول را کپی کرده و در مرورگر باز کنید.

برای ارتباط با دستگاه‌های اندرویدی، Android Platform Tools را دانلود کرده و پوشه platform-tools را در مسیر libs/bin/ جایگزین نمایید.

۵) خطاهای احتمالی

در این قسمت به احتمال زیاد با این خطای رایج مواجه می‌شوید: Project has no JDK configuration

برای رفع این مشکل، در پنجره تنظیمات بخش Project باید نسخه SDK را انتخاب کنید. نسخه Java 11 یا بالاتر را برگزینید و در صورت عدم وجود، روی Add کلیک کنید تا به‌صورت خودکار دانلود شود.

اپسان برخی از رخدادها و خطاها را به صورت log نمایش می‌دهد. یکی از این موارد، درخواست‌های وب است که متن ارسالی و پاسخ دریافتی آن داخل لاگ قابل مشاهده است.

دسترسی به لاگ‌ها از طریق CLI

برای دسترسی به لاگ‌ها، دستور زیر را اجرا کنید (به جای <device-id>، شناسه دستگاه خود را قرار دهید):

java -jar libs/Appsan-CLI-1.0-SNAPSHOT.jar logs -d <device-id>

برای به‌دست آوردن شناسه دستگاه اندرویدی خود، ابتدا این دستور را اجرا کنید:

java -jar libs/Appsan-CLI-1.0-SNAPSHOT.jar devices

پس از اجرای دستور logs، می‌توانید لاگ‌ها را در آدرس http://localhost:12982/logs/ در مرورگر دلخواه خود مشاهده کنید:

دسترسی به لاگ‌ها در IntelliJ IDEA

برای تنظیم اجرای لاگ‌ها در IntelliJ، از منوی اجرا Edit Configurations را باز کنید:

روی دکمه + کلیک کرده و JAR Application را انتخاب کنید:

در قسمت Name نام موردنظر را وارد کنید و در Path to JAR مسیر فایل Appsan-CLI-1.0-SNAPSHOT.jar را انتخاب نمایید. سپس در بخش Program arguments دستور زیر را وارد کنید:

logs -d <device-serial>

که <device-serial> همان شناسه دستگاه است که پیش‌تر از CLI دریافت کردید.

حالا با اجرای پیکربندی logs در IntelliJ، لاگ‌ها در مرورگر نمایش داده می‌شوند.

در این راهنما، نحوه افزودن یک پروژه وب به پروژه Appsan به صورت گام‌به‌گام توضیح داده می‌شود. با استفاده از این راهنما، شما می‌توانید پروژه‌های وب خود را به‌طور مؤثری درون Appsan ادغام کرده و از قابلیت‌های جدید عنصر web-page بهره‌مند شوید.

۱. ایجاد پوشه‌های مورد نیاز

1. ایجاد پوشه web:
   • در مسیر اصلی پروژه Appsan، پوشه‌ای به نام web ایجاد کنید.
   • این پوشه حاوی کد منبع پروژه‌های وب شما خواهد بود.
2. ایجاد پوشه webdist:
   • در کنار پوشه web، پوشه‌ای به نام webdist ایجاد کنید.
   • این پوشه فایل‌های ساخته‌شده (build) پروژه‌های وب شما را نگهداری می‌کند.

۲. اضافه کردن پروژه وب به پوشه web

1. ایجاد پوشه برای پروژه وب:
   • درون پوشه web، پوشه‌ای به نام پروژه وب خود بسازید (مثلاً MyWebProject).
2. افزودن کد منبع:
   • تمام فایل‌های HTML، CSS، JavaScript و سایر فایل‌های پروژه وب را در این پوشه کپی کنید.

۳. ساخت پروژه وب

1. ساخت پروژه:
   • با ابزار ساخت مناسب (مثل Webpack یا Parcel) پروژه وب خود را بسازید.
   • خروجی (build) شامل فایل‌های HTML، CSS و JavaScript بهینه شده خواهد بود.
2. کپی خروجی به webdist:
   • پس از ساخت، فایل‌های خروجی را در پوشه‌ای با همان نام پروژه در webdist قرار دهید.
   • مثلاً webdist/MyWebProject.

۴. استفاده از عنصر webpage در پروژه Appsan

1. افزودن عنصر webpage به فایل XML:
   • در فایل XML پروژه Appsan خود، تگ زیر را اضافه کنید:

   <webpage src="MyWebProject" title="پروژه وب من"/>

2. تست و اشکال‌زدایی:
   • پروژه Appsan را اجرا کرده و از بارگذاری صحیح صفحه وب اطمینان حاصل کنید.
   • در صورت بروز مشکل، تنظیمات پوشه‌های web، webdist و ساخت پروژه وب را بررسی کنید.

نکات مهم

• نام پوشه‌ها در web و webdist باید یکسان باشد.
• برای لینک‌های خارجی در src از URLهای HTTPS معتبر استفاده کنید.
• پس از هر تغییر در کد منبع، مجدداً پروژه وب را بسازید و خروجی را به webdist کپی کنید.

این راهنما به شما کمک می‌کند پروژه‌های وب خود را به‌طور مؤثر در Appsan ادغام کرده و از قابلیت‌های جدید بهره‌مند شوید.

در این راهنما، نحوه تنظیم پروژه Angular به گونه‌ای که فایل‌های ساخته شده (build) آن به پوشه webdist در پروژه Appsan منتقل شوند و همچنین پروژه Angular در پوشه web مدیریت شود، توضیح داده می‌شود. این تنظیمات به شما امکان می‌دهند که به راحتی از پروژه Angular خود در Appsan استفاده کنید.

۱. ایجاد پوشه‌های مورد نیاز

1. ایجاد پوشه web:
   • در مسیر اصلی پروژه Appsan، یک پوشه به نام web ایجاد کنید.
   • این پوشه حاوی کد منبع پروژه‌های وب شما خواهد بود.
2. ایجاد پوشه برای پروژه Angular:
   • درون پوشه web، پوشه‌ای به نام پروژه Angular خود بسازید (مثلاً MyAngularProject).

۲. ایجاد پروژه Angular در پوشه web

1. ایجاد پروژه Angular در مسیر مناسب:

   ng new MyAngularProject --directory web/MyAngularProject

2. تست پروژه:

   با دستور زیر پروژه را به صورت محلی اجرا کنید و از صحت عملکرد آن مطمئن شوید:

   ng serve

۳. تنظیم مسیر خروجی (outputPath) در angular.json

1. باز کردن فایل angular.json:

   در ریشه پروژه Angular، فایل angular.json را باز کنید.

2. یافتن تنظیمات outputPath:

   در بخش architect → build مقدار outputPath را پیدا کنید.

3. تغییر مسیر خروجی:

   مقدار outputPath را به مسیر زیر تغییر دهید:

   "outputPath": "../../webdist/MyAngularProject"

۴. تنظیم baseHref برای پروژه Angular

برای اطمینان از بارگذاری صحیح منابع، baseHref را به ./ تنظیم کنید:

• از طریق خط فرمان:

  ng build --base-href ./

• در angular.json:

  
  "build": {
    "options": {
      "outputPath": "../../webdist/MyAngularProject",
      "baseHref": "./"
    }
  }
        

۵. ساخت پروژه Angular

1. ساخت پروژه:

   ng build

2. بررسی فایل‌های ساخته شده:

   اطمینان حاصل کنید که فایل‌های خروجی در پوشه webdist/MyAngularProject قرار گرفته باشند.

۶. استفاده از پروژه Angular در Appsan

1. افزودن عنصر webpage در فایل XML:

   <webpage src="MyAngularProject" title="پروژه Angular من"/>

2. اجرای پروژه Appsan:

   پروژه Appsan را اجرا کرده و از بارگذاری صحیح پروژه Angular مطمئن شوید.

نکات مهم

• مطمئن شوید پوشه Angular در web/[project-name] قرار دارد.
• مسیر outputPath در angular.json دقیقاً به پوشه مناسب در webdist اشاره کند.
• همیشه baseHref را به ./ تنظیم کنید.
• پس از هر تغییر در پروژه Angular، مجدداً آن را بسازید و خروجی را به webdist کپی کنید.
• نام پوشه در webdist باید با مقدار src در عنصر webpage مطابقت داشته باشد.

در این راهنما، نحوه تنظیم یک پروژه React به‌گونه‌ای که فایل‌های build آن به پوشه webdist در پروژه Appsan منتقل شوند و همچنین پروژه در پوشه web مدیریت شود، آموزش داده می‌شود. این مراحل مشابه با تنظیمات پروژه Angular بوده ولی با در نظر گرفتن تفاوت‌های React و Vite تهیه شده است.

۱. ایجاد پوشه‌های مورد نیاز

ایجاد پوشه web:
در مسیر اصلی پروژه Appsan خود، یک پوشه به نام web ایجاد کنید. این پوشه محل قرارگیری پروژه‌های وب شماست.

ایجاد پوشه برای پروژه React:
در داخل پوشه web، یک پوشه به نام دلخواه برای پروژه React ایجاد کنید. مثلاً:

web/MyReactProject

۲. ایجاد پروژه React در مسیر مناسب

با استفاده از Vite و دستور زیر پروژه React را در مسیر دلخواه ایجاد کنید:

npm create vite@latest web/MyReactProject -- --template react

سپس وارد پوشه پروژه شده و پکیج‌ها را نصب کنید:

cd web/MyReactProject  
npm install

۳. تنظیم مسیر خروجی (build output)

برای ذخیره فایل‌های build در پوشه webdist، فایل vite.config.js را باز کرده و تنظیمات زیر را اضافه کنید:

export default defineConfig({
  base: './',
  build: {
    outDir: '../../webdist/MyReactProject',
    emptyOutDir: true,
  },
});

توجه: به جای MyReactProject در مسیر outDir نام پوشه‌ای که می‌خواهید در webdist بسازید را قرار دهید.

۴. تنظیم مسیر (Routing) برای استفاده از مسیرهای داینامیک

در صورتی که اپلیکیشن شما از مسیر داینامیک استفاده می‌کند، باید از HashRouter به جای BrowserRouter استفاده کنید.

مراحل:

1. نصب React Router:

   npm install react-router-dom

2. در فایل App.jsx به صورت زیر تغییر دهید:

   import { HashRouter, Routes, Route } from 'react-router-dom';
   function App() {
   return (
   <HashRouter>
   <Routes>
   <Route path="/" element={} />
   <Route path="/results" element={} />
   {/* مسیرهای دیگر */}
   </Routes>
   </HashRouter>
   );
   }

۵. ساخت پروژه

پس از اعمال تغییرات بالا، دستور زیر را برای ساخت پروژه اجرا کنید:

npm run build

با اجرای این دستور، فایل‌های نهایی در مسیر webdist/MyReactProject قرار می‌گیرند.

۶. استفاده از پروژه React در Appsan

در فایل XML مربوط به Appsan، عنصر <webpage> را به شکل زیر اضافه کنید:

<webpage src="MyReactProject" title="پروژه React من"/>

مطمئن شوید که src با نام پوشه‌ای که در webdist ساختید مطابقت داشته باشد.

نکات مهم

• پروژه React باید در مسیر web/[project-name] ایجاد شود.
• مسیر خروجی (outDir) در vite.config.js باید به ../../webdist/[project-name] تنظیم شود.
• مقدار base باید به './' تغییر یابد.
• برای جلوگیری از مشکلات در مسیرهای داینامیک، از HashRouter استفاده کنید.
• هر بار که تغییراتی در پروژه ایجاد می‌کنید، مجدداً دستور npm run build را اجرا نمایید.
• در فایل XML Appsan، مقدار src باید دقیقاً با نام خروجی در webdist یکسان باشد.

کتابخانه JavaScript اپسان وب با هدف تسهیل ارتباط بین صفحات وب و پلتفرم اپسان طراحی شده است. این مستند به شما کمک می‌کند تا از این کتابخانه در وب‌سایت‌های خود استفاده کنید.

نصب کتابخانه

برای نصب کتابخانه اپسان، کافی است از npm استفاده کنید:

npm i @appsan-web/mini-web-sdk

لینک کتابخانه

راه‌اندازی کتابخانه

در ابتدا نیاز است که کتابخانه را در پروژه خود وارد کنید:

import { AppsanWeb } from '@appsan-web/mini-web-sdk';

استفاده از کلاس AppsanWeb

کلاس اصلی برای تعامل با اپسان، AppsanWeb است. این کلاس مسئول مدیریت ارتباطات بین وب‌سایت شما و صفحه اپسان است.

1. راه‌اندازی اولیه

برای راه‌اندازی کتابخانه کافی است تابع initialize را فراخوانی کنید. این تابع به صورت خودکار بعد از بارگذاری کامل صفحه وب شما فعال می‌شود:

AppsanWeb.initialize();

2. وضعیت آماده بودن اپسان

می‌توانید با استفاده از getStatus() وضعیت آماده بودن اپسان را بررسی کنید. این تابع یک BehaviorSubject از نوع رشته بازمی‌گرداند که می‌توانید به تغییرات آن گوش دهید:

const status$ = AppsanWeb.getStatus();  
status$.subscribe(status => {  
  console.log("Appsan Status:", status);  
});

وضعیت می‌تواند یکی از مقادیر زیر باشد:

• not ready
• ready
• not available
• error

3. اجرای اکشن در اپسان

تابع runAction برای اجرای اکشن در اپسان استفاده می‌شود:

AppsanWeb.runAction('myAction').subscribe();

4. مدیریت دکمه بازگشت

برای کنترل رفتار دکمه بازگشت از متد setCustomBackHandler استفاده کنید. در حالت پیش‌فرض اپسان هیستوری مینی‌وب شما را مدیریت می‌کند و این تابع تنها برای مدیریت پیشرفته بازگشت کاربرد دارد:

AppsanWeb.setCustomBackHandler(() => {  
  // Custom back behavior  
});

5. ارسال درخواست HTTP

برای ارسال درخواست HTTP می‌توانید از متد httpCall استفاده کنید:

AppsanWeb.httpCall('https://api.example.com', 'GET', {}, {}).subscribe(response => {  
  console.log('HTTP Response:', response);  
});

6. دریافت اطلاعات بایند (Bind)

متد getBind برای دریافت اطلاعات یک بایند خاص استفاده می‌شود. این متد یک Subject برمی‌گرداند که می‌توانید به آن subscribe کنید تا اطلاعات بایند را دریافت کنید:

AppsanWeb.getBind('myBind').subscribe(data => {  
  console.log('Bind data:', data);  
});

7. تنظیم مقدار متغیر

با استفاده از متد setVariable می‌توانید مقدار یک متغیر را در اپسان تنظیم کنید:

AppsanWeb.setVariable('variableId', 'newValue').subscribe();

8. دریافت مقدار متغیر

برای دریافت مقدار یک متغیر از اپسان از متد getVariable استفاده کنید. این متد نیز یک Subject برمی‌گرداند که می‌توانید مقدار متغیر را دریافت نمایید:

AppsanWeb.getVariable('variableId').subscribe(variable => {  
  console.log('Variable:', variable);  
});

import { AppsanWeb, AvailableBackCountProvider } from "./AppsanWeb";

export class ConfirmableBackCountProvider implements AvailableBackCountProvider {
  private availableHistoryCount = 1;

  constructor() {
    // Patch history.pushState so we can track forward navigation
    const h = window.history as any;
    const originalPushState = h.pushState;
    h.pushState = (...args: any[]) => {
      this.onPushState();
      return originalPushState.apply(h, args);
    };

    // Track browser back/forward via popstate
    window.addEventListener("popstate", () => this.onPopState());

    // Hook custom back handler to show a confirmation dialog
    AppsanWeb.setCustomBackHandler(() => this.showConfirmationDialog());
  }

  private onPushState(): void {
    this.availableHistoryCount++;
    (AppsanWeb as any).instance.post(
      (AppsanWeb as any).MESSAGE_TYPE_AVAILABLE_HISTORY_COUNT,
      this.availableHistoryCount
    );
  }

  private onPopState(): void {
    this.availableHistoryCount = Math.max(0, this.availableHistoryCount - 1);
    (AppsanWeb as any).instance.post(
      (AppsanWeb as any).MESSAGE_TYPE_AVAILABLE_HISTORY_COUNT,
      this.availableHistoryCount
    );
  }

  getAvailableHistoryCount(): number {
    return this.availableHistoryCount;
  }

  clearBackStack(): void {
    this.availableHistoryCount = 1;
    (AppsanWeb as any).instance.post(
      (AppsanWeb as any).MESSAGE_TYPE_AVAILABLE_HISTORY_COUNT,
      1
    );
  }

  private showConfirmationDialog(): void {
    if (confirm("آیا مطمئن هستید می‌خواهید بازگشت کنید؟")) {
      history.back();
    }
  }
}

1. نمونه سازنده را بسازید:

   const backHandler = new ConfirmableBackCountProvider();

2. کلاس ساخته شده را به setAppsanBackCountProvider بدهید

• این کلاس از AppsanWeb.httpCall برای ارسال درخواست‌ها استفاده می‌کند که توسط سوپر‌اپ Appsan مدیریت می‌شود.
• داده‌های مربوط به احراز هویت به‌صورت خودکار توسط سوپر‌اپ اضافه می‌شوند.
• خروجی تمامی متدها از نوع Observable است و می‌توان با استفاده از RxJS آن‌ها را مدیریت کرد.
• گزینه‌های connectTimeout، readTimeout و writeTimeout همگی بر حسب میلی‌ثانیه هستند.
• Timeoutها را می‌توان با استفاده از setDefaultOptions برای تمامی درخواست‌ها تنظیم کرد یا از طریق options برای هر درخواست مقدار متفاوتی تعیین کرد.