sighmon/opendonation

An Open Source donation app for Android making use of the Square card reader.

OpenDonation

An Open Source donation app for Android making use of the Square card reader.

Add a custom logo & background

To add your own custom logo to the top of the donation box, create a transparent .png image and copy it over the top of:

Portrait logo: app/src/main/res/drawable/custom_logo.png

Landscape logo: app/src/main/res/drawable/custom_logo_land.png

Then set the logo to appear in the file MainActivity.java by un-commenting out setCustomLogo();

To change the background colour, edit colorPrimary in app/src/main/res/values/colors.xml.

Other settings

Open MainActivity.java and scroll to Setup default donation values where you can set:

minimumDonationValue = 5;
maximumDonationValue = 99;
donationValue = 5; // currently selected value
transactionTimeout = 4; // in seconds
showDialogs = true; // set false to hide success dialogs
dialogAutoDismissTimeout = 10; // in seconds

Register your app

Don’t forget to register your app under your Square dev account: https://connect.squareup.com/apps

You’ll need your package name: com.company.opendonation

And the fingerprint of your debug certificate, which you can find with this one-liner:

$ keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

Full instructions: https://docs.connect.squareup.com/articles/android-app-fingerprint

Secrets

Secrets are stored in a file you’ll need to create:

<!-- Inside of `app/src/main/res/values/secrets.xml` -->
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="square_client_id">YOUR_CLIENT_ID</string>
</resources>

Usage:

getString(R.string.square_client_id);

<meta-data
    android:name="com.squareup"
    android:value="@string/square_client_id"/>

Follow the guide to get YOUR_CLIENT_ID: https://docs.connect.squareup.com/articles/point-of-sale-api-android

Credits

Idea by Ashleigh Hull.

Open Donation logo by simpvi.

opendonation's Issues

FEATURE 1: Number Scroll to select donation - $5 to $99

Idea 1) One of those number flict scroll wheels
idea 2) A set of buttons.. [+$1] [+$5] [+$10] and a [Donate] button to trigger the final amount?

Build a website for opendonation.app

https://opendonation.app

HOTFIX 3: Auto return after payment

After a transaction completes, Square Point of Sale automatically returns to your app after the timeout you provide to this method.

https://docs.connect.squareup.com/api/point-of-sale/android/com/squareup/sdk/pos/ChargeRequest.Builder.html#autoReturn-long-java.util.concurrent.TimeUnit-

HOTFIX 2: Restrict payment types to Tap only

https://docs.connect.squareup.com/api/point-of-sale/android/com/squareup/sdk/pos/ChargeRequest.Builder.html#restrictTendersTo-java.util.Collection-

https://docs.connect.squareup.com/api/point-of-sale/android/com/squareup/sdk/pos/ChargeRequest.TenderType.html#CARD

FEATURE 2: Full screen if possible (no back button/home button)

We'd need to be able to secretly trigger between fullscreen and not fullscreen...

The application pinning feature is good enough - but the back/home combo jumps out of pinned mode - so we need to disable or hide the back/home button

HOTFIX 1: Keep the screen on

https://developer.android.com/training/scheduling/wakelock

HOTFIX 4: Return on timeout. 30 seconds the NFC reader disconnects.

the application doesn't cancel the ChargeRequest once the NFC reader timesout.

Issue 2: the POS application login for authentication vs staff pin login

I've noticed that I need to sign in with a staff pin for the opendonation to work sometimes
but not others.

this might be a setting in the account to require staff login for transactions - I'll investigate.

Issues 1: Reader firmware upgrade seems to trigger automaticlly

this might or might not break the flow... we need to detect if the reader is online and ready?

Add a thank you page after a successful donation

FEATURE 3: Theme

This kind of depends on how we handle the scroller - but I'd like to be able to theme the application

Min: https://generozity.com.au/ purple

ok: maybe an animated cycle with the logo or something

better: fully themed animated application.

Maybe if half of the app was interaction and the second half was just "empty space" for artwork to cycle thru

Add a landscape mode for custom logos on small devices

Square: NFC Reader seems to unsync from mobile - require hard reboot

I got home today, and the reader was disconnected from the mobile phone.

Tried to resync with a quick click of the button as requested, but it refused to sync.

had to hold the button down for 15~ seconds until the lights went from orange to red,
then resync with the device..

Might need to speak with Square regarding bugs?

OR have a method of sending "test pings" to the unit on a regular basis?

FYI: API - Local vs square reporting

I've been working with the square API

and we're able to recover some information from the transactions such as amount, fee and location.

Test SDK v2 for headless features