Skip to content

Commit

Permalink
🚀 README Updated #2 (#12)
Browse files Browse the repository at this point in the history
  • Loading branch information
@nabiloo19
nabiloo19 authored Jan 19, 2022
1 parent 7799f5f commit 4b91f9f
Showing 1 changed file with 46 additions and 77 deletions.
123 changes: 46 additions & 77 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@
<li>
<a href="#webhooks">Webhooks</a>
<ul>
<li><a href="#create-new-webhookaction-command">Create new Webhook/Action command</a></li>
<li><a href="#order-related-webhooksactions">Order Related Webhooks/Actions</a></li>
<li><a href="#products-related-webhooksactions">Products Related Webhooks/Actions</a></li>
<li><a href="#customer-related-webhooksactions">Customer Related Webhooks/Actions</a></li>
Expand All @@ -57,13 +58,7 @@
<li><a href="#coupon-related-webhooksactions">Coupon Related Webhooks/Actions</a></li>
</ul>
</li>
<li>
<a href="#commands">Commands</a>
<ul>
<li><a href="#setup-command">Setup command</a></li>
<li><a href="#create-new-webhookaction-command">Create new Webhook/Action command</a></li>
</ul>
</li>
<li><a href="#support">Support</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
</ol>
Expand All @@ -84,63 +79,30 @@ What can you use this starter App for?
The starter App comes with an easy _1-command step_ that does the complete setup for your starter App. To be ready, you will need some prerequisites which will be listed hereafter.

