Ana içeriğe geç

BEX Full SDK — Entegrasyon Kılavuzu

Ne işe yarar?​

BKM Express SDK'si, kartların güvenli ve kolayca saklandığı BKM Express altyapısını kullanmak için geliştirilen bir framework'tür.

Nasıl Çalışır?​

  1. Entegrasyon talebi açılır ve token üretilecek servisin entegrasyonu sağlanır.
  2. Kullanıcının telefon numarası ile 'init' isteği atılır ve token elde edilir.
  3. Elde edilen token ile SDK istenen kullanım türünde başlatılır.

Gereksinimler​

  • iOS 15.0+ sürümler ve Swift programlama dili desteklenmektedir.
  • SwiftUI ve UIKit frameworkleri için komponentler mevcuttur.
  • iPhone ve iPad cihazlar desteklenmektedir.

Ortamlar​

SDK Production, Preprod ve Test olmak üzere üç modu desteklemektedir. Mod (Mode) parametresi 'init' işlemi esnasında context içinde belirtilmelidir. Testlerin güvenlik ve çeşitlilik için Test ortamında yapılması önerilir.

Entegrasyon​

Sadece Swift Package Manager ile dağıtım mevcuttur.

  • Projenizin "Package Dependencies" kısmından gerekli sürüm bilgisini girerek

** veya **

  • Başka bir Swift Package içinde kullanılacaksa:

    1. Package.swift dosyanızdaki "dependencies" parametresi içerisine bağımlılığı ekledikten sonra

      .package(url: "https://github.com/BKMExpress/BKMExpressSDK.git", exact: "2.0.0")

    2. Bağımlılığı kullanmak istediğiniz target'in "dependencies" kısmına SDK'nin product'ını ekleyerek

      "BKMExpressSDK"

SDK'yi kullanabilirsiniz.

Kullanım (Kart Seçimi)​

UIKit​

  1. BKM Express SDK'sı import edilir
import BKMExpressSDK
  1. Kendi sunucularınızdan entegrasyon sonucunda elde edeceğiniz tokenle birlikte 'InitializationContext' içerisinde istenen tüm bilgiler doldurulur ve 'init' çağrısı yapılır.
final class MyController: UIViewController {
  private func selectCardButtonTapped() async {
    do {
      let token = try await BKMExpress.initialize(
        context: .init(
          authToken: "", // -> Auth tokeniniz.
          merchantID: "", // -> Entegrasyon sonucunda size verilen merchant identifier'ınız.
          merchantUserID: "", // -> Kullanıcınızı tanımlamak için kullandığınız identifier.
          gsmNo: .init("5555555555") // -> Kullanıcınıza ait telefon numarası. Ayrı bir struct olduğu için kendi kurallarını işletir ve sadece verilen telefon numarası şartları sağladığında bir instance'ı yaratılabilir.
          mode: .development// -> SDK'nın modunu belirler. Test yaparken test veya preprod, uygulama kullanılırken production kullanılmalıdır.
        ) 
      )
      
    } catch {
      showAlert("BKM Express başlatılamadı.")
    }
  }
}
  1. 'init' çağrısından elde edilen token ile birlikte 'selectCard' fonksiyonu kullanılarak eşleştirme modunda başlatılır.

SDK akışı herhangi bir nedenle tamamladığında kendini dismiss edeceğinden ekstra dismiss çağrısı yapılmasına gerek yoktur.

class Controller: UIViewController {
  private func selectCardButtonTapped() async {
    do {
      let token = try await BKMExpress.initialize(
        context: .init(
          authToken: "", // -> Auth tokeniniz.
          merchantID: "", // -> Entegrasyon sonucunda size verilen merchant identifier'ınız.
          merchantUserID: "", // -> Kullanıcınızı tanımlamak için kullandığınız identifier.
          gsmNo: .init("5555555555") // -> Kullanıcınıza ait telefon numarası. Ayrı bir struct olduğu için kendi kurallarını işletir ve sadece verilen telefon numarası şartları sağladığında bir instance'ı yaratılabilir.
          mode: .development// -> SDK'nın modunu belirler. Test yaparken test veya preprod, uygulama kullanılırken production kullanılmalıdır.
        ) 
      )
      
      var theme = BKMExpress.Theme()
      // tema özelleştirmesi burada yapılabilir. 
      // özelleştirme yapılmayacaksa tema parametresi verilmeyerek varsayılan tema kullanılabilir.
      
      // Burada günümüz konvansiyonlarına uymak için callbackli olan metod kullanılmıştır ancak bu metodun klasik delegate versiyonu da bulunmaktadır.
      BKMExpress.selectCard(
        token: token, // -> init işleminden elde edilen token.
        theme: theme, // -> SDK görünümünü özelleştirmek için kullanılan tema. Opsiyonel.
        style: .sheet, // -> SDK sunum şekli. Tam ekran için .fullScreen, sheet için .sheet kullanılabilir.
        on: self, // -> SDK'yı present edecek controller.
      ) { result in 
        // SDK sonucuna göre aksiyon alınır.
      }
    } catch {
      showAlert("BKM Express başlatılamadı.")
    }
  }
}

