Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/vtex/affiliates

Last synced: about 1 month ago
JSON representation

Host: GitHub
URL: https://github.com/vtex/affiliates
Owner: vtex
Created: 2021-11-08T13:22:29.000Z (about 3 years ago)
Default Branch: main
Last Pushed: 2024-10-24T22:49:50.000Z (2 months ago)
Last Synced: 2024-10-26T02:11:42.877Z (2 months ago)
Language: TypeScript
Size: 4.34 MB
Stars: 1
Watchers: 9
Forks: 3
Open Issues: 26
Metadata Files:
- Readme: docs/README.md
- Changelog: CHANGELOG.md
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

# Affiliates Program

> ⚠️ This app is no longer maintained by VTEX. This means support and maintenance are no longer provided.

Affiliates app allows your store to work with a partner structure. The app creates affiliates stores, that has an access page and url parameter for them to share with their clients. When something is bought, it generates a commission related to their clients purchase.
The app also adds configuration and management pages for the store owner and affiliates as well.

![Affiliate page](https://user-images.githubusercontent.com/53904010/192868993-8967062b-b140-4d0e-95e1-b5c3c4e9f79a.png)

_**Example of an affiliate page**_

This is the main page that will be shared by the affiliate with their clients. It's a page that can be customized to show some products and guide the customer.

![Affiliate profile page](https://user-images.githubusercontent.com/53904010/192872539-184d5dee-01cc-46b4-a2b8-4d138e3b0b6c.png)

_**Example of the affiliate profile page**_

This is the page where the affiliate can see the orders related to their account, with a totalizer and dashboard for a better experience.

![Affiliate Form page](https://user-images.githubusercontent.com/53904010/192870484-72cfc8a0-f5bb-488e-8a7a-cda6c189affc.png)

_**Example of the affilate form**_

This page contains a form that can be filled by anyone that wants to became an affiliate

## Configuration

1. Search for the Affiliate app on our app store and install it on your account.

2. Open your store's Store Theme app directory in your code editor.

3. Add the Affiliates app to your theme's `manifest.json` file inside **peerDependencies** as shown below:

```diff
"peerDependencies": {
+ "vtex.affiliates": "1.x"
}
```

> ℹ️ _The Affiliates app can export several theme blocks when added as a dependency. There are some that are responsible for creating several different pages on the storefront, like `affiliate`, `affiliate-profile` and `affiliate-form`, and there are several functionality blocks that will be used within these pages context as well, we will show more about them on the advanced section._

3. After installing the app, the main pages will be available with a default layout, you can access them by `/affiliates/:slug` and `/affiliates/profile/:slug`

4. If you want your affiliates to have the possibility to send any URL of the site for the client, you will have to add the `affiliate-url-monitoring` block into the header of your theme as shown below:

```diff
"header-layout.desktop": {
"children": [
+ "affiliate-url-monitoring",
"flex-layout.row#1-desktop",
"flex-layout.row#3-desktop",
]
},

"header-layout.mobile": {
"children": [
+ "affiliate-url-monitoring",
"flex-layout.row#1-desktop",
]
},
```

> ℹ️ _The `affiliate_url_monitoring` app adds a logic that will seek for specific parameter on the URL, if the parameter is found with a valid affiliate slug as it's value, it will add the affiliate informations on the purchase.

5. Now your affiliate can send any URL with the parameter **targeting** with their slug as value, it will adds this affiliate information to be linked to the purchase

| Example URL | Behavior |
|-------------------------------------------------------|----------------------------------------------------------------|
| https://mystore.com/product/p | Just a simple product URL |
| https://mystore.com/product/p?targeting=affiliateName | URL with the parameter, will link this client to the affiliate |

6. If you want to change the parameter that will be used for the affiliate to share, you can edit the parameter property from the `Affiliate Monitoring` block inside the Site Editor.

![Parameter Editing](https://user-images.githubusercontent.com/53904010/191607498-a58c11ba-57f9-4d1c-aa65-b3d4c82c0c90.png)

> ℹ️ _After the affiliate send their URL for the client, their Affiliate ID will be linked to this client for some time and will be prioritized even if another Affiliate send an URL to the same client, the time the Affiliate ID usually persists is 60 days

## Advanced configurations

According to the Affiliate app composition, the `/affiliates/:slug` page can be highly customizable using other blocks. Currently, its default implementation is as follows:

`store.affiliates` interface for the route `/affiliates/:slug`, `store.affiliates-profile` for the route `affiliates/profile/:slug`, and `store.affiliate-form` for the route `affiliate/form`.

**store.affiliates**

```json
{
"store.affiliates": {
"blocks": ["affiliate-validator"]
},

"affiliate-validator": {
"props": {
"Valid": "affiliate-template",
"Invalid": "affiliate-invalid-template"
}
},

"affiliate-template": {
"children": [
"affiliate-store-name",
"flex-layout.row#banner",
"affiliate-profile-button",
"search-result-layout.customQuery#affiliate"
]
},

"flex-layout.row#banner": {
"children": ["image#affiliate-banner"]
},

"image#affiliate-banner": {
"props": {
"src": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/VTEX_Logo.svg/400px-VTEX_Logo.svg.png"
}
},

"search-result-layout.customQuery#affiliate": {
"props": {
"querySchema": {
"skusFilter": "ALL_AVAILABLE",
"simulationBehavior": "default",
"queryField": "137",
"mapField": "productClusterIds",
"facetsBehavior": "Dynamic"
}
},
"blocks": [
"search-result-layout.desktop",
"search-result-layout.mobile",
"search-not-found-layout"
]
},

"affiliate-invalid-template": {
"children": ["rich-text#invalid-affiliate"]
},

"rich-text#invalid-affiliate": {
"props": {
"textAlignment": "CENTER",
"textPosition": "CENTER",
"text": "**Affiliate does not exist or has not been approved**",
"font": "t-heading-1"
}
}

}
```

**store.affiliates-profile**

```json
{
"store.affiliates-profile": {
"children": ["affiliate-profile"]
},

"affiliate-profile": {
"children": ["affiliate-profile-topbar", "affiliate-profile-validator"]
},

"affiliate-profile-validator": {
"props": {
"Valid": "flex-layout.row#profile",
"Invalid": "rich-text#profileerror"
}
},

"rich-text#profileerror": {
"props": {
"text": "### Faça o login com a conta correta do afiliado para acessar as informações",
"textAlignment": "CENTER",
"textPosition": "CENTER"
}
},

"flex-layout.row#profile": {
"children": ["flex-layout.col#profile"]
},

"flex-layout.col#profile": {
"children": [
"affiliate-profile-title",
"affiliate-profile-totalizer",
"affiliate-profile-table"
]
},

}
```

**store.affiliate-form**

```json
{
"store.affiliate-form": {
"children": ["affiliate-form"]
}
}
```

By "default implementation" we mean that, by installing the Affiliate app in your store, you're actually using the `jsons` above behind the scenes to build the new pages.

Therefore, in order to customize these pages configuration, you should:

1. Create a `affiliates.jsonc`, `affiliates-profile.jsonc` or `affiliates-form.jsonc` file under `store/blocks`.
3. Copy the code above, paste it in the new file and change it as you wish.
4. Deploy your changes.

## Props

There a two specific component types with props that must be configured to work properly.

#### `affiliate-validator` and `affiliate-profile-validator` props

#### `affiliate_url_monitoring` props

## Email Template

For the export function to work properly and be able to send the exported sheets to the user via email, it is needed to create two new templates on the message center, based on the examples below:

#### Affiliate Orders Export Template

```diff

{{_accountInfo.TradingName}}

p {
font-family: Fabriga, -apple-system, BlinkMacSystemFont, avenir next, avenir, helvetica neue, helvetica, ubuntu, roboto, noto, segoe ui, arial, sans-serif;
};
.vtex-button {
border-width: .125rem;
border-style: solid;
font-weight: 500;
vertical-align: middle;
padding: 0;
line-height: 1;
border-radius: .25rem;
min-height: 2.5rem;
box-sizing: border-box;
font-family: Fabriga, -apple-system, BlinkMacSystemFont, avenir next, avenir, helvetica neue, helvetica, ubuntu, roboto, noto, segoe ui, arial, sans-serif;
font-size: 1rem;
text-transform: uppercase;
letter-spacing: 0;
background-color: #134cd8;
border-color: #134cd8;
color: #fff;
cursor: pointer;
};

Planilha de pedidos de afiliados exportada

Olá,

Segue o link para baixar a planilha pedidos de afiliados.

Baixar Planilha

Abraços,

VTEX

O link para download é válido por 24 horas. Após esse tempo, será necessário realizar a exportação novamente.

Esse email é enviado automaticamente e não recebe respostas.

Precisa de ajuda? Fale Conosco

```

#### Commissions By Sku Export Template

```diff

Planilha de comissionamento por SKU exportada

Olá,

Segue o link para baixar a planilha de comissionamento por SKU.

Baixar Planilha

Abraços,

VTEX

O link para download é válido por 24 horas. Após esse tempo, será necessário realizar a exportação novamente.

Esse email é enviado automaticamente e não recebe respostas.

Precisa de ajuda? Fale Conosco

```
## Customization

In order to apply CSS customizations to this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://vtex.io/docs/recipes/style/using-css-handles-for-store-customization).

| CSS Handles |
| ----------------------- |
| `affiliateStoreName` |
| `affiliateProfileTitle` |
| `profileButtonContainer`|

## Some app errors and their possible solution
https://www.notion.so/vtexhandbook/Errors-that-the-affiliate-app-may-present-128f8223cee9800a93e7f9a32ea99fba?pvs=4

## Contributors ✨

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!