### Prerequisites
- Create a Partner account at [Salla Partner Portal](https://salla.partners/)
- Create your App in [Salla Partner Portal](https://salla.dev/blog/create-your-first-app-on-salla-developer-portal/)

> From your App dashboard at [Salla Partner Portal](https://salla.partners/), you will be able to get your App's _Client ID, Client Secret Key and Webhook Secret Key_ which you will use later duraing the setup process.
- For Laravel compatibility: `PHP >= 7.4, Composer package manager and MySql Database`
- Install [ngrok](https://www.npmjs.com/package/ngrok): `npm install ngrok -g`
- Other requirments: `Nodejs and npm`
- Create a Partner account at [Salla Partner Portal](https://salla.partners/)
- For Laravel compatibility: `PHP >= 7.4, Composer package manager and MySql Database`

That is all!

### Installation
The installation process is straightforward as you will see in the below steps.

1. In your MySql Database: **create a database** with any name for example `laravel`.

2. In your command line: **run** the following `create-project` composer command to create your Laravel starter App project.
```sh
composer create-project salla/laravel-starter-kit {your-awesome-app}
```

The above `create-project` will take you through a step-by-step process in which you'll enter your App's _Client ID, Client Secret Key, and Webhook Secret Key_, which you can get from your App dashboard in the Partners Panel, as well as your database name, which is set to `laravel` by default.

![FxNjM6ii-2021-11-19 at 11 10 21](https://user-images.githubusercontent.com/10876587/142588575-f730e962-06c5-49f0-b728-837ee5dc676c.gif)
1. In your MySql Database: **create a database** with any name for example `laravel`.
2. Install [Salla CLI](https://github.com/SallaApp/Salla-CLI) via [NPM](https://www.npmjs.com/): `npm install @salla.sa/cli -g` where you will be able to run the `salla` binary commands such as `salla app create` and `salla app create-webhook <event.name>`
<!-- 3. [Salla CLI](https://github.com/SallaApp/Salla-CLI): to run the `salla` binary commands such as `salla app create` and `salla app create-webhook <event.name>` -->

> The step will ask you to select the authorization mode for your App, which can be [Easy or Custom mode.](#auth-modes)
> In case you selected the _Custom_ mode for your App authorization, you will need to enter the **same callback Url you already entered in your App dashboard at the [Salla Partner Portal](https://salla.partners/)**
<!-- > The step will ask you to select the authorization mode for your App, which can be [Easy or Custom mode.](#auth-modes)
> In case you selected the _Custom_ mode for your App authorization, you will need to enter the **same callback Url you already entered in your App dashboard at the [Salla Partner Portal](https://salla.partners/)** -->

<p align="right">(<a href="#top">back to top</a>)</p>

## Usage

1. In your command line: **Run** `php artisan serve.remote` command
With [Salla CLI](https://github.com/SallaApp/Salla-CLI) installed, **run** the following command to create your Laravel starter app project: ```salla app create``` and follow on-screen instructions.

![XBHrsHj4-2021-11-19 at 00 37 54](https://user-images.githubusercontent.com/10876587/142501121-48608b18-a14e-4f6d-968c-022b6a29b221.gif)
List of existing apps assocaited to your account will be displayed as well as an option to create your app on [Salla Partners Portal](https://salla.partners/). Afterwards, you will be presented with easy-to fill in information to create your app.

Now you can open your browser to view your App at `Remote App Url` in the [output URLs.](#output-urls). 🎉

2. Login to the Laravel App with the demo account: Email: `[email protected]`, Password: `in ksa`
3. Click the button to request the _Access Token_.
4. The Laravel App will redirect you to Merchant Auth Page.
5. Login using a Merchant Account (or the demo store of your app).
5. Give access to your App.


> If you are using [Easy mode.](#auth-modes.easy) the access token will push to the action ([`StoreAuthorize`](app/Actions/App/StoreAuthorize.php#L18)) via webhook
>
> If you are using [Custom mode.](#auth-modes.custom) the browser will redirect you again to the [`callback() page`](app/Http/Controllers/OAuthController.php#L26).
#### Output URLs <span id='output-urls'>

| URL | Description |
|------------------|-----------------------------------------------------------------------------------------------------------------|
| Local App Url | The local link for your App\. |
| Remote App Url | The online link to your App\. It will be always synced with the local Url |
| Webhook Url | The Url link that connects your App with any action that may happen at the Merchant store, e\.g\. \ncreate new product\. |
| OAuth Callback Url | The App entry page where the access token is generated; Note that this Url is available only for the `Custom` mode auth. |
![Salla App Create Command](https://i.ibb.co/92tKgZz/Clean-Shot-2021-12-27-at-21-31-15.gif)


<p align="right">(<a href="#top">back to top</a>)</p>
Expand All @@ -160,17 +122,18 @@ While creating your App in the [Salla Partners Portal](https://salla.partners/),
This mode is the default mode for the authorization, which means that the `access token` is generated automatically at Salla's side back to you.
You may refer to the class [`StoreAuthorize`](app/Actions/App/StoreAuthorize.php#L18) which is defined inside [`app\Actions\App\StoreAuthorize.php`](app/Actions/App/StoreAuthorize.php) to get more details on how to receive and manage the `access token`



#### Custom Mode <span id='auth-modes.custom'>

A callback Url is the Url that is triggered when the App has been granted authorization. This should be a valid Url to which the merchant's browser is redirected. In this mode, you will need to set a custom callback url from the App dashboard at the [Salla Partner Portal](https://salla.partners/). This callback url will redirect the merchants who are interested in using your app into your App entry page where the access token is generated.
A callback Url is the Url that is triggered when the App has been granted authorization. This should be a valid Url to which the merchant's browser is redirected. In this mode, you will need to set a custom callback url from the App dashboard at the [Salla Partner Portal](https://salla.partners/). This callback url will redirect the merchants who are interested in using your app into your App entry page where the access token is generated. Moreover, using the Salla CLI command `salla app serve`, your callback url will be automatically updated.

You may refere to file [`app/Http/Controllers/OAuthController.php`](app/Http/Controllers/OAuthController.php) which contains the [`callback()`](app/Http/Controllers/OAuthController.php#L26) function. This function is responsible for generating the `access token`

> The custom url will redirect the merchant to the [Store Dashboard](https://s.salla.sa/apps) in order to access the Store where he needs your App to be installed.
<br />
<p align="right">(<a href="#top">back to top</a>)</p>

## Authorization Service

This project comes with a simple singleton authorization service to help you with managing the access and refresh tokens
Expand Down Expand Up @@ -200,7 +163,7 @@ auth()->user()->token()->create([

### Refreshing a Token

Access tokens expire after one week. Once expired, you will have to refresh a user’s access token. you can easily request a new access token via the current refresh token for any user like this
Access tokens expire after two weeks. Once expired, you will have to refresh a user’s access token. you can easily request a new access token via the current refresh token for any user like this

```php
try {
Expand All @@ -219,14 +182,34 @@ try {
}
```
<br />

<!-- ## Examples
TBD -->

<!-- Webhooks -->

<p align="right">(<a href="#top">back to top</a>)</p>

## Webhooks
[Webhooks](https://docs.salla.dev/docs/merchant/ZG9jOjI0NTE3NDg1-webhook) simplify the communication between your App and [Salla APIs](https://docs.salla.dev/). In this way, you will be notified whenever your app receives payload/data from the Salla APIs. These webhooks are triggered along with many actions such as an order or product being created, a customer logs in, a coupon is applied, and much more.

### Create new Webhook/Action command
Salla already defined a list of the webhooks/actions that are triggered automatically. The predefined webhooks/actions can be found in the folder [`app/Actions`](https://github.com/SallaApp/Laravel-Start-Kit/tree/master/app/Actions).

### Order Related Webhooks/Actions
Run the following command to create your webhook event:

```bash
salla app create-webhook <event.name>
```

![Salla App Create-Webhook Command](https://i.ibb.co/yBstbgx/Clean-Shot-2021-12-27-at-16-16-47.gif)

<hr>

You may find the supported [Webhook events](https://docs.salla.dev/docs/merchant/ZG9jOjI0NTE3NDg1-webhook#list-of-events) as follows:

#### Order Related Webhooks/Actions

| ** Action Name ** | ** Description ** |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
Expand All @@ -251,7 +234,7 @@ Salla already defined a list of the webhooks/actions that are triggered automati

<p align="right">(<a href="#top">back to top</a>)</p>

### Products Related Webhooks/Actions
#### Products Related Webhooks/Actions

| ** Action Name ** | ** Description ** |
|--------------------------------------------------------------|---------------------------------------------------------------------------------------|
Expand All @@ -263,7 +246,7 @@ Salla already defined a list of the webhooks/actions that are triggered automati

<p align="right">(<a href="#top">back to top</a>)</p>

### Customer Related Webhooks/Actions
#### Customer Related Webhooks/Actions

| ** Action Name ** | ** Description ** |
|--------------------------------------------------------------|-------------------------------------------|
Expand All @@ -274,7 +257,7 @@ Salla already defined a list of the webhooks/actions that are triggered automati

<p align="right">(<a href="#top">back to top</a>)</p>

### Category Related Webhooks/Actions
#### Category Related Webhooks/Actions


| ** Action Name ** | ** Description ** |
Expand All @@ -284,7 +267,7 @@ Salla already defined a list of the webhooks/actions that are triggered automati

<p align="right">(<a href="#top">back to top</a>)</p>

### Brand Related Webhooks/Actions
#### Brand Related Webhooks/Actions

| ** Action Name ** | ** Description ** |
|-------------------------------------------------|----------------------------------------------------------------------------------------|
Expand All @@ -294,7 +277,7 @@ Salla already defined a list of the webhooks/actions that are triggered automati

<p align="right">(<a href="#top">back to top</a>)</p>

### Store Related Webhooks/Actions
#### Store Related Webhooks/Actions

| ** Action Name ** | ** Description ** |
|--------------------------------------------------------------------|--------------------------------------|
Expand All @@ -307,9 +290,8 @@ Salla already defined a list of the webhooks/actions that are triggered automati

<p align="right">(<a href="#top">back to top</a>)</p>



### Coupon Related Webhooks/Actions
#### Coupon Related Webhooks/Actions

| ** Action Name ** | ** Description ** |
|----------------------------------------------------------------------------|---------------------------------------------------|
Expand All @@ -321,22 +303,9 @@ Salla already defined a list of the webhooks/actions that are triggered automati

<p align="right">(<a href="#top">back to top</a>)</p>

<!-- COMMANDS -->
## Commands
### Setup command
The setup file can be found in [`app/Console/Commands/Setup.php`](https://github.com/SallaApp/Laravel-Start-Kit/blob/ffbed5807075e8da28dd445049ea3aaadf688c1a/app/Console/Commands/Setup.php).
## Support

```sh
php artisan setup
```

### Create new Webhook/Action command
The predefined [Webhooks](#webhooks), events/actions, can be found in folder [`app/Actions`](https://github.com/SallaApp/Laravel-Start-Kit/tree/master/app/Actions).
> You may define your own new webhook/action the way fits your App's requirments.
```sh
php artisan make:webhook.event {event-name}
```
<br />
The team is always here to help you. Happen to face an issue? Want to report a bug? You can submit one here on Github using the [Issue Tracker](https://github.com/SallaApp/Salla-CLI/issues/new). If you still have any questions, please contact us via the [Telegram Bot](https://t.me/SallaSupportBot) or join in the Global Developer Community on [Telegram](https://t.me/salladev).

<!-- CONTRIBUTING -->
## Contributing
Expand Down

0 comments on commit 4b91f9f

Please sign in to comment.