SwiftUI​

  1. BKM Express SDK'sı import edilir
import BKMExpressSDK
  1. BKMExpress.InitializationToken state'i optional view'ınıza (veya ViewModelinize) eklenir. 'bkmExpressCardSelectionSheet' view modifier'ına binding'i iletilir.
struct Screen: View {
  @State var bkmExpressToken: BKMExpress.InitializationToken?
  
  var body: some View {
    VStack {
      // view'ınızın içeriği
      Button("BKM Express kartınızı eşleştirin") {
        // ...
      }
    }
    .bkmExpressCardSelectionSheet(
      token: $bkmExpressToken, // -> init işleminden elde edilen token'ın binding'i.
      theme: { $0.buttonCornerRadius = .capsule }, // -> SDK'da kullanılacak varsayılan temayı değiştirmek için kullanılacak fonksiyon. Opsiyonel.
      style: .sheet, // -> SDK sunum şekli. Tam ekran için .fullScreen, sheet için .sheet kullanılabilir.
    ) { result in 
      // SDK sonucuna göre aksiyon alınır.
    }
  }
}
  1. Kendi sunucularınızdan entegrasyon sonucunda elde edeceğiniz tokenle birlikte 'InitializationContext' içerisinde istenen tüm bilgiler doldurulur ve 'init' çağrısı yapılır. Init çağrısından alınan token state'e atanır, böylelikle SDK başlamış olur.

SDK akışı herhangi bir nedenle tamamladığında kendini dismiss edip tokene otomatik olarak nil değerini set edecektir. Ekstra bir aksiyona gerek yoktur.

struct Screen: View {
  @State var bkmExpressToken: BKMExpress.InitializationToken?
  
  var body: some View {
    VStack {
      // view'ınızın içeriği
      Button("BKM Express kartınızı eşleştirin") {
        Task {
          do {
            bkmExpressToken = try await BKMExpress.initialize(
              context: .init(
                authToken: "", // -> Auth tokeniniz.
                merchantID: "", // -> Entegrasyon sonucunda size verilen merchant identifier'ınız.
                merchantUserID: "", // -> Kullanıcınızı tanımlamak için kullandığınız identifier.
                gsmNo: .init("5555555555") // -> Kullanıcınıza ait telefon numarası. Ayrı bir struct olduğu için kendi kurallarını işletir ve sadece verilen telefon numarası şartları sağladığında bir instance'ı yaratılabilir.
                mode: .development // -> SDK'nın modunu belirler. Test yaparken test veya preprod, uygulama kullanılırken production kullanılmalıdır. 
              ) 
            )
          } catch {
            showAlert("BKM Express başlatılamadı.")
          }
        }
      }
    }
    .bkmExpressCardSelectionSheet(
      token: $bkmExpressToken, // -> init işleminden elde edilen token'ın binding'i.
      theme: { $0.buttonCornerRadius = .capsule }, // -> SDK'da kullanılacak varsayılan temayı değiştirmek için kullanılacak fonksiyon. Opsiyonel.
      style: .sheet, // -> SDK sunum şekli. Tam ekran için .fullScreen, sheet için .sheet kullanılabilir.
    ) { result in 
      // SDK sonucuna göre aksiyon alınır.
    }
  }
}

Kullanım (Ödeme)​

UIKit​

  1. BKM Express SDK'sı import edilir
import BKMExpressSDK
  1. Kendi sunucularınızdan entegrasyon sonucunda elde edeceğiniz tokenle birlikte 'InitializationContext' içerisinde istenen tüm bilgiler doldurulur ve 'init' çağrısı yapılır.
final class MyController: UIViewController {
  private func payButtonTapped() async {
    do {
      let token = try await BKMExpress.initialize(
        context: .init(
          authToken: "", // -> Auth tokeniniz.
          merchantID: "", // -> Entegrasyon sonucunda size verilen merchant identifier'ınız.
          merchantUserID: "", // -> Kullanıcınızı tanımlamak için kullandığınız identifier.
          gsmNo: .init("5555555555") // -> Kullanıcınıza ait telefon numarası. Ayrı bir struct olduğu için kendi kurallarını işletir ve sadece verilen telefon numarası şartları sağladığında bir instance'ı yaratılabilir.
          mode: .development // -> SDK'nın modunu belirler. Test yaparken test veya preprod, uygulama kullanılırken production kullanılmalıdır.
        ) 
      )
      
    } catch {
      showAlert("BKM Express başlatılamadı.")
    }
  }
}
  1. 'init' çağrısından elde edilen token ile birlikte 'pay' fonksiyonu kullanılarak eşleştirme modunda başlatılır.

SDK akışı herhangi bir nedenle tamamladığında kendini dismiss edeceğinden ekstra dismiss çağrısı yapılmasına gerek yoktur.

