Stand with Ukraine App

Backend Components

---

Overview

Stand With Ukraine is a BigCommerce application. It allows merchants to easily add a widget to their storefront with a customized message and list of Charities that the merchant would like their shoppers to visit and support.

Repositories

• Frontend Components
• Backend Components

Getting Started

• apps/server is a rust http server that implements the OAuth callback flow for BigCommerce Single Click Apps and uses the BigCommerce Management APIs to inject the widget using the Script API. For information on how to develop apps for BigCommerce stores, see our Developer Portal.
• apps/exporter is an program that exports data from the database and updates a google spreadsheet with the install status and widget removal feedback. It is scheduled to run every hour and allows the product/business teams to access this data without needing database access.

We hope this sample gives you a good reference point for building your next killer app!

Registering the app with BigCommerce

1. Create a trial store on BigCommerce

2. Go to the Developer Portal and log in by going to "My Apps"

3. Click the button "Create an app", enter a name for the new app, and then click "Create"

4. You don't have to fill out all the details for your app right away, but you do need to provide some core details in section 4 (Technical). Note that if you are just getting started, you can use localhost for your hostname, but ultimately you'll need to host your app on the public Internet.

   • Auth Callback URL: https://<app hostname>/bigcommerce/install
   • Load Callback URL: https://<app hostname>/bigcommerce/load
   • Uninstall Callback URL: https://<app hostname>/bigcommerce/uninstall

5. Enable the following under OAuth scopes which this sample app needs:

   • Store Information - Read Only scope is needed to get the store url for providing a preview url
   • Store Content - Modify scope is needed to inject the script on the storefront

6. Click Save & Close on the top right of the dialog.

7. You'll now see your app in a list in the My Apps section of Developer Portal. Hover over it and click View Client ID. You'll need these values in the next step.

Local Development

• Prerequisites
  • Rust toolchain
    • Recommend using rustup to setup rust, cargo, fmt
  • SQLX command
    • Recommend setup using cargo install sqlx-cli --force --version=0.8.2 --features=postgres --no-default-features
  • Nextest command
    • Recommend setup using cargo install nextest
  • Docker
    • Recommended setup for macos or linux is podman and creating an alias for docker from podman
  • Editor
    • Recommended setup is vscode and the rust-analyzer extension.
  • Tracing / Logs
    • Open telemetry is supported so you can enable it:
      • Run jaeger locally: docker run -d -p16686:16686 -p4317:4317 jaegertracing/all-in-one:latest
      • Run
        • the app with flag enabled RUST_LOG=trace OTEL_ENABLE=true cargo run --bin swu-app
        • or the test suite OTEL_ENABLE=true cargo nextest run
      • View spans in the jaeger ui (service = swu-app for server binary, or service = test for test suite)
        • http://localhost:16686
    • Or you can use console output + bunyan
      • Recommended setup is cargo install bunyan
      • Set log level during testing and pass it through bunyan RUST_LOG=trace cargo test | bunyan

1. Clone this repo: git clone [email protected]:bigcommerce/stand-with-ukraine-backend.git
2. Change to the repo directory: cd stand-with-ukraine-backend
3. Install dependencies with pip: cargo install
4. Copy .env-sample to .env
5. Edit .env or apps/exporter/configuration/base.yaml / apps/server/configuration/base.yaml
   • Set the following to the values obtained from Developer Portal for your app.
     • bigcommerce.client_id
     • bigcommerce.client_secret
   • Set application.jwt_secret to a long random string, such as that generated by your password manager or random.org.
6. Start the database container CREATE_LOCAL_DB=TRUE ./scripts/init_db.sh
7. Run tests: cargo nextest run
8. Run app: cargo run --bin swu-app

Hosting the app

In order to install this app in a BigCommerce store, it must be hosted on the public Internet. You can get started in development by simply running cargo run --bin swu-app to run it locally, and then use localhost in your URLs. Ultimately you will need to host it somewhere to use the app anywhere other than your development system.

Deploying to Production

This repo is setup to be deployed to Google cloud run using a Docker container. Github Actions tests and builds a docker image if everything passes. The action is also responsible for pushing the image to google cloud artifacts and also running the update deployment command to target the new image.

To configure the production server variables you can use environment variables for the container to override the configuration in the file apps/server/configuration/base.yaml apps/exporter/configuration/base.yaml.

For example, to configure of the app hostname you can do one of the following:

1. Edit application.base_url in apps/server/configuration/base.yaml apps/exporter/configuration/base.yaml.
2. Set APP__APPLICATION__BASE_URL using environment variables from the container platform. Environment variables will override the file configuration.

Installing the app in your trial store

• Login to your trial store
• Go to the Marketplace and click My Drafts. Find the app you just created and click it.
• A details dialog will open. Click Install and the draft app will be installed in your store.

Architecture - API/Routes

• BigCommerce OAuth Routes. They are responsible for handling the install, load and uninstall requests from a BigCommerce Store
  • /bigcommerce/install
  • /bigcommerce/load
  • /bigcommerce/uninstall
• API Routes
  • /api/v1/publish
    • POST publish widget to storefront
    • DELETE remove widget from storefront
  • /api/v1/preview
    • GET retrieve the store url for previewing the widget
  • /api/v1/configuration
    • POST set the configuration of the widget
    • GET get the current configuration of the widget
  • /api/v2/widget-event
    • POST saves a widget event for analytics purposes
  • /api/v2/charity-event
    • POST saves a charity visited event for analytics purposes

License

Copyright (c) 2017-present, BigCommerce Pty. Ltd. All rights reserved

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.