feat(): Rename method from transferSummary to sendTransferSummary

- rename ExtractionFeedbackIntegrationTest to TransferSummaryIntegrationTest - rename feedback to transfer summary in comments and menu items - add some information about how to use sendTransferSummary method - enhance Kotlin and Java docs PIA-4595
gini · Oct 17, 2023 · b6826e6 · b6826e6
1 parent fb8de3a
commit b6826e6
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 47 deletions.
diff --git a/.../api/ExtractionFeedbackIntegrationTest.kt → ...ank/api/TransferSummaryIntegrationTest.kt b/.../api/ExtractionFeedbackIntegrationTest.kt → ...ank/api/TransferSummaryIntegrationTest.kt
@@ -22,7 +22,7 @@ import java.util.*
 
 @OptIn(ExperimentalCoroutinesApi::class)
 @RunWith(AndroidJUnit4::class)
-class ExtractionFeedbackIntegrationTest {
+class TransferSummaryIntegrationTest {
 
     private lateinit var giniBankAPI: GiniBankAPI
     private val moshi = Moshi.Builder().build()

diff --git a/.../example-app/src/main/java/net/gini/android/bank/sdk/exampleapp/ui/ExtractionsActivity.kt b/.../example-app/src/main/java/net/gini/android/bank/sdk/exampleapp/ui/ExtractionsActivity.kt
@@ -31,7 +31,7 @@ import javax.inject.Inject
 /**
  * Displays the Pay5 extractions: paymentRecipient, iban, bic, amount and paymentReference.
  *
- * A menu item is added to send feedback.
+ * A menu item is added to send transfer summary.
  */
 
 @AndroidEntryPoint
@@ -76,8 +76,8 @@ class ExtractionsActivity : AppCompatActivity(), ExtractionsAdapter.ExtractionsA
     }
 
     override fun onOptionsItemSelected(item: MenuItem): Boolean = when (item.itemId) {
-        R.id.feedback -> {
-            sendFeedbackAndClose(binding)
+        R.id.transfer_summary -> {
+            sendTransferSummaryAndClose(binding)
             true
         }
 
@@ -130,8 +130,8 @@ class ExtractionsActivity : AppCompatActivity(), ExtractionsAdapter.ExtractionsA
     private fun <T> getSortedExtractions(extractions: Map<String, T>): List<T> =
         extractions.toSortedMap().values.toList()
 
-    private fun sendFeedbackAndClose(binding: ActivityExtractionsBinding) {
-        // Feedback should be sent only for the user visible fields. Non-visible fields should be filtered out.
+    private fun sendTransferSummaryAndClose(binding: ActivityExtractionsBinding) {
+        // Transfer summary should be sent only for the user visible fields. Non-visible fields should be filtered out.
         // In a real application the user input should be used as the new value.
 
         var amount = mExtractions["amountToPay"]?.value ?: ""
@@ -145,7 +145,7 @@ class ExtractionsActivity : AppCompatActivity(), ExtractionsAdapter.ExtractionsA
             amount = Amount.EMPTY.amountToPay()
         }
 
-        GiniBank.transferSummary(
+        GiniBank.sendTransferSummary(
             paymentRecipient, paymentReference, paymentPurpose, iban, bic, Amount(
                 BigDecimal(amount.removeSuffix(":EUR")), AmountCurrency.EUR
             )

diff --git a/bank-sdk/example-app/src/main/res/menu/menu_extractions.xml b/bank-sdk/example-app/src/main/res/menu/menu_extractions.xml
@@ -2,7 +2,7 @@
 <menu xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:app="http://schemas.android.com/apk/res-auto">
     <item
-        android:id="@+id/feedback"
+        android:id="@+id/transfer_summary"
         android:title="@string/menu_item_feedback"
         app:showAsAction="always" />
     <item

diff --git a/.../sdk/ExtractionFeedbackIntegrationTest.kt → ...ank/sdk/TransferSummaryIntegrationTest.kt b/.../sdk/ExtractionFeedbackIntegrationTest.kt → ...ank/sdk/TransferSummaryIntegrationTest.kt
@@ -24,7 +24,6 @@ import net.gini.android.capture.Document
 import net.gini.android.capture.GiniCaptureError
 import net.gini.android.capture.internal.util.MimeType
 import net.gini.android.capture.network.*
-import org.junit.After
 import org.junit.Assert
 import org.junit.Before
 import org.junit.Test
@@ -41,7 +40,7 @@ import kotlin.coroutines.resumeWithException
  */
 
 @RunWith(AndroidJUnit4::class)
-class ExtractionFeedbackIntegrationTest {
+class TransferSummaryIntegrationTest {
 
     private lateinit var networkService: GiniCaptureDefaultNetworkService
     private lateinit var giniBankAPI: GiniBankAPI
@@ -103,12 +102,12 @@ class ExtractionFeedbackIntegrationTest {
         // 3. Assuming the user saw the following extractions:
         //    amountToPay, iban, bic, paymentPurpose and paymentRecipient
 
-        //    When releasing capture we need to provide the values the user has used for
+        //    Before releasing capture we need to provide the values the user has used for
         //    creating the transaction.
         //    Supposing the user changed the amountToPay from "995.00:EUR" to "950.00:EUR"
         //    we need to pass in the changed value. For the other extractions we can pass in
         //    the original values since the user did not edit them.
-        GiniBank.releaseCapture(getApplicationContext(),
+        GiniBank.sendTransferSummary(
             result.specificExtractions["paymentRecipient"]!!.value,
             "", // Payment reference was not shown to the user and can be left empty
             result.specificExtractions["paymentPurpose"]!!.value,
@@ -117,6 +116,10 @@ class ExtractionFeedbackIntegrationTest {
             Amount(BigDecimal("950.00"), AmountCurrency.EUR)
         )
 
+        // Now we can release capture
+        GiniBank.releaseCapture(getApplicationContext()
+        )
+
         //    Wait a little for the feedback sending to complete
         delay(2_000)
 

diff --git a/bank-sdk/sdk/src/main/java/net/gini/android/bank/sdk/GiniBank.kt b/bank-sdk/sdk/src/main/java/net/gini/android/bank/sdk/GiniBank.kt
@@ -138,15 +138,13 @@ object GiniBank {
     /**
      * Provides transfer summary to Gini.
      *
+     * Please provide the required transfer summary to improve the future extraction accuracy.
      *
-     * Please provide the required extraction feedback to improve the future extraction accuracy.
      * Please follow the recommendations below:
-     *
-     * Please make sure to call this method before calling [releaseCapture].
-     *
-     *  Please provide values for all necessary fields, including those that were not extracted.
-     *  Provide the final data approved by the user (and not the initially extracted only).
-     *
+     * - Please make sure to call this method before calling [releaseCapture] if the user has completed TAN verification.
+     * - Please provide values for all necessary fields, including those that were not extracted.
+     * - Provide the final data approved by the user (and not the initially extracted only).
+     * - Send the transfer summary after TAN verification and provide the extraction values the user has used.
      *
      * @param paymentRecipient payment receiver
      * @param paymentReference ID based on Client ID (Kundennummer) and invoice ID (Rechnungsnummer)
@@ -155,23 +153,23 @@ object GiniBank {
      * @param bic bank identification code
      * @param amount accepts extracted amount and currency
      */
-    fun transferSummary(
+    fun sendTransferSummary(
         paymentRecipient: String,
         paymentReference: String,
         paymentPurpose: String,
         iban: String,
         bic: String,
         amount: Amount
     ) {
-        GiniCapture.transferSummary(
+        GiniCapture.sendTransferSummary(
             paymentRecipient, paymentReference, paymentPurpose, iban, bic, amount
         )
     }
 
     /**
      * Frees up resources used by the capture flow.
      *
-     * Please provide the required extraction feedback to improve the future extraction accuracy.
+     * Please provide the required transfer summary to improve the future extraction accuracy.
      * Please follow the recommendations below:
      *
      * - Please provide values for all necessary fields, including those that were not extracted.</li>
@@ -186,10 +184,10 @@ object GiniBank {
      * @param bic bank identification code
      * @param amount accepts extracted amount and currency
      *
-     * @deprecated Please use {@link #releaseCapture(Context)} which does not require transfer summary parameters.
+     * @deprecated Please use [sendTransferSummary] to provide the required transfer summary first (if the user has completed TAN verification) and then [releaseCapture] to let the SDK free up used resources.
      */
     @Deprecated(
-        "Please use releaseCapture(Context) which does not require transfer summary parameters.",
+        "Please use sendTransferSummary() to provide the required transfer summary first (if the user has completed TAN verification) and then releaseCapture() to let the SDK free up used resources.",
         ReplaceWith("releaseCapture(context)")
     )
     fun releaseCapture(
@@ -201,7 +199,7 @@ object GiniBank {
         bic: String,
         amount: Amount
     ) {
-        transferSummary(
+        sendTransferSummary(
             paymentRecipient, paymentReference, paymentPurpose, iban, bic, amount
         )
         releaseCapture(context)

diff --git a/...work/ExtractionFeedbackIntegrationTest.kt → ...network/TransferSummaryIntegrationTest.kt b/...work/ExtractionFeedbackIntegrationTest.kt → ...network/TransferSummaryIntegrationTest.kt
@@ -22,7 +22,6 @@ import net.gini.android.capture.network.model.GiniCaptureSpecificExtraction
 import net.gini.android.capture.network.test.ExtractionsFixture
 import net.gini.android.capture.network.test.bankAPIDocumentWithId
 import net.gini.android.capture.network.test.fromJsonAsset
-import org.junit.After
 import org.junit.Assert
 import org.junit.Before
 import org.junit.Test
@@ -39,7 +38,7 @@ import kotlin.coroutines.resumeWithException
  */
 
 @RunWith(AndroidJUnit4::class)
-class ExtractionFeedbackIntegrationTest {
+class TransferSummaryIntegrationTest {
 
     private lateinit var networkService: GiniCaptureDefaultNetworkService
     private lateinit var giniBankAPI: GiniBankAPI
@@ -98,12 +97,12 @@ class ExtractionFeedbackIntegrationTest {
         val amountToPay = extractionsBundle.getParcelable<GiniCaptureSpecificExtraction>("amountToPay")
         amountToPay!!.value = "950.00:EUR"
 
-        //    When releasing capture we need to provide the values the user has used for
+        //    Before cleaning up the capture we need to provide the values the user has used for
         //    creating the transaction.
         //    Supposing the user changed the amountToPay from "995.00:EUR" to "950.00:EUR"
         //    we need to pass in the changed value. For the other extractions we can pass in
         //    the original values since the user did not edit them.
-        GiniCapture.cleanup(getApplicationContext(),
+        GiniCapture.sendTransferSummary(
             extractionsBundle.getParcelable<GiniCaptureSpecificExtraction>("paymentRecipient")!!.value,
             "", // Payment reference was not shown to the user and can be left empty
             extractionsBundle.getParcelable<GiniCaptureSpecificExtraction>("paymentPurpose")!!.value,
@@ -112,6 +111,9 @@ class ExtractionFeedbackIntegrationTest {
             Amount(BigDecimal("950.00"), AmountCurrency.EUR)
         )
 
+        // Now we can clean up the capture
+        GiniCapture.cleanup(getApplicationContext())
+
         //    Wait a little for the feedback sending to complete
         delay(2_000)
 

diff --git a/capture-sdk/sdk/src/main/java/net/gini/android/capture/GiniCapture.java b/capture-sdk/sdk/src/main/java/net/gini/android/capture/GiniCapture.java
@@ -70,20 +70,15 @@
  * <p> To create and configure a singleton instance use the {@link #newInstance(Context)} method and the
  * returned {@link Builder}.
  *
- * <p> Use the {@link #cleanup(Context)} method to clean up the SDK
- * Please follow the recommendations below:
- *
- * <ul>
- *     <li>Do cleanup after TAN verification.to clean up.</li>
- * </ul>
+ * <p> Please first provide the transfer summary via the {@link #sendTransferSummary(String, String, String, String, String, Amount)} method.
+ * The transfer summary is used to improve the future extraction accuracy.
+ * Then, use the {@link #cleanup(Context)} method to clean up the SDK.
  *
- * <p> Use the {@link #transferSummary(String, String, String, String, String, Amount)}  method to
- * provide the required extraction feedback to improve the future extraction accuracy.
  * Please follow the recommendations below:
  *
  * <ul>
- *     <li>Please provide values for all necessary fields, including those that were not extracted.</li>
  *     <li>Provide the final data approved by the user (and not the initially extracted only).</li>
+ *     <li>Send the transfer summary after TAN verification and provide the extraction values the user has used.</li>
  * </ul>
  */
 public class GiniCapture {
@@ -168,7 +163,7 @@ public static synchronized boolean hasInstance() {
     @Deprecated
     public static synchronized Builder newInstance() {
         if (sInstance != null) {
-            throw new IllegalStateException("An instance was already created. " + "Call GiniCapture.cleanup() before creating a new instance.");
+            throw new IllegalStateException("An instance was already created. Call GiniCapture.cleanup() before creating a new instance.");
         }
         return new Builder();
     }
@@ -193,13 +188,13 @@ public static synchronized Builder newInstance(final Context context) {
     /**
      * Provides transfer summary to Gini.
      *
-     * <p>Please provide the required extraction feedback to improve the future extraction accuracy.
+     * <p>Please provide the required transfer summary to improve the future extraction accuracy.
      * Please follow the recommendations below:
-     *
      * <ul>
-     *     <li>Please call this method before calling the {@link #cleanup(Context)} method</li>
+     *     <li>Please make sure to call this method before calling {@link #cleanup(Context)} if the user has completed TAN verification.</li>
      *     <li>Please provide values for all necessary fields, including those that were not extracted.</li>
      *     <li>Provide the final data approved by the user (and not the initially extracted only).</li>
+     *     <li>Send the transfer summary after TAN verification and provide the extraction values the user has used.</li>
      * </ul>
      *
      * @param paymentRecipient payment receiver
@@ -209,7 +204,7 @@ public static synchronized Builder newInstance(final Context context) {
      * @param bic              bank identification code
      * @param amount           accepts extracted amount and currency
      */
-    public static synchronized void transferSummary(@NonNull final String paymentRecipient, @NonNull final String paymentReference, @NonNull final String paymentPurpose, @NonNull final String iban, @NonNull final String bic, @NonNull final Amount amount) {
+    public static synchronized void sendTransferSummary(@NonNull final String paymentRecipient, @NonNull final String paymentReference, @NonNull final String paymentPurpose, @NonNull final String iban, @NonNull final String bic, @NonNull final Amount amount) {
 
         if (sInstance == null) {
             return;
@@ -233,7 +228,7 @@ public static synchronized void transferSummary(@NonNull final String paymentRec
         // Test fails here if for some reason mGiniCaptureNetworkService is null
         // Added null checking to fix test fail -> or figure out something else
         final GiniCapture oldInstance = sInstance;
-        if (oldInstance.mGiniCaptureNetworkService != null)
+        if (oldInstance.mGiniCaptureNetworkService != null) {
             oldInstance.mGiniCaptureNetworkService.sendFeedback(extractionMap, oldInstance.mInternal.getCompoundExtractions(), new GiniCaptureNetworkCallback<Void, Error>() {
                 @Override
                 public void failure(Error error) {
@@ -256,14 +251,15 @@ public void cancelled() {
                     }
                 }
             });
+        }
 
     }
 
 
     /**
      * Destroys the {@link GiniCapture} instance and frees up used resources.
      *
-     * <p>Please provide the required extraction feedback to improve the future extraction accuracy.
+     * <p>Please provide the required transfer summary to improve the future extraction accuracy.
      * Please follow the recommendations below:
      *
      * <ul>
@@ -279,12 +275,13 @@ public void cancelled() {
      * @param iban             international bank account
      * @param bic              bank identification code
      * @param amount           accepts extracted amount and currency
-     * @deprecated Please use {@link #cleanup(Context)} to cleanup and {@link #transferSummary(String, String, String, String, String, Amount)} to provide the required extraction feedback.
+     * @deprecated Please use {@link #sendTransferSummary(String, String, String, String, String, Amount)} to provide the required transfer summary first (if the user has completed TAN verification) and then {@link #cleanup(Context)} to let the SDK free up used resources.
+     *
      */
 
     @Deprecated
     public static synchronized void cleanup(@NonNull final Context context, @NonNull final String paymentRecipient, @NonNull final String paymentReference, @NonNull final String paymentPurpose, @NonNull final String iban, @NonNull final String bic, @NonNull final Amount amount) {
-        transferSummary(paymentRecipient, paymentReference, paymentPurpose, iban, bic, amount);
+        sendTransferSummary(paymentRecipient, paymentReference, paymentPurpose, iban, bic, amount);
         cleanup(context);
     }