class Controller: UIViewController {
  private func payButtonTapped() async {
    do {
      let token = try await BKMExpress.initialize(
        context: .init(
          authToken: "", // -> Auth tokeniniz.
          merchantID: "", // -> Entegrasyon sonucunda size verilen merchant identifier'ınız.
          merchantUserID: "", // -> Kullanıcınızı tanımlamak için kullandığınız identifier.
          gsmNo: .init("5555555555") // -> Kullanıcınıza ait telefon numarası. Ayrı bir struct olduğu için kendi kurallarını işletir ve sadece verilen telefon numarası şartları sağladığında bir instance'ı yaratılabilir.
          mode: .development // -> SDK'nın modunu belirler. Test yaparken test veya preprod, uygulama kullanılırken production kullanılmalıdır.
        ) 
      )
      
      var theme = BKMExpress.Theme()
      // tema özelleştirmesi burada yapılabilir. 
      // özelleştirme yapılmayacaksa tema parametresi verilmeyerek varsayılan tema kullanılabilir.
      
      // Ödeme bilgileri alanı uygun şekilde doldurulur.
      let paymentData = BKMExpress.PaymentData(...)
      
      // Burada günümüz konvansiyonlarına uymak için callbackli olan metod kullanılmıştır ancak bu metodun klasik delegate versiyonu da bulunmaktadır.
      BKMExpress.pay(
        token: token, // -> init işleminden elde edilen token.
        data: paymentData, // -> Ödeme işleminize dair bilgilerin tutulduğu veri yapısı.
        theme: theme, // -> SDK görünümünü özelleştirmek için kullanılan tema. Opsiyonel.
        style: .sheet, // -> SDK sunum şekli. Tam ekran için .fullScreen, sheet için .sheet kullanılabilir.
        on: self, // -> SDK'yı present edecek controller.
      ) { result in 
        // SDK sonucuna göre aksiyon alınır.
      }
    } catch {
      showAlert("BKM Express başlatılamadı.")
    }
  }
}

SwiftUI​

  1. BKM Express SDK'sı import edilir
import BKMExpressSDK
  1. BKMExpress.InitializationToken state'i optional view'ınıza (veya ViewModelinize) eklenir. 'bkmExpressPaymentSheet' view modifier'ına binding'i iletilir.
struct Screen: View {
  @State var bkmExpressToken: BKMExpress.InitializationToken?
  
  var body: some View {
    VStack {
      // view'ınızın içeriği
      Button("BKM Express ile ödeyin") {
        // ...
      }
    }
    .bkmExpressPaymentSheet(
      token: $bkmExpressToken, // -> init işleminden elde edilen token'ın binding'i.
      data: BKMExpress.PaymentData(...), // -> Ödeme işleminize dair bilgilerin tutulduğu veri yapısı.
      theme: { $0.buttonCornerRadius = .capsule }, // -> SDK'da kullanılacak varsayılan temayı değiştirmek için kullanılacak fonksiyon. Opsiyonel.
      style: .sheet, // -> SDK sunum şekli. Tam ekran için .fullScreen, sheet için .sheet kullanılabilir.
    ) { result in 
      // SDK sonucuna göre aksiyon alınır.
    }
  }
}
  1. Kendi sunucularınızdan entegrasyon sonucunda elde edeceğiniz tokenle birlikte 'InitializationContext' içerisinde istenen tüm bilgiler doldurulur ve 'init' çağrısı yapılır. Init çağrısından alınan token state'e atanır, böylelikle SDK başlamış olur.

SDK akışı herhangi bir nedenle tamamladığında kendini dismiss edip tokene otomatik olarak nil değerini set edecektir. Ekstra bir aksiyona gerek yoktur.

struct Screen: View {
  @State var bkmExpressToken: BKMExpress.InitializationToken?
  
  var body: some View {
    VStack {
      // view'ınızın içeriği
      Button("BKM Express kartınızı eşleştirin") {
        Task {
          do {
            bkmExpressToken = try await BKMExpress.initialize(
              context: .init(
                authToken: "", // -> Auth tokeniniz.
                merchantID: "", // -> Entegrasyon sonucunda size verilen merchant identifier'ınız.
                merchantUserID: "", // -> Kullanıcınızı tanımlamak için kullandığınız identifier.
                gsmNo: .init("5555555555") // -> Kullanıcınıza ait telefon numarası. Ayrı bir struct olduğu için kendi kurallarını işletir ve sadece verilen telefon numarası şartları sağladığında bir instance'ı yaratılabilir.
                mode: .development // -> SDK'nın modunu belirler. Test yaparken test veya preprod, uygulama kullanılırken production kullanılmalıdır. 
              ) 
            )
          } catch {
            showAlert("BKM Express başlatılamadı.")
          }
        }
      }
    }
    .bkmExpressCardSelectionSheet(
      token: $bkmExpressToken, // -> init işleminden elde edilen token'ın binding'i.
      theme: { $0.buttonCornerRadius = .capsule }, // -> SDK'da kullanılacak varsayılan temayı değiştirmek için kullanılacak fonksiyon. Opsiyonel.
      style: .sheet, // -> SDK sunum şekli. Tam ekran için .fullScreen, sheet için .sheet kullanılabilir.
    ) { result in 
      // SDK sonucuna göre aksiyon alınır.
    }
  }
}